cielogo

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 18, 2025 License: MIT Imports: 13 Imported by: 0

README

CI codecov Go Report Card Go Reference

CieloGo is a Go client library for interacting with the Cielo Finance API, allowing developers to easily access wallet analytics, pnl stats, related wallets, and wallet tags through a simple and intuitive interface. Built for efficiency and ease of use, CieloGo abstracts the complexity of direct API calls into straightforward Go functions.

Please note, CieloGo is an unofficial client library and is not endorsed or maintained by Cielo Finance.

Features

  • Transaction Feed - Get wallet or list transaction feeds with advanced filtering (chain, token, value range, market cap)
  • Portfolio Management - Retrieve wallet portfolios with token balances and USD values (single or multi-wallet)
  • Token Information - Access token metadata, real-time prices, statistics, and balances
  • PnL Analytics - Analyze NFT and token profit/loss with aggregated statistics and performance metrics
  • Trading Statistics - Get detailed trading performance stats including PnL, ROI, win rates, and more
  • Related Wallets - Discover wallets with transaction relationships and customizable sorting
  • Wallet Tracking - Full CRUD operations for tracked wallets with notification support (Telegram/Discord)
  • Wallet Tags - Tag wallets for organization and filter by custom or system tags
  • Wallet Lists - Create and manage wallet lists with follow/unfollow functionality
  • WebSocket Support - Real-time wallet activity monitoring via WebSocket connections

Installation

To use CieloGo in your Go project, install it as a module:

go get github.com/sealtv/cielogo

Usage

To start using CieloGo, import it into your Go project:

import "github.com/sealtv/cielogo"
Initializing the Client
client := cielogo.NewClient()
Making Requests

Here are some examples of how you might call various methods of the CieloGo client.

Get Feed:

ctx := context.Background()
req := &apiv1.FeedRequest{...} // setup your request
feed, err := client.GetFeedV1(ctx, req)

Get NFTs PnL:

nftsPnLReq := apiv1.NftsPnLRequest{Wallet: "0xWALLET_ADDRESS"}
nftsPnl, err := client.GetNftsPnlV1(ctx, &nftsPnLReq)

Get Tokens PnL:

tokensPnLReq := apiv1.TokensPnLRequest{Wallet: "0xWALLET_ADDRESS"}
tokensPnl, err := client.GetTokensPnlV1(ctx, &tokensPnLReq)

For more details on each request and response structure, refer to the Cielo Finance API documentation.

Breaking Changes

v0.x.x → v1.0.0
1. RelatedWallets Sorting Type Rename (Typo Fix)

Breaking Change: Type and constant names corrected from RelatedWalletsSoring to RelatedWalletsSorting.

Migration:

// Before:
sortCriteria := apiv1.RelatedWalletsSoringInflowDesc

// After:
sortCriteria := apiv1.RelatedWalletsSortingInflowDesc

All Constants Renamed:

  • RelatedWalletsSoringInflowAsc → RelatedWalletsSortingInflowAsc
  • RelatedWalletsSoringInflowDesc → RelatedWalletsSortingInflowDesc
  • RelatedWalletsSoringOutflowAsc → RelatedWalletsSortingOutflowAsc
  • RelatedWalletsSoringOutflowDesc → RelatedWalletsSortingOutflowDesc
  • RelatedWalletsSoringTransactionsAsc → RelatedWalletsSortingTransactionsAsc
  • RelatedWalletsSoringTransactionsDesc → RelatedWalletsSortingTransactionsDesc

Automated Fix:

find . -type f -name "*.go" -exec sed -i 's/RelatedWalletsSoring/RelatedWalletsSorting/g' {} +
2. DeleteWalletsListV1 Signature Change

Breaking Change: New required deleteWallets parameter controls cascade deletion.

Migration:

// Before:
err := client.DeleteWalletsListV1(ctx, listID)

// After (preserve wallets):
err := client.DeleteWalletsListV1(ctx, listID, false)

// Or (delete wallets too):
err := client.DeleteWalletsListV1(ctx, listID, true)

Default Behavior: Pass false to maintain backward compatibility (delete list only, keep wallets).

API Credits

All API endpoints consume credits from your Cielo Finance account. Below is a comprehensive cost table:

