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.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.
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, incoverage.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:
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:/tradesanswers 200, page by page. Each page reads only the next stretch of the wallet’s history (scan.modeWINDOWED), so it stays fast however large the wallet is. Pages can be short or empty and still carrynextCursor; seescanunder Trade history. The wallet’s history from before 2025-01-01 is not fetched (coveragecodeBEFORE_INDEX_START), so/tradesnever answers 202 for it./holdings,/history,/pnlandPOST /api/wallet/pnlanswer HTTP 422WALLET_TOO_LARGE. Retrying does not help. The body’sdetailssays what the wallet is still served:
/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.