Wallet positions API

GET/wallets/:chain/:address/positions

Every token the wallet traded since indexing began, open, closed or all: amounts, average prices, realized and unrealized PnL. With token=, one position.

Parameters

Name	In	Type	Default	Allowed values
`chain`	path	string	required	`evm:56` (BSC), `solana`, `evm:8453` (Base), `evm:4663` (Robinhood Chain) or `evm:1` (Ethereum)
`address`	path	string	required	Wallet address (BSC) or account (Solana)
`token`	query	string	none	One position: a token address or mint, or `native` for BNB, ETH or SOL
`status`	query	string	`all`	`open`, `closed`, `all`
`sort`	query	string	`recent`	`recent` (last trade), `pnl` (total), `realized`, `volume`
`limit`	query	integer	`50`	1–200
`cursor`	query	string	first page	The previous page's `next`, as it came

Response

Field	Type	Meaning
`chain`, `wallet`, `labels`, `indexedSince`, `status`	string, string, string[], number, string	As in every wallet answer, with its labels.
`positions[]`	array	Highest first by `sort`; a null PnL sorts last, ties by token address.
`positions[].token`	{ address, symbol, name, decimals }	`address` is `"native"` for BNB, ETH or SOL.
`quote`	boolean	A stablecoin, or the native or wrapped native token: listed, but left out of every wallet total.
`trades`, `buys`, `sells`, `unpricedTrades`	number	The swaps of the token. A buy is one where the wallet received it. `unpricedTrades` had no USD price and are left out of the USD figures.
`bought`, `sold`	string	Token amounts, decimals applied.
`open`	string	`bought − sold`, at least 0: what the trades leave held. Transfers are not counted, so it can differ from the balance.
`boughtUsd`, `soldUsd`	number	USD value of the priced buys and sells.
`avgBuyPriceUsd`, `avgSellPriceUsd`	number \| null	USD per token over the priced buys, and sells. Null without one.
`priceUsd`, `priceAt`	number \| null	The token's price now, and the start of the hour of the swap it came from, unix ms (see Wallets and PnL).
`realizedPnlUsd`, `unrealizedPnlUsd`, `totalPnlUsd`	number \| null	See Wallets and PnL. Null is unknown, never 0.
`firstTradeAt`, `lastTradeAt`	number	Unix ms.
`next`	string \| null	Cursor for the next page. Null on the last.
`position`	object \| null	With `token`, in place of `positions`: that position, null when the wallet never traded the token.

Example

Captured 2026-09-28 18:03 UTC on a test instance, trimmed to 2 positions.

curl -s -H 'Authorization: Bearer <key>' 'https://app.aurelia.build/api/wallets/evm:56/0x3304e22ddaa22bcdc5fca2269b418046ae7b566a/positions?sort=pnl&limit=2'

{
  "chain": "evm:56",
  "wallet": "0x3304e22ddaa22bcdc5fca2269b418046ae7b566a",
  "labels": [
    "sniper",
    "fresh"
  ],
  "indexedSince": 1790546261920,
  "status": "all",
  "positions": [
    {
      "token": {
        "address": "0xa9fcda9bd321adeb7cbbbd30ef2dd0ed1d657777",
        "symbol": "TAX",
        "name": "Tax Token",
        "decimals": 18
      },
      "quote": false,
      "trades": 22,
      "buys": 12,
      "sells": 10,
      "unpricedTrades": 0,
      "bought": "20118000",
      "sold": "9800",
      "open": "20108200",
      "boughtUsd": 1008,
      "soldUsd": 60,
      "avgBuyPriceUsd": 0.00005010438413361169,
      "avgSellPriceUsd": 0.006122448979591836,
      "priceUsd": 0.006,
      "priceAt": 1790618400000,
      "realizedPnlUsd": 59.5089770354906,
      "unrealizedPnlUsd": null,
      "totalPnlUsd": 59.5089770354906,
      "firstTradeAt": 1790546864920,
      "lastTradeAt": 1790618578665
    },
    {
      "token": {
        "address": "0x5eed00000000000000000000000000000000b444",
        "symbol": "NEWT2",
        "name": "Newt Two",
        "decimals": 18
      },
      "quote": false,
      "trades": 1,
      "buys": 1,
      "sells": 0,
      "unpricedTrades": 0,
      "bought": "20000000",
      "sold": "0",
      "open": "20000000",
      "boughtUsd": 300,
      "soldUsd": 0,
      "avgBuyPriceUsd": 0.000015,
      "avgSellPriceUsd": null,
      "priceUsd": 0.000015000000000000002,
      "priceAt": 1790546400000,
      "realizedPnlUsd": 0,
      "unrealizedPnlUsd": 3.3881317890172014e-14,
      "totalPnlUsd": 3.3881317890172014e-14,
      "firstTradeAt": 1790547464920,
      "lastTradeAt": 1790547464920
    }
  ],
  "next": "3.3881317890172014e-14_0x5eed00000000000000000000000000000000b444"
}

Notes

A position is closed when its trades left at most 0.1% of what they bought open (open), as a position sold down to dust is; one the wallet only sold is closed too.
Quote positions (quote: true) are listed with their PnL, which is only the price move of the currency paid with: every wallet total leaves them out.
A page continues after the previous page's last position in the order as it is when read: sorted by PnL, a position can change place between pages as prices move.
From the wallet's own rows, never the chain: one database query on a miss. Cached 5 s. The positions channel sends them again as they change.

Try it in the interactive docs Create a free account