Endpoint Cost (Credits) Notes
Feed & PnL
GetFeedV1 5 (3 with wallet filter) 10/6 with IncludeMarketCap=true ⚠️
GetNftsPnlV1 5
GetTokensPnlV1 5
GetAggregatedTokenPnLV1 20 Expensive operation
Portfolio & Token Info
GetWalletPortfolioV1 20
GetWalletPortfolioV2 20 per wallet
GetTokenMetadataV1 1
GetTokenPriceV1 1
GetTokenStatsV1 3
GetTokenBalanceV1 3
Trading Stats
GetTradingStatsV1 30 Most expensive, may return 202 Accepted
Related Wallets
GetRelatedWalletsV1 10
Tags
GetWalletTagsV1 5 Deprecated, use GetWalletsTagsV1
GetWalletsTagsV1 5 Batch operation (up to 50 wallets)
GetWalletsByTagV1 10
Lists
GetAllWalletsListsV1 5
GetUserWalletsListsV1 5
AddWalletsListV1 5
UpdateWalletsListV1 5
DeleteWalletsListV1 5
ToggleFollowWalletsListV1 5
Tracked Wallets
GetTrackedWalletsV1 5
AddTrackedWalletsV1 5
RemoveTrackedWalletsV1 5
GetWalletByAddressV1 5
UpdateTrackedWalletV1 5 By ID (full update)
UpdateTrackedWalletV2 5 By address (partial update)
GetTelegramBotsV1 5
Cost Optimization Tips
  1. Use batch operations - GetWalletsTagsV1 supports up to 50 wallets for 5 credits (vs 5 credits per wallet)
  2. Filter feeds by wallet - Reduces cost from 5 to 3 credits
  3. Avoid IncludeMarketCap unless necessary - Doubles feed costs (5→10 or 3→6)
  4. Cache expensive results - Portfolio (20 credits) and Trading Stats (30 credits) change infrequently
  5. Use V2 partial updates - UpdateTrackedWalletV2 allows updating specific fields without full replacement

Contributing

Contributions to the CieloGo project are welcome. Please feel free to report any bugs, suggest features, or open pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(apiKey string, opts ...ClientOption) *Client

func (*Client) AddTrackedWalletsV1 added in v0.1.6 

func (c *Client) AddTrackedWalletsV1(ctx context.Context, req *apiv1.AddTrackedWalletRequest) (*apiv1.TrackedWallet, error)

AddTrackedWalletsV1 adds a new wallet to tracking with optional notification settings.

Cost: 5 credits per request

https://developer.cielo.finance/reference/addtrackedwallet

func (*Client) AddWalletsListV1 added in v0.1.6 

func (c *Client) AddWalletsListV1(ctx context.Context, req *apiv1.AddWalletsListRequest) (*apiv1.WalletList, error)

AddWalletsListV1 creates a new wallet list.

Cost: 5 credits per request

https://developer.cielo.finance/reference/adduserlist

func (*Client) DeleteWalletsListV1 added in v0.1.6 

func (c *Client) DeleteWalletsListV1(ctx context.Context, listID int64, deleteWallets bool) error

DeleteWalletsListV1 deletes a wallet list. If deleteWallets is true, all wallets in the list will also be deleted. If deleteWallets is false, only the list itself is deleted, wallets are preserved.

Cost: 5 credits per request

https://developer.cielo.finance/reference/deleteuserlist

func (*Client) GetAggregatedTokenPnLV1 

func (c *Client) GetAggregatedTokenPnLV1(ctx context.Context, req *apiv1.AggregatedTokenPnLRequest) (*apiv1.AggregatedTokenPnLResponse, error)

GetAggregatedTokenPnLV1 retrieves aggregated token statistics and performance metrics for a wallet.

Cost: 20 credits per request

https://developer.cielo.finance/reference/gettotalstats

func (*Client) GetAllWalletsListV1 added in v0.1.6 

func (c *Client) GetAllWalletsListV1(ctx context.Context, req *apiv1.GetAllWalletsListsRequest) (*apiv1.GetAllWalletsListsResponse, error)

GetAllWalletsListV1 retrieves all public wallet lists with optional filtering and sorting.

Cost: 5 credits per request

https://developer.cielo.finance/reference/getalllists

func (*Client) GetFeedV1 

func (c *Client) GetFeedV1(ctx context.Context, req *apiv1.FeedRequest) (*apiv1.FeedResponse, error)

GetFeedV1 retrieves the transaction feed for a wallet or list.

Cost: 5 credits per request (3 credits when filtered by wallet). WARNING: Setting IncludeMarketCap to true doubles the cost (10 or 6 credits).

Example: 

// Get feed with new MaxUSD filter and market cap data
maxUSD := 100000.0
includeMarketCap := true
feed, err := client.GetFeedV1(ctx, &apiv1.FeedRequest{
	ListID:           apiv1.ToRef(int64(123)),
	MaxUSD:           &maxUSD,
	IncludeMarketCap: &includeMarketCap, // WARNING: Doubles credit cost
})

