StatusTerminal
APIUse casesOracleMCP & AgentsSDKsSkillsChangelog

Open and closed positions of a wallet

GET
/chains/{chain}/wallets/{address}/positions

One row per token the wallet traded, averaging every entry and exit cycle together. When a per-cycle view is wanted, read /rounds instead.

basis_is_incomplete marks a position that received tokens the indexer could not price, so its PNL is a floor rather than a figure. Each row carries the traded token's token_score and token_status; statuses 999 and 1000 are terminal, and a position in one of those is a position in a condemned token whatever the score says.

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

state?string
Default"any"

Value in

  • "any"
  • "open"
  • "closed"
sort?string

token is the stable address order used for plain listing. hold measures first buy to last sell, so it is only meaningful on closed positions. Every value sort runs descending.

Default"token"

Value in

  • "token"
  • "realized_pnl"
  • "unrealized_pnl"
  • "hold"
limit?integer

page size; plans above startup may raise the ceiling

Formatint32
Range1 <= value <= 100
Default10
cursor?string

opaque cursor from next_cursor or prev_cursor

Lengthlength <= 512

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/positions"
{  "items": [    {      "token_address": "string",      "token_symbol": "string",      "qty_held": 0.1,      "cost_basis_usd": 0.1,      "realized_pnl_usd": 0.1,      "realized_pnl_pct": 0.1,      "unrealized_pnl_usd": 0.1,      "bought_usd": 0.1,      "sold_usd": 0.1,      "bought_qty": 0.1,      "sold_qty": 0.1,      "avg_entry_price": 0.1,      "avg_exit_price": 0.1,      "fees_usd": 0.1,      "buy_txs": 0,      "sell_txs": 0,      "hold_seconds": 0,      "first_trade_at": "string",      "last_trade_at": "string",      "closed_at": "string",      "basis_is_incomplete": true,      "unsellable": true,      "token_score": 0,      "token_status": 0,      "pairs": [        {          "address": "string",          "ticker": "string",          "dex_name": "string",          "liquidity_usd": 0.1,          "status": 0,          "score": 0,          "unsellable": true,          "rugged": true        }      ]    }  ],  "next_cursor": "string"}

Trader profile with metrics for every window GET

Everything known about one trader on one chain: capital tier, behaviour labels, the two scores with the reasons behind them, and `metrics` once per window so a client switches window without another round trip. `rebuild_skipped` true means the zeroes are a decision rather than a gap — the wallet is classified as machinery nobody can copy. `human_known` false means the timing evidence was too thin to have an opinion, which caps the score and is not the same as a wallet judged mid-range.

Raw trade history of a wallet GET

Every trade the wallet made on this chain, newest first. `side` separates a real swap from a bare token movement: `transfer_in` and `transfer_out` carry no price and must not be counted as trading. `fee_is_estimated` true means the fee was modelled rather than read from the receipt.