StatusTerminal
APIUse casesOracleMCP & AgentsSDKsSkillsChangelog

Best and worst closed trades of a wallet

GET
/chains/{chain}/wallets/{address}/best-trades

The wallet's ranked realised winners and losers over the window, and what the ranking left out.

hidden_positions and hidden_realized_pnl_usd account for the PNL outside both lists, so a profile cannot show a top three that silently contradicts the total.

Path Parameters

chain*string

chain slug (ton) or numeric chain id (950000)

Length1 <= length <= 32
address*string

the wallet address

Length1 <= length <= 128

Query Parameters

window?string

rolling window the metrics are computed over

Default"30d"

Value in

  • "1d"
  • "7d"
  • "30d"
  • "1y"
  • "all"
limit?integer

rows per list

Formatint32
Range1 <= value <= 100
Default10

Header Parameters

Accept-Payment?string

payment methods the client can use, comma-separated, case-insensitive. With x402 in the list, a spent keyless budget answers 402 with the x402 challenge instead of 429.

PAYMENT-SIGNATURE?string

base64 x402 v2 payment payload for this request. A paid request skips the keyless budget and is settled only when it answers 2xx. The v1 header X-PAYMENT is accepted too.

Response Body

application/json

application/problem+json

application/problem+json

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/chains/string/wallets/string/best-trades"
{  "winners": [    {      "token_address": "string",      "symbol": "string",      "entry_market_cap_usd": 0.1,      "exit_market_cap_usd": 0.1,      "realized_pnl_usd": 0.1,      "roi": 0.1,      "buys": 0,      "sells": 0    }  ],  "losers": [    {      "token_address": "string",      "symbol": "string",      "entry_market_cap_usd": 0.1,      "exit_market_cap_usd": 0.1,      "realized_pnl_usd": 0.1,      "roi": 0.1,      "buys": 0,      "sells": 0    }  ],  "hidden_positions": 0,  "hidden_realized_pnl_usd": 0.1}

Wallet performance series — PNL and ROI GET

One series carrying both metrics, so a chart switches between PNL and ROI without another round trip. Buckets are hourly for windows of a week or less and daily above that. A bucket's `roi` is its realised profit over the cost basis it closed. `cumulative_roi` is running realised profit over running cost basis — not a sum of the per-bucket ratios, which would be a different and meaningless number.

Position rounds — one entry and exit cycle per row GET

A wallet re-enters a token as often as it likes; a round is one buy-to-flat cycle of it. Rounds are what a per-trade PNL view needs, because a single position row averages every cycle together. Omit `token` for every token the wallet traded.