https://developer.cielo.finance/reference/getfeed

func (*Client) GetNftsPnlV1 

func (c *Client) GetNftsPnlV1(ctx context.Context, req *apiv1.NftsPnLRequest) (*apiv1.NftsPnLResponse, error)

GetNftsPnlV1 retrieves NFT profit and loss data for a wallet.

Cost: 5 credits per request

https://developer.cielo.finance/reference/getnftspnl

func (*Client) GetRelatedWalletsV1 

func (c *Client) GetRelatedWalletsV1(ctx context.Context, req *apiv1.RelatedWalletsRequest) (*apiv1.RelatedWalletsResponse, error)

GetRelatedWalletsV1 finds wallets that have transacted with the specified wallet.

Cost: 10 credits per request

https://developer.cielo.finance/reference/getrelatedwalletsl

func (*Client) GetTelegramBotsV1 added in v0.2.0 

func (c *Client) GetTelegramBotsV1(ctx context.Context) (*apiv1.GetTelegramBotsResponse, error)

GetTelegramBotsV1 retrieves the list of available Telegram bots for notifications. Only returns bots where available=true.

Cost: 5 credits per request

https://developer.cielo.finance/reference/getTelegramBots

func (*Client) GetTokenBalanceV1 added in v0.2.0 

func (c *Client) GetTokenBalanceV1(ctx context.Context, req *apiv1.TokenBalanceRequest) (*apiv1.TokenBalanceResponse, error)

GetTokenBalanceV1 retrieves the balance of a specific token for a given wallet, including the token's current price and total USD value.

Supported chains: solana, ethereum, base, hyperevm Cost: 3 credits per request

https://developer.cielo.finance/reference/getTokenBalance

func (*Client) GetTokenMetadataV1 added in v0.2.0 

func (c *Client) GetTokenMetadataV1(ctx context.Context, req *apiv1.TokenMetadataRequest) (*apiv1.TokenMetadataResponse, error)

GetTokenMetadataV1 retrieves detailed metadata for a specified token including name, symbol, decimals, creation details, social links, and supply information.

Supported chains: solana, ethereum, base, hyperevm Cost: 1 credit per request

https://developer.cielo.finance/reference/getTokenMetadata

func (*Client) GetTokenPriceV1 added in v0.2.0 

func (c *Client) GetTokenPriceV1(ctx context.Context, req *apiv1.TokenPriceRequest) (*apiv1.TokenPriceResponse, error)

GetTokenPriceV1 retrieves the current price in USD for a specified token.

Supported chains: solana, ethereum, base, hyperevm Cost: 1 credit per request

https://developer.cielo.finance/reference/getTokenPrice

func (*Client) GetTokenStatsV1 added in v0.2.0 

func (c *Client) GetTokenStatsV1(ctx context.Context, req *apiv1.TokenStatsRequest) (*apiv1.TokenStatsResponse, error)

GetTokenStatsV1 retrieves comprehensive statistics for a specified token including price changes, volume metrics, market cap, and unique trader counts across multiple time periods (5m, 1h, 6h, 24h).

Supported chains: solana, ethereum, base, hyperevm Cost: 3 credits per request

https://developer.cielo.finance/reference/getTokenStats

func (*Client) GetTokensPnlV1 

func (c *Client) GetTokensPnlV1(ctx context.Context, req *apiv1.TokensPnLRequest) (*apiv1.TokensPnLResponse, error)

GetTokensPnlV1 retrieves token profit and loss data for a wallet.

Cost: 5 credits per request

Example: 

// Get only active positions (balance > 0)
pnl, err := client.GetTokensPnlV1(ctx, &apiv1.TokensPnLRequest{
	Wallet:              "0x1234...",
	ActivePositionsOnly: apiv1.ToRef(true),
})

https://developer.cielo.finance/reference/gettokenspnl

func (*Client) GetTrackedWalletsV1 added in v0.1.6 

func (c *Client) GetTrackedWalletsV1(ctx context.Context, req *apiv1.GetTrackedWalletsRequest) (*apiv1.GetTrackedWalletsResponse, error)

GetTrackedWalletsV1 retrieves all wallets being tracked by the user, with optional filtering by list.

Cost: 5 credits per request

https://developer.cielo.finance/reference/gettrackedwallets

func (*Client) GetTradingStatsV1 added in v0.2.0 

func (c *Client) GetTradingStatsV1(ctx context.Context, req *apiv1.TradingStatsRequest) (*apiv1.TradingStatsResponse, error)

GetTradingStatsV1 retrieves detailed performance statistics for a wallet's trading activity, including PnL, ROI, win rate, and trading behavior insights.

