Skip to main content
GET
GET /v1/wallet/positions · 2 credits
Live: the wallet-positions stream channel keeps these rows up to date as the wallet trades and moves tokens, and wallet-portfolio adds their live value and unrealized PnL.
Every position of a wallet with entry and exit prices, cumulative amounts and PnL: exact 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 minLiquidityUsd of real reserves (default $1,000), which keeps airdropped spam out; pass minLiquidityUsd=0 to list every received holding. A holding on a thin pool is then valued at what that pool can pay out, often close to zero, while a holding with no market at all keeps amountUsd at null, so a worthless holding and an unknown value stay distinct. Traded positions are never filtered by liquidity. 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. amount is the wallet’s exact on-chain balance, a decimal string at the token’s full precision, already scaled by decimals (the token’s decimals); token quantities (amount, boughtTokens, soldTokens) are plain decimal strings, never in exponent notation, and never carry more decimals than the token. marketCapUsd is the token’s current market cap, currentPriceUsd times its circulating supply (the total supply minus the tokens held by burn addresses; the asset’s circulating supply for the largest tokens by market cap), 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. pool is the token’s main pool, the one /v1/token reports: its address, its type (the key of exchanges in /v1/meta/factories; null when the pool has no known type), its exchange (display name and logo; null for a venue we do not list, and logo is null when we have none) and liquidityUsd, the liquidity of that pool in USD, the same figure as pool.liquidityUsd of /v1/token (on multi-chain major assets such as WBTC, on native coins and on the main stablecoins, /v1/token leaves that field null; the row still carries the pool’s own liquidity). fdvUsd is the fully diluted value, currentPriceUsd times the total supply, the same figure as /v1/token. pool is null when the token has no live market and pool.liquidityUsd when the pool’s reserves are unknown; fdvUsd is null on native and stable rows and on multi-chain major assets such as WBTC, whose value is read on /v1/token. native and stable rows carry the same pool object as a position: on a stable row it is the stablecoin’s main pool; on a native row (the native coin and its wrapped form) it is the chain’s reference market for the native coin, the pool /v1/token reports for the coin; it is null on a chain that has no such market, as when the native coin is itself a USD stablecoin. On those rows too, pool.liquidityUsd is the liquidity of that pool alone, not the liquidity of the asset across all its markets. On Solana, amountUsd can be valued against a deeper market of the token than its main pool, so it can exceed what pool.liquidityUsd alone would pay out. isHoneypot tells whether the token can be sold, the same flag as risk.isHoneypot of /v1/token: true when it cannot (on EVM a sell loses its whole value, and a token from a launchpad or a known token factory is never flagged this way; on Solana the mint is non-transferable), false when no block is known (on EVM a sell was measured below that; on Solana the mint is transferable, with no active transfer hook, no pause and no accounts frozen by default), null when not known for that token. On EVM a position row carries the flag when it is already known for the token and null otherwise; /v1/token and /v1/token/security compute it for a given token. It is always null on native and stable rows. labels lists the wallet’s labels on the row, as they stand now: dev when the wallet is the token’s creator, sniper, bundler and whale from the wallet’s trading on that token, proTrader, smartTrader, freshTrader and kol when the wallet itself carries the label (repeated on each of its rows; on Solana, freshTrader is a label of the token, from the wallet’s first buy of it). 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. key identifies the row, unique in a response: <chain>:<token address>, the same key as the rows of the wallet streams, followed by :native or :stable on those rows. share is the position’s share of meta.summary.totalValueUsd, in percent, the same on every page; null when amountUsd is null or meta.summary.totalValueUsd is 0.
amountUsd is the position’s market value at the depth of the token’s market: the proceeds of selling the whole amount, pool fee included, into its main pool on EVM and into the deepest live pool of the token on Solana, 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. 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 native coin’s USD price at the time of each trade, on EVM and Solana alike.
Chains. Omit chain for every EVM chain of a hex address (a base58 address is Solana), pass chain for one chain, or chains for several: public chain ids comma-separated (chains=evm:8453,evm:1) or as a repeated parameter, evm for every EVM chain. Rows and meta.summary cover the requested chains only. Every chain must belong to the wallet’s family; send chain or chains, not both. The call costs 2 credits whatever the number of chains.
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. These rows are balances: they carry no buys, no sells and no PnL, even when the wallet swapped the native coin or the stablecoin directly; those swaps are listed by /v1/wallet/trades. They are never filtered by minLiquidityUsd. 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. Every native row also carries nativeAmount and wrappedAmount, decimal strings in the format of amount: the part of the balance held as the coin itself and the part held wrapped. On Solana the native row is the SOL balance plus wrapped SOL, so nativeAmount is the SOL balance and wrappedAmount the wrapped SOL; on EVM chains the coin’s row carries nativeAmount (wrappedAmount is null) and the wrapped token’s row carries wrappedAmount (nativeAmount is null). A stable row carries both at null; position rows do not carry these two fields.
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 on the requested chains, whatever minValueUsd and the page are; value and unrealized PnL cover the positions that carry an amountUsd, and valued is the number of those positions; 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. Omit for every EVM chain of a hex address; a base58 address is Solana.

chains

Public chain ids, comma-separated or as a repeated parameter: evm:<id>, solana, or evm for every EVM chain (combine it with explicit ids freely). Rows and summary cover those chains only. Every chain must belong to the wallet's family (EVM chains for a hex address, solana for a base58 address). Send chain or chains, not both; omit both for every EVM chain of a hex address.

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
minLiquidityUsd
number
default:1000

Holdings received without a trade (a transfer, an airdrop) are only listed when their main pool holds at least this much real liquidity, in USD. Default 1000 (airdropped spam left out); pass 0 to list every received holding. Traded positions are never filtered by liquidity.

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.