Skip to main content
Wallet Analytics add-on. Portfolio-level analytics for any Cardano stake address: current holdings, value over time, the wallet’s executed trades, and realized/unrealized profit-and-loss computed on a FIFO (first-in, first-out) cost basis.
Endpoints on this page require the Wallet Analytics add-on, on its own or through the Data or Complete bundle. Without it they return HTTP 402 with "addon": "walletAnalytics". Available on Starter, Builder, Growth and Scale, included in Enterprise. The trades and status routes are served through Nexus only.
Base URL: https://nexus.gerowallet.io · Auth: X-Api-Key: nxs_…

Endpoints

Example

P&L is computed FIFO: each disposal is matched against the earliest acquisitions to derive cost basis and realized gains. Holdings still held are marked to current market price for unrealized P&L.

Check a wallet first: status

GET /api/wallet/{stakeAddress}/status says what holdings, trades, value history and P&L will answer for a wallet right now, so you can pick which views to show and what to say before calling them. It is cheap and never starts fetching the wallet’s history.
An invalid stakeAddress is a 400 with errorCode INVALID_STAKE_ADDRESS.

Trade history

GET /api/wallet/{stakeAddress}/trades lists executed trades of one token against ADA, taken from the wallet’s own ADA flow, one row per wallet transaction, newest first. stakeAddress is a mainnet stake address (stake1..., script stake addresses included), all lower case, checksum checked. The route serves mainnet only.
Every listed trade is one the P&L prices, but not every trade the P&L prices is listed. The P&L additionally prices fills it finds through the swap index (for example an order fill on a DEX named under ORDER_WITHOUT_USER_STAKE_ADDRESS), which are not listed, so totals summed from this list can be lower than the P&L’s. You cannot reproduce the P&L’s totals by summing this list.
order, venue and side are case-insensitive, and so is the hex in unit. Pass nextCursor back as cursor to read the next page, with the same filters. On the last page nextCursor is null. The list behind the pages is computed per wallet and kept for up to 30 minutes, so a new trade can take that long to appear. It is kept separately on each server instance, so two pages can come from lists computed at different times and carry different computedAt values; the cursor stays valid either way.
Amounts and prices are strings so they keep full precision. A field with no value is sent as null, never left out. scan says how the page was read. For most wallets mode is FULL: pages are cut from the wallet’s whole list, and a page holds fewer than limit rows only when it is the last. For a very large wallet mode is WINDOWED: each page reads only the next stretch of the wallet’s history, so a page can hold fewer rows than limit, even none, and still carry a nextCursor. partial is then true, and scannedTo is the block time (unix seconds) the read reached, which you can show as “searched back to”. Keep requesting nextCursor until it is null; show a loading row rather than an end of list while partial is true.

What is and is not a trade

A row is a transaction in which the wallet itself swapped exactly one token against ADA on a DEX or launchpad: the wallet’s own net flow in that transaction is ADA one way and a single token the other, and the transaction went through a DEX order, a DEX pool or a launchpad. The amounts are what actually entered and left the wallet. Every listed trade is one the P&L prices, but the P&L also prices fills found through the swap index that are not listed here, so the list’s totals can be lower than the P&L’s. Some trades are not in the list. Every response says which, in coverage.excludes, with a code and a short note you can show to your users as is. In this version they are: coverage.includes lists what the list does cover: always ADA_PAIRED_SWAPS, ORDER_FILLS_WITH_USER_STAKE_ADDRESS, OWN_ORDER_FILLS_WITHOUT_USER_STAKE_ADDRESS and DIRECT_POOL_SWAPS, plus SOLADA_CURVE when Solada launchpad trades are included, as they are today. Read includes rather than assuming a launchpad is covered. Both lists are the same on every page of a wallet; excludes changes only with coverage.ruleVersion, except that a very large wallet’s pages also carry BEFORE_INDEX_START. coverage.enrichmentDegraded is true when a secondary lookup failed for this response. The answer is still a 200 and every trade is still listed, but ticker, marketPriceAda, aggregator or venues may be null or empty and decimals may be 0. Such a list is not kept, so calling again later recomputes it.

First call for a wallet: 202 Accepted

History, P&L and trades need a wallet’s full on-chain history. The first call for a wallet starts fetching it. That takes seconds for most wallets and a few minutes for wallets with thousands of transactions. Until it finishes, /history, /pnl, /trades and POST /api/wallet/pnl answer HTTP 202 with a Retry-After header and no P&L, history or trade data:
Call again after retryAfterSeconds. reason says why the answer is not ready; today it is always BACKFILL, and an unknown value should be treated the same way. backfill is COMPLETE, IN_PROGRESS, or FAILED (retried automatically; the hint is then 300 s). Holdings never waits for it. Paging through /trades with cursor does not start a new fetch.

Very large wallets and timeouts

A wallet with more than 50,000 indexed UTxOs (an exchange, a bot, a busy treasury) is too large for holdings, value history and P&L, which read its whole history at once. For such a wallet:
  • /trades answers 200, page by page. Each page reads only the next stretch of the wallet’s history (scan.mode WINDOWED), so it stays fast however large the wallet is. Pages can be short or empty and still carry nextCursor; see scan under Trade history. The wallet’s history from before 2025-01-01 is not fetched (coverage code BEFORE_INDEX_START), so /trades never answers 202 for it.
  • /holdings, /history, /pnl and POST /api/wallet/pnl answer HTTP 422 WALLET_TOO_LARGE. Retrying does not help. The body’s details says what the wallet is still served:
Call /status first to know a wallet is LARGE before calling the rest, and show your users the trade history with a note such as “P&L isn’t available for wallets with this much history”. Timeouts:
  • HTTP 502, on every endpoint on this page: reading the wallet’s history took too long and was cancelled, or, for /trades, reading what admits its trades failed. No wallet data is returned and nothing is cached; retry later. The body is {"error": "upstream_unavailable", "status": 502, "requestId": "..."}.

Invalid requests: 400

/trades checks its parameters before doing any work. A 400 body carries an errorCode: The body is {"errorCode": "INVALID_CURSOR", "message": "cursor is not one this endpoint issued", ...} with a timestamp. Nexus passes it through unchanged. Full request/response schemas are in the API Reference.