Note: This endpoint may return 202 Accepted if data is not ready yet. In that case, retry the request after 10 seconds.

Cost: 30 credits per request

Example: 

stats, err := client.GetTradingStatsV1(ctx, &apiv1.TradingStatsRequest{
	Wallet: "0x1234...",
	Chain:  apiv1.ToRef(chains.Ethereum),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Total PnL: $%.2f | Win Rate: %.1f%%\n",
	stats.TotalPnL, stats.WinRate*100)

https://developer.cielo.finance/reference/getTradingStats

func (*Client) GetUserWalletsListsV1 added in v0.1.6 

func (c *Client) GetUserWalletsListsV1(ctx context.Context) ([]apiv1.WalletList, error)

GetUserWalletsListsV1 retrieves all wallet lists owned by the authenticated user.

Cost: 5 credits per request

https://developer.cielo.finance/reference/getuserlists

func (*Client) GetWalletByAddressV1 added in v0.2.0 

func (c *Client) GetWalletByAddressV1(ctx context.Context, wallet string) (*apiv1.TrackedWallet, error)

GetWalletByAddressV1 retrieves a tracked wallet by its wallet address. Returns 404 if the wallet is not being tracked.

Cost: 5 credits per request

https://developer.cielo.finance/reference/getWalletByAddress

func (*Client) GetWalletPortfolioV1 added in v0.2.0 

func (c *Client) GetWalletPortfolioV1(ctx context.Context, wallet string) (*apiv1.WalletPortfolioResponse, error)

GetWalletPortfolioV1 retrieves the portfolio of a wallet including token balances and USD values. For Solana wallets, the response also includes the native SOL balance. Portfolio assets with a total_usd_value of zero are excluded from the response.

Supported chains: Solana, EVM (Ethereum, Base, HyperEVM) Cost: 20 credits per request

Example: 

portfolio, err := client.GetWalletPortfolioV1(ctx, "0x1234...")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Total USD: $%.2f\n", portfolio.TotalUSD)
for _, token := range portfolio.Tokens {
	fmt.Printf("%s: %.2f (%s)\n", token.Symbol, token.Balance, token.TotalUSDValue)
}

https://developer.cielo.finance/reference/getWalletPortfolio

func (*Client) GetWalletPortfolioV2 added in v0.2.0 

func (c *Client) GetWalletPortfolioV2(ctx context.Context, req *apiv1.WalletPortfolioV2Request) (*apiv1.WalletPortfolioV2Response, error)

GetWalletPortfolioV2 retrieves the portfolio of one or multiple wallets with optional token filtering. Supports comma-separated wallet addresses for aggregated portfolio view. Each token in the response includes a wallet_address field indicating which wallet holds it.

When a token parameter is provided (Solana wallets only):

  • Only supported for Solana wallets - returns error for EVM/Sui wallets
  • Returns only the specified token's balance information
  • Response format changes to a single token object instead of portfolio object
  • Returns 404 if the token is not found in the wallet

When multiple wallets are provided:

  • Token filtering is not supported and will return an error
  • Portfolios are fetched in parallel for better performance
  • Tokens are sorted by total_usd_value in descending order
  • Total USD and chain distributions are aggregated across all wallets

Supported chains: Solana, EVM (Ethereum, Base, HyperEVM), Sui Cost: 20 credits per wallet

Example (aggregated multi-wallet portfolio): 

portfolio, err := client.GetWalletPortfolioV2(ctx, &apiv1.WalletPortfolioV2Request{
	Wallets: []string{"0x1111...", "0x2222...", "0x3333..."},
})
// Cost: 60 credits (20 per wallet)

https://developer.cielo.finance/reference/getWalletPortfolioV2

func (*Client) GetWalletTagsV1 deprecated 

func (c *Client) GetWalletTagsV1(ctx context.Context, req *apiv1.GetWalletTagsRequest) (*apiv1.GetWalletTagsResponse, error)

GetWalletTagsV1 retrieves tags for a single wallet.

Deprecated: This endpoint is deprecated by the Cielo Finance API. Use GetWalletsTagsV1 instead, which supports batch operations for up to 50 wallets.

Cost: 5 credits per request

https://developer.cielo.finance/reference/getwallettags

func (*Client) GetWalletsByTagV1 added in v0.1.2 

func (c *Client) GetWalletsByTagV1(ctx context.Context, req *apiv1.GetWalletsByTagRequest) (*apiv1.GetWalletsByTagResponse, error)

GetWalletsByTagV1 retrieves all wallets that have a specific tag.

Cost: 10 credits per request

https://developer.cielo.finance/reference/getwalletsbytag

func (*Client) GetWalletsTagsV1 added in v0.1.6 

func (c *Client) GetWalletsTagsV1(ctx context.Context, req *apiv1.GetWalletsTagsRequest) ([]apiv1.WalletTags, error)

GetWalletsTagsV1 retrieves tags for multiple wallets in a single request (up to 50 wallets).

Cost: 5 credits per request

https://developer.cielo.finance/reference/getwalletstags

func (*Client) NewWebsocketConnection added in v0.1.5 

func (c *Client) NewWebsocketConnection(ctx context.Context, opts ...WebsocketOption) (*WebsocketClient, error)

func (*Client) RemoveTrackedWalletsV1 added in v0.1.6 

func (c *Client) RemoveTrackedWalletsV1(ctx context.Context, req *apiv1.RemoveTrackedWalletsRequest) error

RemoveTrackedWalletsV1 removes one or more wallets from tracking by their IDs.

Cost: 5 credits per request

https://developer.cielo.finance/reference/removetrackedwallets

func (*Client) ToggleFollowWalletsListV1 added in v0.1.6 

func (c *Client) ToggleFollowWalletsListV1(ctx context.Context, listID int64) (*apiv1.ToggleFollowWalletsListResponce, error)

ToggleFollowWalletsListV1 toggles the follow status of a public wallet list.

Cost: 5 credits per request

https://developer.cielo.finance/reference/togglefollowlist

func (*Client) UpdateTrackedWalletV1 added in v0.2.0 

func (c *Client) UpdateTrackedWalletV1(ctx context.Context, walletID int64, req *apiv1.UpdateTrackedWalletRequest) (*apiv1.TrackedWallet, error)

UpdateTrackedWalletV1 updates a tracked wallet by its wallet ID.

Cost: 5 credits per request

https://developer.cielo.finance/reference/updateTrackedWalletV1

func (*Client) UpdateTrackedWalletV2 added in v0.2.0 

func (c *Client) UpdateTrackedWalletV2(ctx context.Context, wallet string, req *apiv1.UpdateTrackedWalletV2Request) (*apiv1.TrackedWallet, error)

UpdateTrackedWalletV2 updates a tracked wallet by its wallet address with support for partial updates. All fields are optional and only provided fields will be updated.

Cost: 5 credits per request

Example: 

// Update only notification settings (partial update)
updated, err := client.UpdateTrackedWalletV2(ctx, "0x1234...", &apiv1.UpdateTrackedWalletV2Request{
	MinUSD:         apiv1.ToRef(1000.0),
	TelegramBot:    apiv1.ToRef("my_bot"),
	DiscordChannel: apiv1.ToRef("webhook_url"),
})

https://developer.cielo.finance/reference/updateTrackedWalletV2

func (*Client) UpdateWalletsListV1 added in v0.1.6 

func (c *Client) UpdateWalletsListV1(ctx context.Context, req *apiv1.UpdateWalletsListRequest) (*apiv1.WalletList, error)

UpdateWalletsListV1 updates an existing wallet list's properties.

Cost: 5 credits per request

https://developer.cielo.finance/reference/updateuserlist

type ClientOption added in v0.2.0 

type ClientOption func(*Client)

ClientOption is a function that configures a Client

func WithBaseURL added in v0.2.0 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets a custom base URL (useful for testing)

func WithHTTPClient added in v0.2.0 

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client

type WebsocketClient added in v0.1.5 

type WebsocketClient struct {
	// contains filtered or unexported fields
}

func (*WebsocketClient) Close added in v0.1.5 

func (ws *WebsocketClient) Close()

func (*WebsocketClient) RunListener added in v0.1.5 

func (ws *WebsocketClient) RunListener(ctx context.Context, out chan<- apiv1.WSEvent) error

func (*WebsocketClient) SendCommand added in v0.1.5 

func (ws *WebsocketClient) SendCommand(cmd apiv1.WebSocketsCommand) error

type WebsocketOption added in v0.1.5 

type WebsocketOption func(*WebsocketClient)

func WithCloseHandler added in v0.1.5 

func WithCloseHandler(h func(code int, text string) error) WebsocketOption

func WithDeadline added in v0.1.5 

func WithDeadline(t time.Time) WebsocketOption

func WithPingHandler added in v0.1.5 

func WithPingHandler(h func(appData string) error) WebsocketOption

func WithPongHandler added in v0.1.5 

func WithPongHandler(h func(appData string) error) WebsocketOption

Source Files

View all Source files

Directories

Path Synopsis
api
apiv1
chains
examples
complete_workflow command
portfolio command
tracked_wallets command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.