Skip to main content
GET
Get Wallet Positions History
Alpha — This endpoint is in early access. Response shape, field names, and sort/pagination semantics may change without notice.

What it returns

Unlike /wallet/positions which returns one row per token (lifetime aggregate), this endpoint returns one row per closed trading cycle. A trader who bought/sold the same coin three separate times will appear three times here, each with its own realized PnL — exactly as they would on an exchange trade-history panel. Currently open positions are excluded. Use /wallet/positions or /wallet/position-history to see them.

Query Parameters

ParameterTypeRequiredDescription
walletstringYesWallet address.
chainIdsstringNoComma-separated list of chain IDs (e.g. evm:1,solana:solana). If omitted, all chains.
limitnumberNoPage size. 1–200, default 50.
offsetnumberNoPagination offset, default 0.
sortBystringNoOne of exitDate (default), entryDate, realizedPnl.
orderstringNoasc or desc (default).

Usage Examples

Top 10 most-profitable closed trades:
Most recent exits, Solana only:

Sample Response

Cycle semantics

Each cycle object uses the exact same field set as /wallet/position-history. Refer to that page for per-field documentation. Because this endpoint filters to closed cycles only, isOpen is always false, exitDate is always set, remainingBalance is 0 (±dust), unrealizedPnlUSD is 0, and currentPriceUSD is null.

Performance

The endpoint scans all trade swaps for the wallet once (server-side Postgres bitmap index on swap_recipient_id / transaction_sender_address_id), groups them by token, detects cycles in-memory, and paginates the global list. Candidate tokens are pre-filtered to those with at least one sell on record — a token never sold cannot have a closed cycle. Typical latency:
Wallet sizeLatency
< 1 000 swaps< 300 ms
10 000 swaps~700 ms
70 000 swaps (super-trader)~2 s

SDK Usage

Use Cases

  • Top-trades leaderboards: surface a trader’s best and worst closed positions.
  • Backtest alpha: evaluate how well a wallet recycles profits across different plays.
  • Follow-the-whale: watch which tokens a known trader is actually closing vs. still holding.

Query Parameters

wallet
string
required

Wallet address

chainIds
string

Comma-separated list of chain IDs (e.g., "evm:1,solana:solana"). If omitted, all chains.

limit
number

Number of closed positions per page (1-200, default 50)

Required range: 1 <= x <= 200
offset
number | null

Offset for pagination (default 0)

Required range: x >= 0
sortBy
enum<string>

Sort field (default exitDate)

Available options:
exitDate,
realizedPnl,
entryDate
order
enum<string>

Sort order (default desc)

Available options:
asc,
desc

Response

200 - application/json

Paginated closed-cycle history.

data
object[]
required
pagination
object
required