Skip to main content
GET
GET /v1/wallet/positions · 2 credits Every position of a wallet with entry and exit prices, cumulative amounts and PnL: amount held, USD value, average entry and average exit, bought and sold totals, realized + unrealized + total PnL, trade counts and first/last trade timestamps. Optional native and stablecoin balances read on-chain, pagination. EVM and Solana.
Lists the tokens currently held that the wallet has traded, plus the real holdings it received without trading them (a transfer, an airdrop, a routing leg): those carry buys and sells at 0 and no entry price. Every row carries a kind: position for a traded token or a received holding. Received holdings are only listed when their main pool holds at least $1,000 of real reserves, which keeps airdropped spam out. iconUrl is the token logo, an https URL ready to render (null when no image is known). entryPriceUsd is the current bag’s average entry; entryPriceLifetimeUsd is the average over the position’s whole life; exitPriceUsd is the average price of every sell (null when nothing was sold). boughtTokens, soldTokens, boughtUsd and soldUsd are the position’s lifetime totals, and firstTradeAt is the wallet’s first trade ever on the token. holdingSince is when the current bag was opened: it starts over each time the wallet fully exits the token and buys back, so it is the timestamp to use for a “holding for” display (null when it cannot be established from the wallet’s trades). The realized counterpart of each fully-exited position is on /v1/wallet/closed-positions: across the two endpoints the realized PnL of a token is counted exactly once. decimals is the token’s decimals (amount is already scaled). marketCapUsd is the token’s current market cap, currentPriceUsd times its total supply, the same figure as /v1/token; it is null on native and stable rows and on multi-chain major assets such as WBTC, whose market cap is read on /v1/token. labels lists the wallet’s badges on the row: dev when the wallet is the token’s creator, sniper, bundler and whale from the wallet’s trading on that token, proTrader and smartTrader when the wallet itself carries the badge (repeated on each of its rows). It is [] on native and stable rows. buyFeesUsd, sellFeesUsd and totalFeesUsd are the fees the wallet paid trading this token (network fees, tips and platform fees, in USD at the time of each transaction); null when not available for the position.
amountUsd is the position’s market value at the depth of its main pool: the proceeds of selling the whole amount into that pool, pool fee included, so a large position on a thin pool is worth what the pool can actually pay out. Positions on a live bonding curve are valued at the curve price. currentPriceUsd is the market price of the token; unrealizedPnlUsd is amountUsd minus the cost basis. amountUsd and unrealizedPnlUsd are null when the position has no pool with usable reserves to value it against, including a held token with no live market on the chain; currentPriceUsd is null when the main pool carries no plausible market price. entryPriceUsd, entryPriceLifetimeUsd, exitPriceUsd and realizedPnlUsd come from the wallet’s trades and are always served when the wallet traded the token. On Solana, every USD figure drawn from the wallet’s trades (entry and exit prices, boughtUsd, soldUsd, realized PnL and the cost basis behind unrealizedPnlUsd) is valued at the SOL price at the time of each trade; on EVM chains, at the current native price.
includeNative=true adds the wallet’s native coin balance (and its wrapped form) as rows of kind native; includeStables=true adds its USD stablecoin balances (kind stable). Both are read on-chain at request time, served at face value with no PnL fields, and counted in summary.totalValueUsd. Without the flags these balances are not part of the response nor of the summary. A stablecoin the wallet actually traded is a position either way. kind stable is reserved to the canonical USD stablecoins (on Solana: USDC, USDT, USDS, USD1 and PYUSD, by mint; on EVM: the stablecoins of our registry, by contract address): any other token is a position, whatever its symbol. On Solana the native row is the SOL balance plus wrapped SOL.
minValueUsd defaults to 0.05: dust positions are left out unless you pass minValueUsd=0. A traded position whose value cannot be established is always listed, since its entry price and realized PnL stand on their own. Rows are sorted by value; limit and offset page through them and meta.hasMore tells whether another page follows (omit limit to receive every row). meta.summary carries wallet-level totals (value, realized, unrealized, total PnL) computed over every position of the wallet, whatever minValueUsd and the page are; value and unrealized PnL cover the positions that carry an amountUsd; positions is the total number of rows across all pages. meta.asOf is the moment the holdings were read on-chain: a trade refreshes them within a few seconds. Returns 503 with Retry-After while holdings are momentarily unavailable.

Authorizations

​
Authorization
string
header
required

Your raw API key (not needed on the demo server).

Query Parameters

​
wallet
string
required

Wallet address (EVM hex, case-insensitive; Solana base58).

​
chain
string

Public chain id - evm:<id> or solana.

​
tokens
string

Comma-separated token addresses (1-50) to scope the response to - positions and summary cover only those tokens.

​
minValueUsd
number
default:0.05

Only positions whose amountUsd reaches this floor. Default 0.05 (dust removed); pass 0 to lift the floor. A traded position whose value is unknown is always listed; meta.summary still covers every position of the wallet.

Required range: x >= 0
​
includeNative
boolean
default:false

Also list the wallet's native coin balance (and its wrapped form) as rows of kind native, read on-chain, at face value, counted in summary.totalValueUsd. On Solana: SOL plus wrapped SOL. Default false.

​
includeStables
boolean
default:false

Also list USD stablecoin balances (kind stable), read on-chain, at face value, counted in summary.totalValueUsd. Default false.

​
limit
integer

Page size, 1-500. Omit to receive every row.

Required range: 1 <= x <= 500
​
offset
integer
default:0

Rows to skip. Default 0.

Required range: x >= 0

Response

200

Standard { data, meta } envelope.