> 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/wallet-pnl-and-stats.md).

# Wallet PnL & Stats

Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets.

## Token PNL

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"responses":{"TokensPNLResponse":{"description":"Successfull tokens PnL response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokensPNL"}}}}},"schemas":{"TokensPNL":{"type":"object","description":"The response schema for the /v1/tokens_pnl endpoint.","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 the main data of the response, including a list of tokens PNL items and pagination details.","properties":{"items":{"type":"array","description":"An array of tokens PNL items, each providing detailed information on token transactions and performance.","items":{"$ref":"#/components/schemas/TokensPNLItem"}},"paging":{"$ref":"#/components/schemas/PnLPaging"}},"required":["items","paging"]},"message":{"type":"string","description":"A descriptive message accompanying the response, often used to provide additional information or context about the results or the status of the request."}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"TokensPNLItem":{"type":"object","properties":{"num_swaps":{"type":"integer","format":"int64"},"num_buys":{"type":"integer","format":"int64","description":"Buy count. num_buys + num_sells == num_swaps."},"num_sells":{"type":"integer","format":"int64","description":"Sell count. num_buys + num_sells == num_swaps."},"total_buy_usd":{"type":"number","format":"double"},"total_buy_amount":{"type":"number","format":"double"},"total_sell_usd":{"type":"number","format":"double"},"total_sell_amount":{"type":"number","format":"double"},"average_buy_price":{"type":"number","format":"double"},"average_sell_price":{"type":"number","format":"double"},"total_pnl_usd":{"type":"number","format":"double"},"roi_percentage":{"type":"number","format":"double"},"unrealized_pnl_usd":{"type":"number","format":"double"},"unrealized_roi_percentage":{"type":"number","format":"double"},"token_price":{"type":"number","format":"double"},"token_address":{"type":"string"},"token_symbol":{"type":"string"},"token_name":{"type":"string"},"chain":{"type":"string"},"is_honeypot":{"type":"boolean"},"holding_time_seconds":{"type":"integer","description":"The token holding time in seconds."},"holding_amount":{"type":"number","format":"double","description":"The current holding amount of the token"},"holding_amount_usd":{"type":"number","format":"double","description":"The current holding amount in USD"},"platform":{"type":"string","description":"Platform or protocol the token is associated with (e.g., \"pump-fun\", \"boop-fun\", \"solana\")"},"platform_ui":{"type":"string","description":"Human-readable platform name (e.g., \"Pump.fun\", \"Boop\", \"Solana\")"},"avg_buy_market_cap_usd":{"type":"number","format":"double","description":"Estimated market cap at the average buy price, calculated as avg_buy_price * (current_market_cap / current_price). Only populated when CieloPricer data is available."},"avg_sell_market_cap_usd":{"type":"number","format":"double","description":"Estimated market cap at the average sell price, calculated as avg_sell_price * (current_market_cap / current_price). Only populated when CieloPricer data is available."},"token_age":{"type":"integer","format":"int64","description":"Time in seconds since the token's launch when the wallet first entered the token."},"held_by":{"type":"string","description":"Wallet address that holds this token. Only present when using multi_bundle_id parameter."},"held_by_labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of held_by wallet address to its bundle label. Only wallets that have a non-empty label appear; consumers fall back to the address for the rest. Only present when using multi_bundle_id parameter."}}},"PnLPaging":{"type":"object","properties":{"total_rows_in_page":{"type":"integer","format":"int32"},"has_next_page":{"type":"boolean"},"next_object":{"type":"string"}},"required":["total_rows_in_page","has_next_page"]},"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/{wallet}/pnl/tokens":{"get":{"tags":["Wallet"],"summary":"Token PNL","description":"This endpoint retrieves a PnL values for a specified wallet by different tokens.\n### Cost per Request\nCost per request = 5 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokensPNL","parameters":[{"name":"wallet","in":"path","description":"Get P&L values for wallet.","required":true,"schema":{"type":"string"}},{"name":"chain","in":"query","description":"Filter data by specific blockchain chains (e.g. ethereum), comma-separated for multiple values (e.g, ethereum,polygon)","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"timeframe","in":"query","description":"Set time range for filtering data. Supported options - 1d, 7d, 30d and max. Default - max timeframe.","required":false,"schema":{"type":"string"}},{"name":"next_object","in":"query","description":"Next page for pagination.","required":false,"schema":{"type":"string"}},{"name":"token","in":"query","description":"Filter data by specific tokens (e.g. PEPECAT or FfhArvgv8WB7eZ6qwENMouJRzcVpQVDoDtTuHrCk4Cxi), comma-separated for multiple values (e.g, usdc,usdt). Symbols are matched case-insensitively; addresses are matched as-is.","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"cex_transfers","in":"query","description":"Include cex transfers for calculating P&L. Default - false.","required":false,"schema":{"type":"boolean"}},{"name":"active_positions_only","in":"query","description":"Filter to show only active positions. Default - false.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"$ref":"#/components/responses/TokensPNLResponse"},"202":{"description":"Accepted - Data is not ready yet. Retry in 10 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## NFT PNL

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"responses":{"NftsPnLResponse":{"description":"Successfull Nft PnL response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NftsPnL"}}}}},"schemas":{"NftsPnL":{"type":"object","description":"The response schema for the /v1/nftss_pnl endpoint.","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 the main data of the response, including a list of Nft PnL items and pagination details.","properties":{"items":{"type":"array","description":"An array of Nft PnL items, each providing detailed information on token transactions and performance.","items":{"$ref":"#/components/schemas/NftPnLItem"}},"paging":{"$ref":"#/components/schemas/PnLPaging"}},"required":["items","paging"]},"message":{"type":"string","description":"A descriptive message accompanying the response, often used to provide additional information or context about the results or the status of the request."}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"NftPnLItem":{"type":"object","properties":{"num_swaps":{"type":"integer","format":"int64"},"total_buy_amount":{"type":"number","format":"double"},"total_sell_amount":{"type":"number","format":"double"},"total_buy_avg":{"type":"number","format":"double"},"total_sell_avg":{"type":"number","format":"double"},"total_buy_usd":{"type":"number","format":"double"},"total_sell_usd":{"type":"number","format":"double"},"profit_loss":{"type":"number","format":"double"},"roi_percentage":{"type":"number","format":"double"},"chain":{"type":"string"},"token_address":{"type":"string"},"nft_symbol":{"type":"string"},"nft_name":{"type":"string"}}},"PnLPaging":{"type":"object","properties":{"total_rows_in_page":{"type":"integer","format":"int32"},"has_next_page":{"type":"boolean"},"next_object":{"type":"string"}},"required":["total_rows_in_page","has_next_page"]},"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/{wallet}/pnl/nfts":{"get":{"tags":["Wallet"],"summary":"NFT PNL","description":"This endpoint retrieves the PnL value for an NFT collection on Ethereum.\n### Cost per Request\nCost per request = 5 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getNftsPNL","parameters":[{"name":"wallet","in":"path","description":"Get NFT P&L values for wallet.","required":true,"schema":{"type":"string"}},{"name":"timeframe","in":"query","description":"Set time range for filtering data. Supported options - 1d, 7d, 30d and max. Default - max timeframe.","required":false,"schema":{"type":"string"}},{"name":"next_object","in":"query","description":"Next page for pagination.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/NftsPnLResponse"},"202":{"description":"Accepted - Data is not ready yet. Retry in 10 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Aggregated Token PNL

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"responses":{"TotalStatsResponse":{"description":"Successfull Total Stats response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotalStats"}}}}},"schemas":{"TotalStats":{"type":"object","description":"The response schema for the /v1/{wallet}/pnl/total-stats endpoint.","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 the main data of the response, including aggregated PnL stats for the specified wallet.","properties":{"wallet":{"type":"string","description":"The wallet address for which the PnL stats are provided."},"realized_pnl_usd":{"type":"number","format":"float64","description":"The total PnL in usd for the specified wallet."},"realized_roi_percentage":{"type":"number","format":"float64","description":"The total ROI percentage for the specified wallet."},"tokens_traded":{"type":"integer","description":"The total number of tokens traded for the specified wallet."},"unrealized_pnl_usd":{"type":"number","format":"float64","description":"The total unrealized PnL in usd for the specified wallet."},"unrealized_roi_percentage":{"type":"number","format":"float64","description":"The total unrealized ROI percentage for the specified wallet."},"winrate":{"type":"number","format":"float64","description":"The winrate percentage for the specified wallet."},"average_holding_time":{"type":"integer","format":"float64","description":"The average holding time for the specified wallet in hours.","deprecated":true},"average_holding_time_seconds":{"type":"integer","description":"The average holding time for the specified wallet in seconds."},"median_holding_time_seconds":{"type":"integer","description":"The median holding time for the specified wallet in seconds."},"combined_pnl_usd":{"type":"number","format":"float64","description":"The combined PnL in usd for the specified wallet."},"combined_roi_percentage":{"type":"number","format":"float64","description":"The combined ROI percentage for the specified wallet."},"total_buy_usd":{"type":"number","format":"float64","description":"The total buy amount in usd for the specified wallet."},"total_sell_usd":{"type":"number","format":"float64","description":"The total sell amount in usd for the specified wallet."}}},"message":{"type":"string","description":"A descriptive message accompanying the response, often used to provide additional information or context about the results or the status of the 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/{wallet}/pnl/total-stats":{"get":{"tags":["Wallet"],"summary":"Aggregated Token PNL","description":"This endpoint retrieves aggregated PnL stats for a specified wallet.\n### Cost per Request\nCost per request = 20 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTotalStats","parameters":[{"name":"wallet","in":"path","description":"Get tags associated with wallet.","required":true,"schema":{"type":"string"}},{"name":"chains","in":"query","description":"Filter transactions by specific blockchain chains (e.g. ethereum), comma-separated for multiple values (e.g, ethereum,polygon)","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"timeframe","in":"query","description":"Set time range for filtering data. Supported options - 1d, 7d, 30d and max. Default - max timeframe.","required":false,"schema":{"type":"string"}},{"name":"cex_transfers","in":"query","description":"Include CEX transfers in the response.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"$ref":"#/components/responses/TotalStatsResponse"},"202":{"description":"Accepted - Data is not ready yet. Retry in 10 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Related Wallets

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"responses":{"RelatedWalletsResponse":{"description":"Successfull Related Wallets response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedWallets"}}}}},"schemas":{"RelatedWallets":{"type":"object","description":"The response schema for the /v1/{wallet}/related-wallets endpoint.","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 the main data of the response.","properties":{"related_wallets":{"type":"array","description":"An array of related wallets associated with the wallet address.","items":{"type":"object","properties":{"wallet":{"type":"string","description":"The wallet address for which the related wallets are provided."},"inflow_usd":{"type":"integer","description":"The total inflow in usd for the specified wallet."},"outflow_usd":{"type":"integer","description":"The total outflow in usd for the specified wallet."},"total_usd":{"type":"integer","description":"The total inflow and outflow in usd for the specified wallet."},"count":{"type":"integer","description":"The total number of transactions for the specified wallet."},"label":{"type":"string","description":"The label for the related wallet."}}}}}},"message":{"type":"string","description":"A descriptive message accompanying the response, often used to provide additional information or context about the results or the status of the 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/{wallet}/related-wallets":{"get":{"tags":["Wallet"],"summary":"Related Wallets","description":"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.\n### Cost per Request\nCost per request = 10 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getRelatedWallets","parameters":[{"name":"wallet","in":"path","description":"Get related wallets for wallet.","required":true,"schema":{"type":"string"}},{"name":"sort_criteria","in":"query","description":"Sort wallets by the specified criteria. Volume uses total USD received plus sent.","required":false,"schema":{"type":"string","enum":["volume_asc","volume_desc","inflow_asc","inflow_desc","outflow_asc","outflow_desc","transactions_asc","transactions_desc"]}}],"responses":{"200":{"$ref":"#/components/responses/RelatedWalletsResponse"},"202":{"description":"Accepted - Data is not ready yet. Retry in 10 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Trading Stats

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"responses":{"TradingStatsResponse":{"description":"Trading stats response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_trades":{"type":"integer","description":"Total number of trades"},"successful_trades":{"type":"integer","description":"Number of successful trades"},"failed_trades":{"type":"integer","description":"Number of failed trades"},"win_rate":{"type":"number","format":"float","description":"Win rate percentage"},"average_profit":{"type":"number","format":"float","description":"Average profit per trade"},"total_profit":{"type":"number","format":"float","description":"Total profit"},"total_volume":{"type":"number","format":"float","description":"Total trading volume"},"most_traded_token":{"type":"string","description":"Most frequently traded token"},"most_profitable_token":{"type":"string","description":"Most profitable token"},"trading_frequency":{"type":"string","description":"Trading frequency (e.g., \"daily\", \"weekly\", \"monthly\")"},"last_trade_timestamp":{"type":"integer","description":"Unix timestamp of the last trade"}}}},"required":["data"]}}}}},"schemas":{"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/{wallet}/trading-stats":{"get":{"tags":["Wallet"],"summary":"Trading Stats","description":"Detailed performance statistics for a wallet's trading activity, including PnL, ROI, win rate, and trading behavior insights.\n### Cost per Request\nCost per request = 30 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTradingStats","parameters":[{"name":"wallet","in":"path","description":"Get trading stats for wallet.","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","description":"Time period for trading stats (1d, 7d, 30d, max).","required":false,"schema":{"type":"string","enum":["1d","7d","30d","max"]}}],"responses":{"200":{"$ref":"#/components/responses/TradingStatsResponse"},"202":{"description":"Accepted - Data is not ready yet. Retry in 10 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Wallet Portfolio

> 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, Robinhood)\
> \### Cost per Request\
> Cost per request = 20 credits.\
> \### Available Plans\
> Available on the following plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"WalletPortfolioResponse":{"type":"object","description":"The response schema for the /api/v1/{wallet}/portfolio endpoint.","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 the main data of the response.","properties":{"last_updated":{"type":"integer","description":"The unix timestamp of the last portfolio update."},"total_usd_value":{"type":"number","description":"The total USD value of the portfolio."},"portfolio":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioAsset"},"description":"Contains the portfolio assets."}},"required":["last_updated"]},"message":{"type":"string","description":"A descriptive message accompanying the response, often used to provide additional information or context about the results or the status of the request."}},"required":["status","data"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"PortfolioAsset":{"type":"object","properties":{"chain":{"type":"string","description":"The chain of the token."},"token_address":{"type":"string","description":"The token address."},"token_name":{"type":"string","description":"The token name."},"token_symbol":{"type":"string","description":"The token symbol."},"platform":{"type":"string","description":"The token launch platform code."},"platform_ui":{"type":"string","description":"The human-readable token launch platform name."},"token_price_usd":{"type":"number","description":"The token price in USD."},"balance":{"type":"number","description":"The token balance."},"total_usd_value":{"type":"number","description":"The total USD value."},"supply":{"type":"number","description":"The token supply."},"supply_owned":{"type":"number","description":"The token supply owned."}},"required":["token_address","token_name","token_symbol","token_price_usd","balance","total_usd_value","supply","supply_owned"]},"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/{wallet}/portfolio":{"get":{"tags":["Wallet"],"summary":"Wallet Portfolio","description":"Retrieve the portfolio of a wallet.\nFor Solana wallets, the response also includes the native SOL balance.\nPortfolio assets with a total_usd_value of zero are not included in the response.\nAvailable chains:\n- Solana\n- EVM (Ethereum, Base, HyperEVM, Robinhood)\n### Cost per Request\nCost per request = 20 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getWalletPortfolio","parameters":[{"name":"wallet","in":"path","description":"Get portfolio for wallet.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletPortfolioResponse"}}}},"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"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Token Balance

> Retrieve the token balance for a wallet.\
> Available chains:\
> \- Solana\
> \- EVM (Ethereum, Base, HyperEVM, Robinhood)\
> \### Cost per Request\
> Cost per request = 3 credits.\
> \### Available Plans\
> Available on the following plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"TokenBalanceResponse":{"type":"object","description":"Response containing token balance information","properties":{"chain":{"type":"string","description":"The chain of the token."},"token_address":{"type":"string","description":"The token address."},"token_name":{"type":"string","description":"The token name."},"token_symbol":{"type":"string","description":"The token symbol."},"token_price_usd":{"type":"number","description":"The token price in USD."},"balance":{"type":"number","description":"The token balance."},"total_usd_value":{"type":"number","description":"The total USD value."},"decimals":{"type":"integer","description":"The number of decimals for the token."}},"required":["chain","token_address","token_name","token_symbol","token_price_usd","balance","total_usd_value","decimals"]},"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/{wallet}/token-balance":{"get":{"tags":["Wallet"],"summary":"Token Balance","description":"Retrieve the token balance for a wallet.\nAvailable chains:\n- Solana\n- EVM (Ethereum, Base, HyperEVM, Robinhood)\n### Cost per Request\nCost per request = 3 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokenBalance","parameters":[{"name":"wallet","in":"path","description":"Get token balance for wallet.","required":true,"schema":{"type":"string"}},{"name":"token_address","in":"query","description":"The token address to get balance for.","required":true,"schema":{"type":"string"}},{"name":"chain","in":"query","description":"The blockchain network (ethereum, base, or solana).","required":true,"schema":{"type":"string","enum":["solana","ethereum","base","hyperevm","robinhood","arc"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenBalanceResponse"}}}},"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"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Wallet Token Positions

> This endpoint retrieves per-token trading positions for one or more wallets: amounts bought and sold, current holdings, average buy and sell prices, and realized and unrealized PnL in USD and in the chain's native token.\
> Results are paginated with a cursor: pass \`paging.next\_cursor\` from the previous response as \`next\_cursor\`.\
> \### Cost per Request\
> Cost per request = 3 credits.\
> \### Available Plans\
> Available on the following plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"WalletTokenPositionsResponse":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"data":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WalletTokenPosition"}},"paging":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page; null on the last page."}}}}}}},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]},"WalletTokenPosition":{"type":"object","properties":{"chain":{"type":"string"},"wallet":{"type":"string"},"token_address":{"type":"string"},"token_symbol":{"type":"string"},"token_name":{"type":"string"},"platform":{"type":"string","description":"The token launch platform code."},"platform_ui":{"type":"string","description":"The human-readable token launch platform name."},"collateral":{"type":"string","description":"The token the position was traded against."},"bought_usd":{"type":"number"},"bought_native":{"type":"number"},"bought_amount":{"type":"number"},"sold_usd":{"type":"number"},"sold_native":{"type":"number"},"sold_amount":{"type":"number"},"sold_fees_usd":{"type":"number"},"sold_fees_native":{"type":"number"},"holding_usd":{"type":"number"},"holding_native":{"type":"number"},"holding_amount":{"type":"number"},"holding_raw":{"type":"string","description":"The holding in the token's smallest unit."},"realized_profit_usd":{"type":"number"},"realized_profit_native":{"type":"number"},"realized_profit_roi":{"type":"number"},"realized_profit_roi_native":{"type":"number"},"unrealized_profit_usd":{"type":"number"},"unrealized_profit_native":{"type":"number"},"unrealized_profit_roi":{"type":"number"},"unrealized_profit_roi_native":{"type":"number"},"total_profit_usd":{"type":"number"},"total_profit_native":{"type":"number"},"total_profit_roi":{"type":"number"},"total_profit_roi_native":{"type":"number"},"current_price_usd":{"type":"number"},"current_price_native":{"type":"number"},"market_cap":{"type":"number"},"avg_buy_price_usd":{"type":"number"},"avg_buy_price_native":{"type":"number"},"avg_sell_price_usd":{"type":"number"},"avg_sell_price_native":{"type":"number"},"avg_buy_market_cap_usd":{"type":"number"},"avg_sell_market_cap_usd":{"type":"number"},"last_trade_timestamp":{"type":"integer","description":"Unix timestamp of the wallet's last trade in this token."},"migrated_at":{"type":"integer","nullable":true,"description":"Unix timestamp of the token's migration off its launchpad, if any."},"has_cost_basis":{"type":"boolean","description":"False for holdings the wallet never traded on Cielo (transferred in, airdropped, bought elsewhere); their cost-basis and PnL fields are zero."},"cost_basis_carried":{"type":"boolean","description":"True when the cost basis was carried over from another wallet in the same request that bought the tokens and transferred them here."}}},"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/wallet/positions":{"get":{"tags":["Wallet"],"summary":"Wallet Token Positions","description":"This endpoint retrieves per-token trading positions for one or more wallets: amounts bought and sold, current holdings, average buy and sell prices, and realized and unrealized PnL in USD and in the chain's native token.\nResults are paginated with a cursor: pass `paging.next_cursor` from the previous response as `next_cursor`.\n### Cost per Request\nCost per request = 3 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getWalletTokenPositions","parameters":[{"name":"chain","in":"query","description":"Chain to query. `all` returns positions from both Base and Solana.","required":true,"schema":{"type":"string","enum":["base","solana","all"]}},{"name":"wallets","in":"query","description":"Comma-separated wallet addresses.","required":false,"schema":{"type":"string"}},{"name":"token_addresses","in":"query","description":"Comma-separated token addresses to filter by.","required":false,"schema":{"type":"string"}},{"name":"active_positions","in":"query","description":"Return only positions with a non-zero holding.","required":false,"schema":{"type":"boolean"}},{"name":"collateral","in":"query","description":"Filter by the collateral the position was traded against.","required":false,"schema":{"type":"string"}},{"name":"sort_by","in":"query","description":"Sort order.","required":false,"schema":{"type":"string","enum":["bought_usd_asc","bought_usd_desc","bought_native_asc","bought_native_desc","sold_usd_asc","sold_usd_desc","sold_native_asc","sold_native_desc","holding_usd_asc","holding_usd_desc","holding_native_asc","holding_native_desc","realized_profit_usd_asc","realized_profit_usd_desc","realized_profit_native_asc","realized_profit_native_desc","avg_buy_price_usd_asc","avg_buy_price_usd_desc","avg_buy_price_native_asc","avg_buy_price_native_desc","avg_sell_price_usd_asc","avg_sell_price_usd_desc","avg_sell_price_native_asc","avg_sell_price_native_desc","last_trade_timestamp_asc","last_trade_timestamp_desc"]}},{"name":"limit","in":"query","description":"Maximum number of positions to return.","required":false,"schema":{"type":"integer"}},{"name":"next_cursor","in":"query","description":"Cursor from the previous response's `paging.next_cursor`.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletTokenPositionsResponse"}}}},"400":{"description":"Bad Request - `chain` is missing or invalid, or `sort_by` is invalid.","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"}}}},"408":{"description":"Request Timeout","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"}}}}}}}}}
```

## Enhanced Aggregated Stats

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"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/{wallet}/enhanced-stats/aggregated":{"get":{"tags":["Wallet"],"summary":"Enhanced Aggregated Stats","description":"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.\n### Cost per Request\nCost per request = 20 credits.\n### Available Plans\nAvailable on the following plans:\n- Whale\n- Builder\n- Architect\n- Enterprise\n","operationId":"getWalletEnhancedAggregatedStats","parameters":[{"name":"wallet","in":"path","description":"The wallet address to get enhanced aggregated stats for.","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","description":"Time range filter. Supported options - 1d, 7d, 30d and max.","required":false,"schema":{"type":"string"}},{"name":"from_timestamp","in":"query","description":"Unix timestamp for the start of the time range.","required":false,"schema":{"type":"integer"}},{"name":"to_timestamp","in":"query","description":"Unix timestamp for the end of the time range.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request - Invalid wallet address or query parameters.","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"}}}}}}}}}
```

## Profitability & Performance Stats

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"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/{wallet}/enhanced-stats/profitability-performance":{"get":{"tags":["Wallet"],"summary":"Profitability & Performance Stats","description":"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.\n### Cost per Request\nCost per request = 20 credits.\n### Available Plans\nAvailable on the following plans:\n- Whale\n- Builder\n- Architect\n- Enterprise\n","operationId":"getWalletProfitabilityAndPerformance","parameters":[{"name":"wallet","in":"path","description":"The wallet address to get profitability stats for.","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","description":"Time range filter. Supported options - 1d, 7d, 30d and max.","required":false,"schema":{"type":"string"}},{"name":"from_timestamp","in":"query","description":"Unix timestamp for the start of the time range.","required":false,"schema":{"type":"integer"}},{"name":"to_timestamp","in":"query","description":"Unix timestamp for the end of the time range.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request - Invalid wallet address or query parameters.","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"}}}}}}}}}
```

## Enhanced Aggregated Stats V2

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"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/v2/enhanced-stats/aggregated":{"get":{"tags":["Wallet"],"summary":"Enhanced Aggregated Stats V2","description":"This endpoint retrieves enhanced aggregated trading statistics with support for multi-bundle wallets via the multi_bundle_id parameter.\n### Cost per Request\nCost per request = 25 credits.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getWalletEnhancedAggregatedStatsV2","parameters":[{"name":"wallet","in":"query","description":"The wallet address to get enhanced aggregated stats for.","required":false,"schema":{"type":"string"}},{"name":"multi_bundle_id","in":"query","description":"Multi-bundle ID to aggregate stats across multiple wallets.","required":false,"schema":{"type":"integer"}},{"name":"days","in":"query","description":"Time range filter. Supported options - 1d, 7d, 30d and max.","required":false,"schema":{"type":"string"}},{"name":"from_timestamp","in":"query","description":"Unix timestamp for the start of the time range.","required":false,"schema":{"type":"integer"}},{"name":"to_timestamp","in":"query","description":"Unix timestamp for the end of the time range.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request - Invalid parameters.","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"}}}}}}}}}
```

## PnL Tokens Chart

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"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/{wallet}/pnl/tokens-chart":{"get":{"tags":["Wallet"],"summary":"PnL Tokens Chart","description":"This endpoint retrieves PnL time series chart data for a specified wallet, showing profit/loss over time with ROI calculations.\n### Cost per Request\nCost per request = 15 credits.\n### Available Plans\nAvailable on the following plans:\n- Whale\n- Builder\n- Architect\n- Enterprise\n","operationId":"getTokensPnLChart","parameters":[{"name":"wallet","in":"path","description":"The wallet address to get PnL chart data for.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Accepted - Data is not ready yet. Retry in 10 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Bad Request - Invalid wallet address or query parameters.","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"}}}}}}}}}
```

## Monthly PnL

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

```json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Wallet","description":"Per-wallet analytics — token and NFT PnL, trading and enhanced stats, portfolio, balances, token flows and related wallets."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"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/{wallet}/pnl/month":{"get":{"tags":["Wallet"],"summary":"Monthly PnL","description":"This endpoint retrieves monthly PnL data for a specified wallet, showing profit/loss aggregated by month.\n### Cost per Request\nCost per request = 5 credits.\n### Available Plans\nAvailable on the following plans:\n- Whale\n- Builder\n- Architect\n- Enterprise\n","operationId":"getMonthlyPnL","parameters":[{"name":"wallet","in":"path","description":"The wallet address to get monthly PnL data for.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Accepted - Data is not ready yet. Retry in 10 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Bad Request - Invalid wallet address or query parameters.","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"}}}}}}}}}
```
