> For the complete documentation index, see [llms.txt](https://docs.cielo.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cielo.finance/api-reference/token.md).

# Token

Token metadata, prices, market stats, liquidity, safety checklist and trending tokens.

## Token metadata

> This endpoint retrieves metadata for a specific token.\
> \### Cost per Request\
> Cost per request = 2 credits.\
> \### Available Plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"TokenMetadataResponse":{"type":"object","description":"Token metadata response","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the standard response status object, which indicates the success or failure of the API request."},"data":{"type":"object","description":"Contains token metadata information.","properties":{"chain":{"type":"string","description":"The blockchain network on which the token is deployed."},"address":{"type":"string","description":"The address of the token contract."},"name":{"type":"string","description":"The name of the token."},"symbol":{"type":"string","description":"The symbol of the token."},"decimals":{"type":"integer","description":"The number of decimal places used by the token."},"created_at_ts":{"type":"integer","description":"Timestamp when the token was created."},"created_at_block":{"type":"integer","description":"Block number when the token was created."},"twitter":{"type":"string","description":"Official Twitter account of the project."},"telegram":{"type":"string","description":"Official Telegram channel for the project."},"website":{"type":"string","description":"Official website of the project."},"supply":{"type":"integer","description":"The total supply of the token."},"logo_uri":{"type":"string","description":"The URI of the token's logo."},"migrated_at":{"type":"integer","description":"Unix timestamp when the token migrated. 0 if not migrated."},"migrated_from_pool":{"type":"string","description":"The pool address the token migrated from."},"migrated_to_pool":{"type":"string","description":"The pool address the token migrated to."},"migration_tx":{"type":"string","description":"The migration transaction hash."},"migration_price_usd":{"type":"number","nullable":true,"description":"Token price in USD at migration time. Null if not migrated."},"migration_price_native":{"type":"number","nullable":true,"description":"Token price in native token (e.g. SOL) at migration time. Null if not migrated."},"migration_market_cap_usd":{"type":"number","nullable":true,"description":"Market cap in USD at migration time. Null if not migrated."},"is_mayhem_mode":{"type":"boolean","description":"Whether the token launched in pump.fun \"Mayhem Mode\" — an opt-in coin-creation setting where an AI agent trades the coin for its first 24h. Only pump.fun tokens can be true; false for everything else."}},"required":["chain","address","name","symbol","decimals","created_at_ts","created_at_block","supply","logo_uri"]},"message":{"type":"string","description":"A message describing the result of the API request."}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"ErrorResponse":{"type":"object","description":"This object represents a response structure typically used to convey the outcome of a request. It primarily consists of a status indicator and a message, which together provide essential feedback about the request's processing. The status reflects the overall result of the request (such as success, error, etc.), while the message gives a more detailed explanation or the nature of the response, especially useful in cases of errors or exceptions.\n","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the response status object. This status is a key indicator of whether the request was processed successfully or resulted in an error."},"data":{"type":"object","description":"A flexible object intended to hold the actual data payload of the response. The structure of this object can vary depending on the specific endpoint and the nature of the response."},"message":{"type":"string","description":"A descriptive message providing additional details about the response. In case of an error, this message typically contains information useful for understanding the error's cause or nature."}},"required":["status","message"]}}},"paths":{"/api/v1/token/metadata":{"get":{"tags":["Token"],"summary":"Token metadata","description":"This endpoint retrieves metadata for a specific token.\n### Cost per Request\nCost per request = 2 credits.\n### Available Plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokenMetadata","parameters":[{"name":"chain","in":"query","required":true,"schema":{"type":"string","enum":["solana","ethereum","base","hyperevm","robinhood","arc"]}},{"name":"token_address","in":"query","required":true,"schema":{"type":"string","format":"address"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenMetadataResponse"}}}},"400":{"description":"Bad Request - The request was unacceptable, often due to missing a required parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - The client does not have access rights to the content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Token not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Token price

> This endpoint retrieves price for a specific token.\
> \### Cost per Request\
> Cost per request = 2 credits.\
> \### Available Plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"TokenPriceResponse":{"type":"object","description":"Token price response","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the standard response status object, which indicates the success or failure of the API request."},"data":{"type":"object","description":"Contains token price.","properties":{"chain":{"type":"string","description":"The blockchain network on which the token is deployed."},"address":{"type":"string","description":"The address of the token contract."},"block_number":{"type":"integer","description":"The block number at which the price was recorded."},"price":{"type":"number","description":"The price of the token in USD."}},"required":["chain","address","block_number","price"]},"message":{"type":"string","description":"A message describing the result of the API request."}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"ErrorResponse":{"type":"object","description":"This object represents a response structure typically used to convey the outcome of a request. It primarily consists of a status indicator and a message, which together provide essential feedback about the request's processing. The status reflects the overall result of the request (such as success, error, etc.), while the message gives a more detailed explanation or the nature of the response, especially useful in cases of errors or exceptions.\n","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the response status object. This status is a key indicator of whether the request was processed successfully or resulted in an error."},"data":{"type":"object","description":"A flexible object intended to hold the actual data payload of the response. The structure of this object can vary depending on the specific endpoint and the nature of the response."},"message":{"type":"string","description":"A descriptive message providing additional details about the response. In case of an error, this message typically contains information useful for understanding the error's cause or nature."}},"required":["status","message"]}}},"paths":{"/api/v1/token/price":{"get":{"tags":["Token"],"summary":"Token price","description":"This endpoint retrieves price for a specific token.\n### Cost per Request\nCost per request = 2 credits.\n### Available Plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokenPrice","parameters":[{"name":"chain","in":"query","required":true,"schema":{"type":"string","enum":["solana","ethereum","base","hyperevm","robinhood","arc"]}},{"name":"token_address","in":"query","required":true,"schema":{"type":"string","format":"address"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenPriceResponse"}}}},"400":{"description":"Bad Request - The request was unacceptable, often due to missing a required parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - The client does not have access rights to the content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Token not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Token stats

> This endpoint retrieves stats of a specified token.\
> \### Cost per Request\
> Cost per request = 10 credits.\
> \### Available Plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"TokenStatsResponse":{"type":"object","description":"Response containing detailed statistics for a specific token including price, market cap, and trading volume metrics","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the standard response status object, which indicates the success or failure of the API request."},"data":{"type":"object","description":"Contains comprehensive token statistics information.","properties":{"trader_counts":{"type":"object","description":"Distinct Solana trading wallets observed since counting began, not current holders or complete historical lifetime totals. Repeated trades count once per token. A wallet remains pro after its first confirmed pro trade. Omitted when counting is disabled or unsupported; independent of include_liquidity.","required":["status","pro_ratio"],"properties":{"status":{"type":"string","enum":["observed","unavailable"],"description":"Unavailable means no count is known; it must not be interpreted as zero."},"total_wallets":{"type":"integer","format":"int64","minimum":0},"pro_wallets":{"type":"integer","format":"int64","minimum":0},"pro_ratio":{"type":"number","nullable":true,"minimum":0,"maximum":1,"description":"pro_wallets / total_wallets; null when unavailable or total_wallets is zero."},"observed_since":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"token_address":{"type":"string","description":"The unique address of the token contract on the blockchain."},"price_usd":{"type":"number","description":"The current price of the token in USD."},"market_cap_usd":{"type":"number","description":"The total market capitalization of the token in USD (calculated as price × circulating supply)."},"ath_price_usd":{"type":"number","description":"The all-time high price of the token in USD. On Solana, Base, Robinhood and Arc it is the highest daily candle high of the token's Cielo chart series (the same pools the chart is drawn from); on other chains it is the highest recorded swap price across all pools. 0 when the chart series has no candles yet or could not be fetched in time; a later request returns the value once it is available."},"ath_market_cap_usd":{"type":"number","description":"The market capitalization at the token's all-time-high price in USD, valued using the CURRENT circulating supply (ath_price_usd × current supply). This is an approximation, not a point-in-time snapshot from the ATH block, and can differ from the true historical cap for tokens whose supply changed since the ATH."},"ath_date":{"type":"integer","format":"int64","description":"The Unix timestamp of the all-time high. On Solana, Base, Robinhood and Arc it is the start (00:00 UTC) of the day whose daily candle set the high; on other chains it is the time of the swap. Omitted when there is no all-time high."},"tax_rate":{"type":"number","description":"Token tax percentage (e.g. 5 = 5% tax), derived from the token's pools. Only present when include_liquidity=true (the default); omitted entirely on include_liquidity=false responses, where pool data is not computed. When present, 0 means no tax."},"total_fees_sol":{"type":"number","description":"Total collected fees across the token's pools, in SOL. Solana only. Only present when include_liquidity=true (the default); omitted on include_liquidity=false responses."},"total_fees_usd":{"type":"number","description":"Total collected fees across the token's pools in USD, estimated from the native-liquidity-implied SOL price. Solana only. Only present when include_liquidity=true (the default); omitted on include_liquidity=false responses."},"twitter":{"type":"string","description":"The token's X (Twitter) URL, or empty string when not set."},"x_link_type":{"type":"string","enum":["post","account","community","other",""],"description":"Classification of the X (Twitter) link: post (tweet), account (profile), community, other (search/hashtag/etc), or \"\" when there is no X link. Use it to pick the distinct X icon on the frontend."},"change":{"type":"object","description":"Price percentage changes over different time periods.","properties":{"1h":{"type":"number","description":"Price percentage change over the last hour."},"24h":{"type":"number","description":"Price percentage change over the last 24 hours."},"5m":{"type":"number","description":"Price percentage change over the last 5 minutes."},"6h":{"type":"number","description":"Price percentage change over the last 6 hours."}}},"volume":{"type":"object","description":"Trading volume statistics across different time periods.","properties":{"5m":{"$ref":"#/components/schemas/VolumeStats","description":"Trading statistics for the last 5 minutes."},"1h":{"$ref":"#/components/schemas/VolumeStats","description":"Trading statistics for the last hour."},"6h":{"$ref":"#/components/schemas/VolumeStats","description":"Trading statistics for the last 6 hours."},"24h":{"$ref":"#/components/schemas/VolumeStats","description":"Trading statistics for the last 24 hours."}}},"migration_price_usd":{"type":"number","nullable":true,"description":"Token price in USD at migration time. Null if not migrated."},"migration_price_native":{"type":"number","nullable":true,"description":"Token price in native token (e.g. SOL) at migration time. Null if not migrated."},"migration_market_cap_usd":{"type":"number","nullable":true,"description":"Market cap in USD at migration time. Null if not migrated."},"active_users":{"type":"integer","format":"int64","description":"Number of Cielo users currently viewing this token's chart (open connections). Best-effort: 0 when nobody is viewing, and also 0 when the upstream count is momentarily unavailable."}},"required":["token_address","price_usd","market_cap_usd","change","volume"]},"message":{"type":"string","description":"A message describing the result of the API request."}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"VolumeStats":{"type":"object","description":"Trading volume statistics for a specific time period","properties":{"volume_usd":{"type":"number","description":"Total trading volume in USD for the time period."},"buy_volume_usd":{"type":"number","description":"Total buy volume in USD for the time period."},"sell_volume_usd":{"type":"number","description":"Total sell volume in USD for the time period."},"unique_buyers":{"type":"integer","description":"Number of unique addresses that bought the token in the time period."},"unique_sellers":{"type":"integer","description":"Number of unique addresses that sold the token in the time period."},"buys":{"type":"integer","description":"Total number of buy transactions in the time period."},"sells":{"type":"integer","description":"Total number of sell transactions in the time period."}},"required":["volume_usd","buy_volume_usd","sell_volume_usd","unique_buyers","unique_sellers","buys","sells"]},"ErrorResponse":{"type":"object","description":"This object represents a response structure typically used to convey the outcome of a request. It primarily consists of a status indicator and a message, which together provide essential feedback about the request's processing. The status reflects the overall result of the request (such as success, error, etc.), while the message gives a more detailed explanation or the nature of the response, especially useful in cases of errors or exceptions.\n","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the response status object. This status is a key indicator of whether the request was processed successfully or resulted in an error."},"data":{"type":"object","description":"A flexible object intended to hold the actual data payload of the response. The structure of this object can vary depending on the specific endpoint and the nature of the response."},"message":{"type":"string","description":"A descriptive message providing additional details about the response. In case of an error, this message typically contains information useful for understanding the error's cause or nature."}},"required":["status","message"]}}},"paths":{"/api/v1/token/stats":{"get":{"tags":["Token"],"summary":"Token stats","description":"This endpoint retrieves stats of a specified token.\n### Cost per Request\nCost per request = 10 credits.\n### Available Plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokenStats","parameters":[{"name":"chain","in":"query","required":true,"schema":{"type":"string","enum":["solana","ethereum","base","hyperevm","robinhood","arc"]}},{"name":"token_address","in":"query","required":true,"schema":{"type":"string","format":"address"}},{"name":"include_liquidity","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"When false, skips the upstream liquidity evaluation to return faster. The liquidity, pools and is_spam fields stay empty in the response. Pair with /api/v1/token/stats-liquidity to fetch the omitted fields separately.\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenStatsResponse"}}}},"400":{"description":"Bad Request - The request was unacceptable, often due to missing a required parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - The client does not have access rights to the content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Token not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Token liquidity slice

> Liquidity portion of /api/v1/token/stats. Designed to pair with /api/v1/token/stats?include\_liquidity=false so callers can fetch the fast stats payload and the heavier liquidity slice in parallel.\
> \### Cost per Request\
> Cost per request = 10 credits.\
> \### Available Plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"TokenStatsLiquidityResponse":{"type":"object","description":"Liquidity slice of /token/stats, returned by the dedicated /token/stats-liquidity endpoint.","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"Standard response status indicating success or failure of the API request."},"data":{"type":"object","description":"Aggregated liquidity information for the token.","properties":{"chain":{"type":"string","description":"Blockchain network."},"token_address":{"type":"string","description":"The token contract address."},"price_usd":{"type":"number","description":"The current price of the token in USD, valued from the most-liquid pool (matches /token/stats)."},"market_cap_usd":{"type":"number","description":"The total market capitalization of the token in USD (price × circulating supply), valued from the most-liquid pool."},"relevant_pool_tax":{"type":"number","description":"Tax rate of the backend-selected top pool (the most-liquid pool that also drives price_usd/market_cap_usd). Same units as the per-pool tax_rate (e.g. 5 = 5%). Use this instead of scanning pools for a tax value. Zero when no pool reports a tax."},"relevant_pool_address":{"type":"string","description":"Address of the selected top pool that relevant_pool_tax refers to. Empty when no pool qualifies."},"is_spam":{"type":"boolean","description":"True when total liquidity is below the spam threshold or unavailable."},"total_fees":{"type":"string","description":"Sum of all collected fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_base_fees":{"type":"string","description":"Sum of base fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_priority_fees":{"type":"string","description":"Sum of priority fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_propagator_fees":{"type":"string","description":"Sum of propagator fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_protocol_fees":{"type":"string","description":"Sum of protocol fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_trading_fees":{"type":"string","description":"Sum of trading fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_creator_fees":{"type":"string","description":"Sum of creator fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_referral_fees":{"type":"string","description":"Sum of referral fees across pools, as a decimal string. Solana only; omitted when the fee totals could not be resolved."},"total_fees_sol":{"type":"number","format":"float","description":"total_fees expressed in the chain's native token (SOL). Solana only; omitted when the fee totals could not be resolved."},"total_fees_usd":{"type":"number","format":"float","description":"total_fees_sol valued in USD from the native-liquidity-implied SOL price. Solana only; omitted when the fee totals could not be resolved, and 0 when the token has no native-token pool to imply a price from."},"liquidity":{"type":"object","description":"Aggregated liquidity totals across all pools.","properties":{"total_liquidity_usd":{"type":"number","description":"Total liquidity in USD across all pools."},"usd_liquidity":{"type":"number","description":"Liquidity provided in USD-denominated paired tokens."},"usd_pools":{"type":"integer","description":"Number of pools paired with a USD-denominated token."},"native_liquidity":{"type":"number","description":"Liquidity provided in the chain's native token."},"native_liquidity_usd":{"type":"number","description":"USD value of the native-token liquidity."},"native_pools":{"type":"integer","description":"Number of pools paired with the native token."}}},"pools":{"type":"array","description":"List of liquidity pools sorted by liquidity_usd descending.","items":{"type":"object","properties":{"likely_spam":{"type":"boolean"},"liquidity_native":{"type":"number"},"liquidity":{"type":"number"},"liquidity_usd":{"type":"number"},"paired_token":{"type":"string"},"paired_token_symbol":{"type":"string"},"paired_token_name":{"type":"string"},"pool_address":{"type":"string"},"protocol":{"type":"string"},"protocol_ui":{"type":"string"},"tax_rate":{"type":"number","nullable":true}}}}},"required":["chain","token_address","liquidity"]},"message":{"type":"string"}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"ErrorResponse":{"type":"object","description":"This object represents a response structure typically used to convey the outcome of a request. It primarily consists of a status indicator and a message, which together provide essential feedback about the request's processing. The status reflects the overall result of the request (such as success, error, etc.), while the message gives a more detailed explanation or the nature of the response, especially useful in cases of errors or exceptions.\n","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the response status object. This status is a key indicator of whether the request was processed successfully or resulted in an error."},"data":{"type":"object","description":"A flexible object intended to hold the actual data payload of the response. The structure of this object can vary depending on the specific endpoint and the nature of the response."},"message":{"type":"string","description":"A descriptive message providing additional details about the response. In case of an error, this message typically contains information useful for understanding the error's cause or nature."}},"required":["status","message"]}}},"paths":{"/api/v1/token/stats-liquidity":{"get":{"tags":["Token"],"summary":"Token liquidity slice","description":"Liquidity portion of /api/v1/token/stats. Designed to pair with /api/v1/token/stats?include_liquidity=false so callers can fetch the fast stats payload and the heavier liquidity slice in parallel.\n### Cost per Request\nCost per request = 10 credits.\n### Available Plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokenStatsLiquidity","parameters":[{"name":"chain","in":"query","required":true,"schema":{"type":"string","enum":["solana","ethereum","base","hyperevm","robinhood","arc"]}},{"name":"token_address","in":"query","required":true,"schema":{"type":"string","format":"address"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenStatsLiquidityResponse"}}}},"400":{"description":"Bad Request - The request was unacceptable, often due to missing a required parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - The client does not have access rights to the content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Token not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Token checklist

> This endpoint retrieves safety and distribution checklist data for a specific token.\
> \### Cost per Request\
> Cost per request = 10 credits.\
> \### Available Plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"TokenChecklistResponse":{"type":"object","description":"Token checklist response containing safety and distribution metrics for a token","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the standard response status object, which indicates the success or failure of the API request."},"data":{"type":"object","description":"Contains token checklist information.","properties":{"dex_paid":{"type":"boolean","description":"Whether the token has paid for DEX listing."},"dex_paid_at":{"type":"integer","description":"Timestamp when the token paid for DEX listing. Omitted when the token has not paid for a DEX listing."},"top_20_holders_percent":{"type":"number","description":"Percentage of total supply held by the top 20 holders."},"holders":{"type":"integer","description":"Total number of token holders."},"developer":{"type":"string","description":"The developer wallet address."},"developer_balance":{"type":"object","description":"Developer's token balance information.","properties":{"amount":{"type":"number","description":"Developer's token balance amount."},"amount_usd":{"type":"number","description":"Developer's token balance value in USD."},"amount_native":{"type":"number","description":"Developer's balance in native token."},"supply_owned_percent":{"type":"number","description":"Percentage of total supply owned by the developer."}},"required":["amount","amount_usd","amount_native","supply_owned_percent"]},"snipers_holding_percent":{"type":"number","description":"Percentage of total supply held by snipers."},"bundlers_holding_percent":{"type":"number","description":"Percentage of total supply held by bundlers."},"top_holder_dump_risk":{"description":"Estimated price drawdown if the largest non-pool holder sold their entire position into the token's top pools. Omitted when it cannot be estimated.","allOf":[{"$ref":"#/components/schemas/DumpRisk"}]},"top_5_holders_dump_risk":{"description":"Estimated price drawdown if the five largest non-pool holders sold their entire positions into the token's top pools. Omitted when it cannot be estimated.","allOf":[{"$ref":"#/components/schemas/DumpRisk"}]},"migration":{"type":"object","description":"Token migration status information.","nullable":true,"properties":{"has_launchpad_pool":{"type":"boolean","description":"Whether the token has a launchpad pool."},"bonding_curve_percentage":{"type":"number","description":"Bonding curve completion percentage."},"migrating_from_protocol":{"type":"string","description":"The protocol the token is migrating from."},"migrated":{"type":"boolean","description":"Whether the token has completed migration."},"blacklisted_token":{"type":"boolean","description":"Whether the token is blacklisted."},"migrated_at":{"type":"integer","description":"Timestamp when the token migrated."},"migrated_from_pool":{"type":"string","description":"The pool address the token migrated from."},"migrated_to_pool":{"type":"string","description":"The pool address the token migrated to."},"migration_tx":{"type":"string","description":"The migration transaction hash."}}}},"required":["dex_paid","top_20_holders_percent","holders","developer","developer_balance","snipers_holding_percent","bundlers_holding_percent"]},"message":{"type":"string","description":"A message describing the result of the API request."}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"DumpRisk":{"type":"object","description":"Estimated sell-pressure impact of a holder position, from a constant-product model over the token's top pools.","properties":{"percent":{"type":"number","description":"Estimated price drop in percent (0-100)."},"amount_usd":{"type":"number","description":"USD value of the position at the current token price."}},"required":["percent","amount_usd"]},"ErrorResponse":{"type":"object","description":"This object represents a response structure typically used to convey the outcome of a request. It primarily consists of a status indicator and a message, which together provide essential feedback about the request's processing. The status reflects the overall result of the request (such as success, error, etc.), while the message gives a more detailed explanation or the nature of the response, especially useful in cases of errors or exceptions.\n","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the response status object. This status is a key indicator of whether the request was processed successfully or resulted in an error."},"data":{"type":"object","description":"A flexible object intended to hold the actual data payload of the response. The structure of this object can vary depending on the specific endpoint and the nature of the response."},"message":{"type":"string","description":"A descriptive message providing additional details about the response. In case of an error, this message typically contains information useful for understanding the error's cause or nature."}},"required":["status","message"]}}},"paths":{"/api/v1/token/checklist":{"get":{"tags":["Token"],"summary":"Token checklist","description":"This endpoint retrieves safety and distribution checklist data for a specific token.\n### Cost per Request\nCost per request = 10 credits.\n### Available Plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokenChecklist","parameters":[{"name":"chain","in":"query","required":true,"schema":{"type":"string","enum":["solana","ethereum","base","robinhood","arc"]}},{"name":"token_address","in":"query","required":true,"schema":{"type":"string","format":"address"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenChecklistResponse"}}}},"400":{"description":"Bad Request - The request was unacceptable, often due to missing a required parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - The client does not have access rights to the content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Token not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Trending tokens

> 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<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"TrendingTokensResponse":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrendingTokenItem"}},"epoch_offset":{"type":"object","properties":{"epoch":{"type":"string"},"offset":{"type":"integer"}}},"paging":{"type":"object","properties":{"next_cursor":{"type":"string"}}}}}}},"TrendingTokenItem":{"type":"object","properties":{"token_address":{"type":"string","description":"The token contract address."},"token_symbol":{"type":"string","description":"The token symbol."},"token_name":{"type":"string","description":"The token name."},"chain":{"type":"string","description":"The blockchain network."},"platform":{"type":"string","description":"The platform code."},"platform_ui":{"type":"string","description":"Human-readable platform name."},"platform_uri":{"type":"string","description":"Platform URI."},"market_cap":{"type":"number","description":"Market cap in USD."},"liquidity":{"type":"number","description":"Total liquidity in USD."},"volume_24h":{"type":"number","description":"24-hour trading volume in USD."},"unique_wallets":{"type":"integer","description":"Number of unique wallets that traded this token in the given interval."},"holders":{"type":"integer","description":"Number of token holders."},"mindshare":{"type":"number","description":"Mindshare score."},"mindshare_breakdown":{"type":"array","items":{"type":"object","properties":{"count":{"type":"integer"},"label":{"type":"string"},"percentage":{"type":"number"}}}},"price_change_percentage":{"type":"number","description":"Price change percentage."},"net_flow":{"type":"number","description":"Net flow value."},"popular_wallets":{"type":"integer","description":"Number of popular wallets."},"whales":{"type":"integer","description":"Number of whale wallets."},"fresh_wallets_percentage":{"type":"number","description":"Percentage of fresh wallets."},"sniper_percentage":{"type":"number","description":"Percentage of sniper wallets."},"dev_percentage":{"type":"number","description":"Developer wallet percentage."},"top_20_percentage":{"type":"number","description":"Top 20 holders percentage."},"bonding_curve_percentage":{"type":"number","description":"Bonding curve percentage."},"avg_buy":{"type":"number","description":"Average buy amount."},"buy_count":{"type":"integer","description":"Number of buy transactions."},"sell_count":{"type":"integer","description":"Number of sell transactions."},"buy_volume_usd":{"type":"number","description":"Buy volume in USD."},"sell_volume_usd":{"type":"number","description":"Sell volume in USD."},"token_age":{"type":"integer","description":"Token age in seconds."},"dex_paid":{"type":"boolean","description":"Whether DEX has been paid."},"is_deleted":{"type":"integer","description":"Deletion flag."},"telegram":{"type":"string","description":"Telegram link."},"website":{"type":"string","description":"Website URL."}}},"ErrorResponse":{"type":"object","description":"This object represents a response structure typically used to convey the outcome of a request. It primarily consists of a status indicator and a message, which together provide essential feedback about the request's processing. The status reflects the overall result of the request (such as success, error, etc.), while the message gives a more detailed explanation or the nature of the response, especially useful in cases of errors or exceptions.\n","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the response status object. This status is a key indicator of whether the request was processed successfully or resulted in an error."},"data":{"type":"object","description":"A flexible object intended to hold the actual data payload of the response. The structure of this object can vary depending on the specific endpoint and the nature of the response."},"message":{"type":"string","description":"A descriptive message providing additional details about the response. In case of an error, this message typically contains information useful for understanding the error's cause or nature."}},"required":["status","message"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]}}},"paths":{"/api/v1/trending-tokens":{"get":{"tags":["Token"],"summary":"Trending tokens","description":"This endpoint retrieves the top trending tokens by unique wallet activity for the specified chain and interval.\n### Cost per Request\nCost per request = 20 credits.\n### Available Plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTrendingTokens","parameters":[{"name":"chain","in":"query","required":true,"schema":{"type":"string","enum":["solana","base","all"]},"description":"The blockchain network to get trending tokens for."},{"name":"interval","in":"query","required":false,"schema":{"type":"string","enum":["1m","5m","1h","6h","24h"],"default":"1h"},"description":"The time window for trending calculation. Shorter intervals show more recent momentum; longer intervals show sustained trends. Defaults to 1h.\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Maximum number of tokens to return."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["mindshare_asc","mindshare_desc","market_cap_asc","market_cap_desc","holders_asc","holders_desc","liquidity_asc","liquidity_desc","volume_24h_asc","volume_24h_desc","transactions_asc","transactions_desc","whale_asc","whale_desc","popular_asc","popular_desc","net_flow_asc","net_flow_desc","fresh_wallets_asc","fresh_wallets_desc","avg_buy_asc","avg_buy_desc","price_change_asc","price_change_desc","age_asc","age_desc","bonding_curve_asc","bonding_curve_desc","unique_wallets_asc","unique_wallets_desc"]},"description":"Sort order for results."},{"name":"next_cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor for pagination."},{"name":"dex_paid","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter by DEX paid status."},{"name":"protocols","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Filter by protocols."},{"name":"min_market_cap","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum market cap filter (USD)."},{"name":"max_market_cap","in":"query","required":false,"schema":{"type":"number"},"description":"Maximum market cap filter (USD)."},{"name":"min_liquidity","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum liquidity filter (USD)."},{"name":"max_liquidity","in":"query","required":false,"schema":{"type":"number"},"description":"Maximum liquidity filter (USD)."},{"name":"min_volume_24h","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum 24h volume filter (USD)."},{"name":"max_volume_24h","in":"query","required":false,"schema":{"type":"number"},"description":"Maximum 24h volume filter (USD)."},{"name":"min_unique_wallets","in":"query","required":false,"schema":{"type":"integer"},"description":"Minimum unique wallets filter."},{"name":"max_unique_wallets","in":"query","required":false,"schema":{"type":"integer"},"description":"Maximum unique wallets filter."},{"name":"min_holders","in":"query","required":false,"schema":{"type":"integer"},"description":"Minimum holders filter."},{"name":"max_holders","in":"query","required":false,"schema":{"type":"integer"},"description":"Maximum holders filter."},{"name":"min_transactions","in":"query","required":false,"schema":{"type":"integer"},"description":"Minimum transactions filter."},{"name":"max_transactions","in":"query","required":false,"schema":{"type":"integer"},"description":"Maximum transactions filter."},{"name":"min_mindshare","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum mindshare filter."},{"name":"max_mindshare","in":"query","required":false,"schema":{"type":"number"},"description":"Maximum mindshare filter."},{"name":"min_price_change","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum price change filter."},{"name":"max_price_change","in":"query","required":false,"schema":{"type":"number"},"description":"Maximum price change filter."},{"name":"min_token_age","in":"query","required":false,"schema":{"type":"string"},"description":"Minimum token age filter."},{"name":"max_token_age","in":"query","required":false,"schema":{"type":"string"},"description":"Maximum token age filter."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingTokensResponse"}}}},"400":{"description":"Bad Request - Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Token Flows V2

> 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<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/api/v2/token-flows":{"get":{"tags":["Token"],"summary":"Token Flows V2","description":"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.\n\nThe caller's wallet is derived server-side from the API key — clients do not need to provide it via a header.\n\n### Cost per Request\nCost per request = 5 credits.\n\n### Available Plans\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokenFlowsV2","parameters":[{"name":"last","in":"query","description":"Time period (1h, 6h, 24h, 7d, 30d). Default is 24h.","required":false,"schema":{"type":"string","enum":["1h","6h","24h","7d","30d"]}},{"name":"page","in":"query","description":"Page number for pagination. Default is 1.","required":false,"schema":{"type":"integer"}},{"name":"list","in":"query","description":"Filter by list/bundle ID.","required":false,"schema":{"type":"integer"}},{"name":"chain","in":"query","description":"Filter by blockchain chain (e.g. solana, ethereum), comma-separated for multiple values.","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"sort_by","in":"query","description":"Sort field (net_flow_usd, buy_usd, sell_usd, wallets_num, trades_num). Default is net_flow_usd.","required":false,"schema":{"type":"string","enum":["net_flow_usd","buy_usd","sell_usd","wallets_num","trades_num"]}},{"name":"order","in":"query","description":"Sort order (asc, desc). Default is desc.","required":false,"schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","description":"Token contract address."},"symbol":{"type":"string"},"name":{"type":"string"},"chain":{"type":"string"},"net_flow_usd":{"type":"integer","format":"int64","description":"Net flow in USD (signed, integer rounded)."},"net_flow_amount":{"type":"integer","format":"int64"},"buy_usd":{"type":"integer","format":"int64"},"buy_amount":{"type":"integer","format":"int64"},"sell_usd":{"type":"integer","format":"int64"},"sell_amount":{"type":"integer","format":"int64"},"avg_buy_usd":{"type":"integer","format":"int64"},"avg_sell_usd":{"type":"integer","format":"int64"},"wallets_num":{"type":"integer"},"trades_num":{"type":"integer"},"platform":{"type":"string","description":"Platform code for Solana tokens (e.g. \"pump.fun\"). Omitted otherwise."}}}},"paging":{"type":"object","properties":{"total_pages":{"type":"integer"},"total_rows":{"type":"integer"},"total_rows_in_page":{"type":"integer"}}}}}}}}}},"400":{"description":"Bad Request - The request was unacceptable, often due to a missing or invalid parameter."},"401":{"description":"Unauthorized - The API key is not associated with a wallet."},"403":{"description":"Forbidden - The API key plan does not allow access to this endpoint."},"500":{"description":"Internal Server Error - Something went wrong on the server's end."}}}}}}
```

## New Token Flows

> 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<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Token","description":"Token metadata, prices, market stats, liquidity, safety checklist and trending tokens."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/api/v2/new-token-flows":{"get":{"tags":["Token"],"summary":"New Token Flows","description":"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.\n\nThe caller's wallet is derived server-side from the API key — clients do not need to provide it via a header.\n\n### Cost per Request\nCost per request = 5 credits.\n\n### Available Plans\n- Builder\n- Architect\n- Enterprise\n","operationId":"getNewTokenFlows","parameters":[{"name":"last","in":"query","description":"Time period (1h, 6h, 24h). Default is 24h.","required":false,"schema":{"type":"string","enum":["1h","6h","24h"]}},{"name":"page","in":"query","description":"Page number for pagination. Default is 1.","required":false,"schema":{"type":"integer"}},{"name":"list","in":"query","description":"Filter by list/bundle ID.","required":false,"schema":{"type":"integer"}},{"name":"chain","in":"query","description":"Filter by blockchain chain (e.g. solana, ethereum), comma-separated for multiple values.","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"sort_by","in":"query","description":"Sort field (net_flow_usd, buy_usd, sell_usd, wallets_num, trades_num). Default is net_flow_usd.","required":false,"schema":{"type":"string","enum":["net_flow_usd","buy_usd","sell_usd","wallets_num","trades_num"]}},{"name":"order","in":"query","description":"Sort order (asc, desc). Default is desc.","required":false,"schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"allOf":[{"$ref":"#/paths/~1api~1v2~1token-flows/get/responses/200/content/application~1json/schema/properties/data/properties/items/items"},{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64","description":"Unix timestamp (seconds) of the token's first trade."}}}]}},"paging":{"$ref":"#/paths/~1api~1v2~1token-flows/get/responses/200/content/application~1json/schema/properties/data/properties/paging"}}}}}}}},"400":{"description":"Bad Request - The request was unacceptable, often due to a missing or invalid parameter."},"401":{"description":"Unauthorized - The API key is not associated with a wallet."},"403":{"description":"Forbidden - The API key plan does not allow access to this endpoint."},"500":{"description":"Internal Server Error - Something went wrong on the server's end."}}}}}}
```
