# cielo-api Documentation > Cielo API documentation ## Guides - [Getting Started and Pricing](https://developer.cielo.finance/docs/getting-started.md): This page will help you get started with cielo-api. You'll be up and running quickly - [Getting an API key](https://developer.cielo.finance/docs/getting-an-api-key.md) - [Endpoints Accessibility by Plan](https://developer.cielo.finance/docs/endpoints-accessibility-by-plan.md): This table outlines the available API endpoints, indicating which subscription plans (Free, Builder, Architect) have access to each endpoint and the corresponding credit cost per use. - [Fetch Transaction Feed](https://developer.cielo.finance/docs/fetch-feed.md) - [Supported Chains](https://developer.cielo.finance/docs/supported-chains.md) - [Supported Transaction Types](https://developer.cielo.finance/docs/supported-on-chain-transaction-types.md) - [Fetch latest transaction via WebSocket](https://developer.cielo.finance/docs/fetch-latest-transaction-via-websocket.md) - [List of Chain IDs](https://developer.cielo.finance/docs/list-of-chain-ids.md) - [List of Transaction Type IDs](https://developer.cielo.finance/docs/list-of-transaction-type-ids.md) ## API Reference - [Feed](https://developer.cielo.finance/reference/getfeed.md): This endpoint retrieves a feed of transactions based on specified query parameters. When set to true, the response will include the market capitalization of tokens, as well as liquidity swap and transfer events. Note that enabling this option will double the cost per request to 10 credits. If the query is filtered by wallet address, the cost will increase to 6 credits per request. ### Filters - **Wallet Address**: Filter transactions by wallet address. - **Number of Transactions (limit)**: Specify the number of transactions to retrieve. - **Specific Lists**: Filter transactions by specific lists. - **Chains**: Filter transactions by chains. - **Transaction Types**: Filter transactions by transaction types. - **Tokens**: Filter transactions by tokens. - **Minimum USD Value**: Filter transactions by minimum USD value. - **Maximum USD Value**: Filter transactions by maximum USD value. - **Starting Point**: Specify the starting point of the feed. - **New Trades**: Filter transactions by new trades. ### Supported Chains - All EVM chains - Solana ### Cost - **Cost per request**: 5 credits - **When filtered by wallet address**: 3 credits ### Available Plans Available on the following plans: - Free - Builder - Architect - Enterprise - [Token PNL](https://developer.cielo.finance/reference/gettokenspnl.md): This endpoint retrieves a PnL values for a specified wallet by different tokens. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Related Wallets](https://developer.cielo.finance/reference/getrelatedwallets.md): This endpoint retrieves a list of wallets related to the specified wallet address. Related wallets are determined based on shared activity, such as token transfers, NFT trades, or participation in DeFi protocols. ### Cost per Request Cost per request = 10 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [NFT PNL](https://developer.cielo.finance/reference/getnftspnl.md): This endpoint retrieves the PnL value for an NFT collection on Ethereum. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Aggregated Token PNL](https://developer.cielo.finance/reference/gettotalstats.md): This endpoint retrieves aggregated PnL stats for a specified wallet. ### Cost per Request Cost per request = 20 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Trading Stats](https://developer.cielo.finance/reference/gettradingstats.md): Detailed performance statistics for a wallet's trading activity, including PnL, ROI, win rate, and trading behavior insights. ### Cost per Request Cost per request = 30 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Wallet Portfolio](https://developer.cielo.finance/reference/getwalletportfolio.md): Retrieve the portfolio of a wallet. For Solana wallets, the response also includes the native SOL balance. Portfolio assets with a total_usd_value of zero are not included in the response. Available chains: - Solana - EVM (Ethereum, Base, HyperEVM) ### Cost per Request Cost per request = 20 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Token Balance](https://developer.cielo.finance/reference/gettokenbalance.md): Retrieve the token balance for a wallet. Available chains: - Solana - EVM (Ethereum, Base, HyperEVM) ### Cost per Request Cost per request = 3 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Wallet Portfolio (Multi-Wallet Support)](https://developer.cielo.finance/reference/getwalletportfoliov2.md): Retrieve 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. For Solana wallets, the response also includes the native SOL balance. Portfolio assets with a total_usd_value of zero are not included in the response. 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 - Uses optimized RPC call to fetch only the specified token 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 - If some wallets fail, data for successful wallets is still returned Available chains: - Solana - EVM (Ethereum, Base, HyperEVM) - Sui ### Cost per Request Cost per request = 20 credits per wallet. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Token Flows V2](https://developer.cielo.finance/reference/gettokenflowsv2.md): Aggregated token flow data (buys, sells, net flow) across your tracked wallets — the wallet list belonging to the account that owns this API key. Includes platform information for Solana tokens. The caller's wallet is derived server-side from the API key — clients do not need to provide it via a header. ### Cost per Request Cost per request = 5 credits. ### Available Plans - Builder - Architect - Enterprise - [New Token Flows](https://developer.cielo.finance/reference/getnewtokenflows.md): Aggregated token flow data for recently created tokens (within the last 24 hours) across your tracked wallets — the wallet list belonging to the account that owns this API key. Includes platform information for Solana tokens. The caller's wallet is derived server-side from the API key — clients do not need to provide it via a header. ### Cost per Request Cost per request = 5 credits. ### Available Plans - Builder - Architect - Enterprise - [Enhanced Aggregated Stats](https://developer.cielo.finance/reference/getwalletenhancedaggregatedstats.md): This endpoint retrieves enhanced aggregated trading statistics for a specified wallet, including trade counts, buy/sell amounts, DEX distribution, holding times, and most traded tokens. ### Cost per Request Cost per request = 20 credits. ### Available Plans Available on the following plans: - Whale - Builder - Architect - Enterprise - [Profitability & Performance Stats](https://developer.cielo.finance/reference/getwalletprofitabilityandperformance.md): This endpoint retrieves profitability and performance statistics for a specified wallet, including win/loss trades, win rate, max profit/drawdown, win streaks, and holding distribution. ### Cost per Request Cost per request = 20 credits. ### Available Plans Available on the following plans: - Whale - Builder - Architect - Enterprise - [Enhanced Aggregated Stats V2](https://developer.cielo.finance/reference/getwalletenhancedaggregatedstatsv2.md): This endpoint retrieves enhanced aggregated trading statistics with support for multi-bundle wallets via the multi_bundle_id parameter. ### Cost per Request Cost per request = 25 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [PnL Tokens Chart](https://developer.cielo.finance/reference/gettokenspnlchart.md): This endpoint retrieves PnL time series chart data for a specified wallet, showing profit/loss over time with ROI calculations. ### Cost per Request Cost per request = 15 credits. ### Available Plans Available on the following plans: - Whale - Builder - Architect - Enterprise - [Monthly PnL](https://developer.cielo.finance/reference/getmonthlypnl.md): This endpoint retrieves monthly PnL data for a specified wallet, showing profit/loss aggregated by month. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Whale - Builder - Architect - Enterprise - [Tags](https://developer.cielo.finance/reference/getwallettags.md): # This endpoint is deprecated. Please use the `/api/v1/tags` endpoint instead. This endpoint retrieves tags associated with a specific wallet address. Tags provide insights into wallet activity, such as NFT trading volume or participation in DeFi protocols. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Wallets Tags](https://developer.cielo.finance/reference/getwalletstags.md): This endpoint retrieves tags associated with a specific wallet address. Tags provide insights into wallet activity. Note, tags will only be returned for wallets indexed by the Cielo engine. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Wallets by Tag](https://developer.cielo.finance/reference/getwalletsbytag.md): This endpoint retrieves wallets associated with a specific tag. Tags provide insights into wallet activity. ### Cost per Request Cost per request = 10 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [WebSocket Connection](https://developer.cielo.finance/reference/getwebsocket.md): This endpoint sets up a WebSocket connection to receive updates on new transactions. Once connected, the client can send command messages to the WebSocket in the following formats: ### Subscribe to a feed: Refer to the `FeedSubscribeCommand` schema for the command structure. #### Subscribe to all feed events: ```json { "type": "subscribe_feed", } ``` #### Subscribe to feed with filters. Filters tx_types, chains, tokens, min_usd_value, new_trade are optional: ```json { "type": "subscribe_feed", "filter": { "tx_types": ["transfer", "swap"], "chains": ["eth", "bsc"], "tokens": ["0x1234", "0x5678"], "min_usd_value": 1000, "new_trade": true } } ``` #### Subscribe to feed for an new trades: ```json { "type": "subscribe_feed", "filter": { "new_trade": true } } ``` ### Subscribe to feed for a certain list: ```json { "type": "subscribe_feed", "list_id": 12345 } ``` ### Unsubscribe from a feed: Refer to the `FeedUnsubscribeCommand` schema for the command structure. ```json { "type": "unsubscribe_feed" } ``` ### Subscribe to a wallet: Refer to the `WalletSubscribeCommand` schema for the command structure. #### Subscribe to all wallet events: ```json { "type": "subscribe_wallet", "wallet": "wallet-address", } ``` #### Subscribe to wallet events with filters. Filters tx_types, chains, tokens, min_usd_value, new_trade are optional: ```json { "type": "subscribe_wallet", "wallet": "wallet-address", "filter": { "tx_types": ["transfer", "swap"], "chains": ["ethereum", "bsc"], "tokens": ["0x1234", "0x5678"], "min_usd_value": 1000, "new_trade": true } } ``` ### Unsubscribe from a wallet: Refer to the `WalletUnsubscribeCommand` schema for the command structure. ```json { "type": "unsubscribe_wallet", "wallet": "wallet-address" } ``` The server will send back messages in the following schema: ### Websocket Event Message: Refer to the `WebsocketEvent` schema for the message structure. ```json { "type": "event_type", "data": {} } ``` ### Supported Chains The `chains` filter accepts the same chain identifiers used by the REST API. The authoritative live list is available at `GET /api/v1/chains` — any value not in that list will be rejected by the server when the command is validated. ### Pricing Information Every 10 messages sent over the WebSocket connection consume 1 credit. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Get all wallets lists](https://developer.cielo.finance/reference/getalllists.md): This endpoint retrieves public wallets lists. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Get all lists for a user](https://developer.cielo.finance/reference/getuserlists.md): This endpoint retrieves user's wallets lists. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Add a list](https://developer.cielo.finance/reference/adduserlist.md): This endpoint creates a new list for a user. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Update a list](https://developer.cielo.finance/reference/updateuserlist.md): This endpoint updates a user's list. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Delete a list](https://developer.cielo.finance/reference/deleteuserlist.md): This endpoint deletes a user's list. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Toggle follow a list](https://developer.cielo.finance/reference/togglefollowlist.md): This endpoint toggles follow a list for a user. ### Cost per Request Cost per request = 5 credits. ### Available Plans Available on the following plans: - Builder - Architect - Enterprise - [Token metadata](https://developer.cielo.finance/reference/gettokenmetadata.md): This endpoint retrieves metadata for a specific token. ### Cost per Request Cost per request = 2 credits. ### Available Plans: - Builder - Architect - Enterprise - [Token price](https://developer.cielo.finance/reference/gettokenprice.md): This endpoint retrieves price for a specific token. ### Cost per Request Cost per request = 2 credits. ### Available Plans: - Builder - Architect - Enterprise - [Token stats](https://developer.cielo.finance/reference/gettokenstats.md): This endpoint retrieves stats of a specified token. ### Cost per Request Cost per request = 10 credits. ### Available Plans: - Builder - Architect - Enterprise - [Trending tokens](https://developer.cielo.finance/reference/gettrendingtokens.md): This endpoint retrieves the top trending tokens by unique wallet activity for the specified chain and interval. ### Cost per Request Cost per request = 20 credits. ### Available Plans: - Builder - Architect - Enterprise - [Token checklist](https://developer.cielo.finance/reference/gettokenchecklist.md): This endpoint retrieves safety and distribution checklist data for a specific token. ### Cost per Request Cost per request = 1 credits. ### Available Plans: - Builder - Architect - Enterprise - [Get Wallet By Address](https://developer.cielo.finance/reference/getwalletbyaddress.md): This endpoint retrieves a wallet by its address. Plans Included = Free, Builder, Architect Cost per request = 5 credits. - [Get Tracked Wallets](https://developer.cielo.finance/reference/gettrackedwallets.md): This endpoint retrieves a list of wallets that are being tracked. Tracked wallets are wallets that are being monitored for activity, such as token transfers, NFT trades, or participation in DeFi protocols. Plans Included = Free, Builder, Architect Cost per request = 5 credits. - [Add Tracked Wallet](https://developer.cielo.finance/reference/addtrackedwallet.md): This endpoint adds a wallet to the list of tracked wallets. Tracked wallets are wallets that are being monitored for activity, such as token transfers, NFT trades, or participation in DeFi protocols. You can optionally configure notification settings including: - Telegram bot assignment for real-time alerts - Discord channel integration - Minimum USD threshold for notifications - Specific transaction types and chains to monitor Plans Included = Free, Builder, Architect Cost per request = 5 credits. - [Remove Tracked Wallets](https://developer.cielo.finance/reference/removetrackedwallets.md): This endpoint removes a wallet from the list of tracked wallets. Tracked wallets are wallets that are being monitored for activity, such as token transfers, NFT trades, or participation in DeFi protocols. Plans Included = Free, Builder, Architect Cost per request = 5 credits. - [Update Tracked Wallet](https://developer.cielo.finance/reference/updatetrackedwallet.md): This endpoint updates a tracked wallet. Tracked wallets are wallets that are being monitored for activity, such as token transfers, NFT trades, or participation in DeFi protocols. Plans Included = Free, Builder, Architect Cost per request = 5 credits. - [Update Tracked Wallet v2](https://developer.cielo.finance/reference/updatetrackedwalletv2.md): This endpoint updates a specified tracked wallet. - [Get Available Telegram Bots](https://developer.cielo.finance/reference/gettelegrambots.md): This endpoint returns a list of all available Telegram bots that can be used for wallet notifications when adding or updating tracked wallets. Only bots that are available (available=true) are included in the response. This includes both enabled and disabled bots. Each bot has a unique ID that should be used in the telegram_bot_id field when configuring wallet notifications. Plans Included = Builder, Architect, Whale Cost per request = 5 credits. - [Get Trading Wallets](https://developer.cielo.finance/reference/gettradingwallets.md): Returns a list of trading wallets for the authenticated user. Trading wallets are custodial wallets used for executing trades through Cielo's trading infrastructure. Plans Included = Basic, Whale, ApiBasic, Builder, Architect, Enterprise Cost per request = 5 credits. - [Set Default Trading Wallet](https://developer.cielo.finance/reference/setdefaulttradingwallet.md): Sets a specific trading wallet as the user's default wallet. Plans Included = Basic, Whale, ApiBasic, Builder, Architect, Enterprise Cost per request = 2 credits. - [Rename Trading Wallet](https://developer.cielo.finance/reference/updatetradingwalletname.md): Updates the display name of a trading wallet. Plans Included = Basic, Whale, ApiBasic, Builder, Architect, Enterprise Cost per request = 2 credits. - [Get Default Trading Wallet](https://developer.cielo.finance/reference/getdefaulttradingwallet.md): Returns the default trading wallet for the specified chain. Plans Included = Basic, Whale, ApiBasic, Builder, Architect, Enterprise Cost per request = 5 credits. - [Supported Chains](https://developer.cielo.finance/reference/getchains.md): Returns the list of blockchain networks currently supported by the Cielo API. The list is the authoritative source for the `chains` query parameter used across endpoints such as `/api/v1/feed` and the WebSocket `subscribe_feed` / `subscribe_wallet` commands — any value not in this list will be rejected with `400 invalid chain`. ### Cost - **Cost per request**: 0 credits (this endpoint is free; requests are not deducted from your API credit quota) ### Available Plans Available on all plans: - Free - Builder - Architect - Enterprise - [Get Solana Swap Quote (v2)](https://developer.cielo.finance/reference/getsolanaquotev2.md): Fetches a quote for buying or selling tokens on Solana. For buy: swaps the chosen collateral (SOL or USDC) for the specified token. For sell: swaps the specified token for the chosen collateral (SOL or USDC). Plans Included = Builder, Architect, Enterprise Cost per request = 5 credits. - [Execute Solana Swap (v2)](https://developer.cielo.finance/reference/executesolanaswapv2.md): Executes a token swap on Solana using the v2 API. The collateral parameter chooses between SOL (default) and USDC as the trading asset. Either amount or amount_raw must be provided. Requires X-API-KEY header. Plans Included = Builder, Architect, Enterprise Cost per request = 10 credits. - [Get Base Chain Swap Quote](https://developer.cielo.finance/reference/getbasequote.md): Fetches a quote for buying or selling tokens on Base chain. Amount is human-readable. Collateral can be "usdc" (default) or "eth". Plans Included = Builder, Architect, Enterprise Cost per request = 5 credits. - [Execute Base Chain Swap](https://developer.cielo.finance/reference/executebaseswap.md): Executes a token swap on Base chain. Amount is human-readable. Collateral determines which token is used as payment (buy) or received (sell). Slippage is in basis points (50 = 0.5%). Requires both X-API-KEY and Authorization Bearer token. Plans Included = Builder, Architect, Enterprise Cost per request = 10 credits.