> ## Documentation Index > Fetch the complete documentation index at: https://nexus.gerowallet.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Wallet trade history > Executed trades of one token against ADA, taken from the wallet's own ADA flow, one row per wallet transaction. Every listed trade is one the P&L prices. The P&L additionally prices fills it finds through the swap index (for example orders placed from an address without the wallet's stake key), which are not listed, so totals summed from this list can be lower than the P&L's and cannot reproduce them. Mainnet only: `stakeAddress` is a lower-case `stake1...` address, checksum checked. Amounts are the wallet's own net flow, as strings: `priceAda` is the all-in price per whole token with fees included (per raw unit when `decimals` is 0 because it is unknown), `marketPriceAda` the pool-side price of the executed swap, on a split route that of the largest leg (null when none is indexed). `status` is always `EXECUTED`. `kind` is `ORDER_FILL` when the wallet's own order at a known DEX order script was filled (only then are the order fields set: the transaction that created the order UTxO the fill spent, the placement or the previous partial fill), `DIRECT_SWAP` when its own transaction swapped against a pool or took someone else's resting order, `LAUNCHPAD` for a bonding curve. `venues` may be empty. Fields with no value are sent as null. Pages are ordered by `blockTime` then `txHash` (`order`, default `desc`); pass `nextCursor` back as `cursor` for the next page; it is null on the last page. The list is computed per wallet and kept for up to 30 minutes on each server instance, so pages may carry different `computedAt` values; the cursor stays valid. Filters: `limit` (1 to 500, default 100), `from` and `to` (unix seconds, inclusive), `unit` (policy id + asset name hex), `venue` (a DEX name or `SOLADA`), `side` (`BUY` or `SELL`); `order`, `venue` and `side` are case-insensitive. An invalid parameter is a 400 whose `errorCode` is `INVALID_STAKE_ADDRESS`, `INVALID_CURSOR`, `INVALID_LIMIT`, `UNKNOWN_VENUE`, `INVALID_PARAMETER`, or `BAD_REQUEST` for a non-numeric `limit`, `from` or `to`. Every response carries a `coverage` object whose `excludes` lists, by code, each kind of trade that is not in the list (token-to-token swaps, order fills whose order address carries no user stake key, payouts to another stake key, multi-token transactions, snek.fun bonding-curve trades, direct pool swaps before 2025-01-01, open and cancelled orders, LP tokens). A wallet holding more than 50,000 indexed UTxOs answers 422 `WALLET_TOO_LARGE`; retrying does not help. The first call for a wallet starts fetching its full on-chain history. Until that finishes (seconds for most wallets, a few minutes for wallets with thousands of transactions) the answer is 202 Accepted with a PENDING body (each wallet's state and retryAfterSeconds) and a Retry-After header, with no P&L or history numbers. Call again after Retry-After seconds. ## OpenAPI ````yaml https://nexus.gerowallet.io/v3/api-docs get /api/wallet/{stakeAddress}/trades openapi: 3.1.0 info: title: Nexus API description: >- Multi-chain blockchain data API for Cardano (and Apex), Bitcoin, and Midnight. ## Blockchains & Networks Endpoints are grouped by **blockchain**. Pick the target **network** with the `network` query parameter. A network is an environment *within* a blockchain, not a separate endpoint family. - **Cardano & Apex**: one shared set of UTxO endpoints serves `CARDANO_MAINNET`, `CARDANO_PREPROD`, `CARDANO_PREVIEW`, `APEX_PRIME_MAINNET`, `APEX_VECTOR_MAINNET`, `APEX_VECTOR_TESTNET` - **Bitcoin**: `BITCOIN_MAINNET`, `BITCOIN_TESTNET4` - **Midnight**: `MIDNIGHT_MAINNET`, `MIDNIGHT_PREPROD`, `MIDNIGHT_PREVIEW`, `MIDNIGHT_STAGENET` (deprecated, removed no earlier than 2026-12-08) These are the values published on each operation's `network` schema, and what generated clients send. A kebab-case alias (`cardano-mainnet`) is also accepted, and matching is case-insensitive — see the note on the parameter itself. ### Key scope: one chain, one network Each API key is scoped to **one chain and one network**, fixed at creation time. A `CARDANO_MAINNET` key cannot query `CARDANO_PREPROD`, and it cannot query Bitcoin or Midnight at all. Create one key per chain and network under the same account. Sending a `network` value that does not match the key returns **400 Network Mismatch**; omit the parameter and the request runs against the key's own network. What is uniform across chains is the integration surface, not the credential: one account, one base URL, one auth header, one docs site. ## Authentication Send your API key in the `X-Api-Key` header. This is the credential for programmatic access (create one in the dashboard; keys start with `nxs_`). `Authorization: Bearer ` is only for JWT **session** tokens issued by `/api/auth/login` (browser/mobile apps), not for API keys. ## Add-ons Capability is gated separately from network scope. Market data, wallet analytics, transaction building, MCP, and IPFS are paid add-ons; those endpoints return **402 Payment Required** on a key whose plan does not carry the matching add-on, even when the chain and network match. contact: name: Nexus Team url: https://nexus.gerowallet.io/support email: nexus@gerowallet.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.0 servers: - url: https://nexus.gerowallet.io description: API Server security: - apiKeyAuth: [] - bearerAuth: [] tags: - name: Cardano · Blocks description: Cardano Block API - name: Cardano · Policy description: Cardano Policy API - name: IPFS description: IPFS Content Resolution API - name: Bitcoin · Ordinals description: Ordinals + runes metadata (ord indexer) - name: Partner description: Aggregator revenue share for partner key holders - name: Cardano · Metadata description: Label-scoped transaction metadata API - name: Cardano · Assets description: Token Registry Metadata - name: Cardano · Transactions description: Cardano Transactions API - name: Midnight · Transactions description: Midnight-specific transaction endpoints (unshielded UTXOs) - name: Bitcoin · Mempool description: Bitcoin mempool snapshot - name: Midnight · DUST description: DUST registration + generation status - name: Cardano · Stake Pools description: >- Cardano stake pool information including registrations, retirements, and pool metadata - name: Cardano · Network description: Cardano Network API - Query static network / genesis parameters - name: Cardano · RealFi description: >- RealFi Earn (USDr / sUSDr) read API. Wallet-keyed reads take a bech32 address; Nexus derives the key hashes RealFi matches on. Networks without a RealFi deployment answer 502 rather than guessing. - name: Cardano · Addresses description: Cardano Address API - name: Bitcoin · Addresses description: >- Bitcoin address-keyed queries: stats / balance / UTxOs via electrs; ordinals via ord - name: Bitcoin · Transactions description: Bitcoin transaction lookup and submission - name: Cardano · Governance description: >- Cardano on-chain governance: DReps, governance actions + votes, constitutional committee, constitution - name: Cardano · DReps description: >- Cardano delegate representatives (DReps): voting power, status, metadata, delegators - name: Cardano · Transaction Builder description: >- Cardano transaction building API. Builds unsigned transactions server-side for client-side signing and submission. Network can be specified in the request body or as a query parameter. Body takes precedence over query parameter. - name: Cardano · Assets description: Cardano Asset API - name: Cardano · Accounts description: Cardano Account API - name: Bitcoin · Fees description: Bitcoin fee-rate estimates by confirmation block target - name: Bitcoin · Blocks description: Bitcoin block lookup - name: Cardano · Handles description: ADA Handle resolution - name: Cardano Market Data description: Endpoints from cardano-market-data - name: Midnight · Indexer description: Transparent proxy to the Midnight GraphQL indexer - name: Cardano · Scripts description: Cardano script & datum API - name: Cardano · Epochs description: Cardano Epoch API - Query protocol parameters and epoch information - name: Bitcoin · Chain description: Bitcoin chain-tip and sync state paths: /api/wallet/{stakeAddress}/trades: get: tags: - Cardano Market Data summary: Wallet trade history description: >- Executed trades of one token against ADA, taken from the wallet's own ADA flow, one row per wallet transaction. Every listed trade is one the P&L prices. The P&L additionally prices fills it finds through the swap index (for example orders placed from an address without the wallet's stake key), which are not listed, so totals summed from this list can be lower than the P&L's and cannot reproduce them. Mainnet only: `stakeAddress` is a lower-case `stake1...` address, checksum checked. Amounts are the wallet's own net flow, as strings: `priceAda` is the all-in price per whole token with fees included (per raw unit when `decimals` is 0 because it is unknown), `marketPriceAda` the pool-side price of the executed swap, on a split route that of the largest leg (null when none is indexed). `status` is always `EXECUTED`. `kind` is `ORDER_FILL` when the wallet's own order at a known DEX order script was filled (only then are the order fields set: the transaction that created the order UTxO the fill spent, the placement or the previous partial fill), `DIRECT_SWAP` when its own transaction swapped against a pool or took someone else's resting order, `LAUNCHPAD` for a bonding curve. `venues` may be empty. Fields with no value are sent as null. Pages are ordered by `blockTime` then `txHash` (`order`, default `desc`); pass `nextCursor` back as `cursor` for the next page; it is null on the last page. The list is computed per wallet and kept for up to 30 minutes on each server instance, so pages may carry different `computedAt` values; the cursor stays valid. Filters: `limit` (1 to 500, default 100), `from` and `to` (unix seconds, inclusive), `unit` (policy id + asset name hex), `venue` (a DEX name or `SOLADA`), `side` (`BUY` or `SELL`); `order`, `venue` and `side` are case-insensitive. An invalid parameter is a 400 whose `errorCode` is `INVALID_STAKE_ADDRESS`, `INVALID_CURSOR`, `INVALID_LIMIT`, `UNKNOWN_VENUE`, `INVALID_PARAMETER`, or `BAD_REQUEST` for a non-numeric `limit`, `from` or `to`. Every response carries a `coverage` object whose `excludes` lists, by code, each kind of trade that is not in the list (token-to-token swaps, order fills whose order address carries no user stake key, payouts to another stake key, multi-token transactions, snek.fun bonding-curve trades, direct pool swaps before 2025-01-01, open and cancelled orders, LP tokens). A wallet holding more than 50,000 indexed UTxOs answers 422 `WALLET_TOO_LARGE`; retrying does not help. The first call for a wallet starts fetching its full on-chain history. Until that finishes (seconds for most wallets, a few minutes for wallets with thousands of transactions) the answer is 202 Accepted with a PENDING body (each wallet's state and retryAfterSeconds) and a Retry-After header, with no P&L or history numbers. Call again after Retry-After seconds. operationId: walletTrades parameters: - name: stakeAddress in: path required: true schema: type: string - name: limit in: query description: Rows per page, 1 to 500. required: false schema: type: integer format: int32 - name: cursor in: query description: nextCursor of the previous page. required: false schema: type: string - name: order in: query description: desc (default, newest first) or asc, by blockTime then txHash. required: false schema: type: string - name: from in: query description: Earliest blockTime, unix seconds, inclusive. required: false schema: type: integer format: int64 - name: to in: query description: Latest blockTime, unix seconds, inclusive. required: false schema: type: integer format: int64 - name: unit in: query description: 'Only this token: policy id + asset name hex.' required: false schema: type: string - name: venue in: query description: >- Only trades through this venue: a DEX name (MINSWAP_V2, SPLASH, ...) or SOLADA. required: false schema: type: string - name: side in: query description: BUY or SELL. required: false schema: type: string - name: network in: query description: >- Target Cardano network for per-network market-data instances (e.g. `preview` or `preprod`). Omit, or pass `mainnet`, for mainnet. required: false schema: type: string responses: '200': description: One page of the wallet's trades. content: '*/*': schema: $ref: '#/components/schemas/MarketDataWalletTradesPage' '202': description: >- Not ready: a requested wallet's history is still being fetched. Contains no P&L or history numbers. Never cached. headers: Retry-After: description: Seconds to wait before retrying. style: simple schema: type: object content: '*/*': schema: $ref: '#/components/schemas/MarketDataWalletBackfillPending' '400': description: >- errorCode INVALID_STAKE_ADDRESS (not a mainnet stake address), INVALID_CURSOR (not a cursor this endpoint issued), INVALID_LIMIT (outside 1 to 500), UNKNOWN_VENUE, or INVALID_PARAMETER (order, side, unit, or from after to). Checked before any work. content: '*/*': schema: $ref: '#/components/schemas/MarketDataErrorResponse' '403': description: >- Not called through Nexus: this route is served to trusted callers only (cluster-internal, or a valid X-Internal-Key). Refused before any work. content: '*/*': schema: $ref: '#/components/schemas/MarketDataWalletTradesPage' '422': description: >- WALLET_TOO_LARGE: the requested wallets hold more indexed UTxOs between them than history, holdings and P&L are computed for (50,000 by default). Retrying does not help. content: '*/*': schema: $ref: '#/components/schemas/MarketDataErrorResponse' '503': description: >- Reading the wallet's indexed history took longer than its statement timeout (30 s by default), or reading the trades' evidence failed. Contains no trades; never cached; retry later. content: '*/*': schema: $ref: '#/components/schemas/MarketDataErrorResponse' components: schemas: MarketDataWalletTradesPage: type: object description: One page of the wallet's trades of one token against ADA. properties: stakeAddress: type: string computedAt: type: integer format: int64 description: >- When the list was computed, unix seconds. Pages of one list share it. indexedFrom: type: integer format: int64 description: >- Start of the indexer's own history, unix seconds. Before it, direct pool swaps are not listed (see coverage). items: type: array items: $ref: '#/components/schemas/MarketDataWalletTrade' nextCursor: type: string description: Opaque cursor for the next page, null on the last page. coverage: $ref: '#/components/schemas/MarketDataWalletTradesCoverage' MarketDataWalletBackfillPending: type: object description: >- Wallet history or P&L is not ready: the history of at least one requested wallet from before the indexer's start is still being fetched. Retry after retryAfterSeconds; the fetch continues in the background between calls. properties: status: type: string description: Always PENDING. example: PENDING wallets: type: array description: Every requested wallet with the state of its history fetch. items: $ref: '#/components/schemas/MarketDataWalletBackfillState' retryAfterSeconds: type: integer format: int32 description: >- Seconds to wait before retrying. Also sent as the Retry-After header. example: 30 message: type: string description: Human-readable explanation. MarketDataErrorResponse: type: object properties: errorCode: type: string message: type: string details: type: array items: type: string timestamp: type: string format: date-time MarketDataWalletTrade: type: object description: >- One trade of one token against ADA that settled in the wallet's own transaction. properties: txHash: type: string description: >- The wallet tx in which the trade settled: the fill tx for an order, the swap tx for a direct swap. blockTime: type: integer format: int64 description: Block time of txHash, unix seconds. slot: type: integer format: int64 description: Slot of txHash. side: type: string description: BUY when the token came into the wallet, SELL when it left. enum: - BUY - SELL unit: type: string description: 'Token traded against ADA: policy id + asset name hex.' ticker: type: string description: Token ticker from token metadata. decimals: type: integer format: int32 description: >- Token decimals from token metadata; 0 when unknown (as in the P&L). With 0 for a token that really has decimals, tokenAmount and priceAda are per RAW unit while marketPriceAda stays per whole token, so the two prices then differ by 10^decimals. tokenAmountRaw: type: string description: >- Net token units that entered or left the wallet in txHash, raw integer, absolute. tokenAmount: type: string description: tokenAmountRaw / 10^decimals, plain decimal. adaAmountLovelace: type: string description: >- Net lovelace the wallet paid (BUY) or received (SELL) in txHash, absolute. All-in: includes batcher and network fees as the wallet saw them. priceAda: type: string description: >- Effective price, ADA per whole token, fees included: adaAmount / tokenAmount. Per raw unit when decimals is 0 for a token whose decimals are unknown (see decimals). marketPriceAda: type: string description: >- Price of the executed indexed swap for txHash and unit, ADA per whole token. Pool level: in a batched tx it covers every order in the tx. status: type: string description: 'Always EXECUTED: the tx is on chain.' enum: - EXECUTED kind: type: string description: >- ORDER_FILL: a batcher or order book filled the wallet's own order. DIRECT_SWAP: the wallet's tx swapped against a pool or a resting order. LAUNCHPAD: a launchpad venue (bonding curve). enum: - ORDER_FILL - DIRECT_SWAP - LAUNCHPAD venues: type: array description: >- Venues the trade went through: DEX names or SOLADA. More than one on a split route; empty only when enrichment was degraded. items: type: string aggregator: type: string description: >- Aggregator that routed the trade (DEXHUNTER, GERO, ...), when indexed. orderTxHash: type: string description: 'ORDER_FILL only: the tx that created the order UTxO the fill spent.' orderOutputIndex: type: integer format: int32 description: 'ORDER_FILL only: output index of that order UTxO.' orderBlockTime: type: integer format: int64 description: 'ORDER_FILL only: block time of the order''s placement, unix seconds.' MarketDataWalletTradesCoverage: type: object description: >- What the list includes and what it deliberately leaves out. The same on every page. properties: ruleVersion: type: integer format: int32 description: >- Version of the rules below. Bumped whenever what counts as a trade changes. includes: type: array description: Classes of trade the list covers in this deployment. items: type: string excludes: type: array description: >- Classes of trade the list never covers, with a note a client can show verbatim. items: $ref: '#/components/schemas/MarketDataExclusion' enrichmentDegraded: type: boolean description: >- True when an enrichment lookup failed: some ticker, decimals, marketPriceAda, aggregator or venue fields may be null or empty. No row is ever dropped for it, and such a list is not cached. MarketDataWalletBackfillState: type: object properties: stakeAddress: type: string backfill: type: string description: >- COMPLETE: history indexed. IN_PROGRESS: being fetched. FAILED: the last fetch failed and is retried automatically on a call after a cool-down. enum: - COMPLETE - IN_PROGRESS - FAILED example: IN_PROGRESS MarketDataExclusion: type: object description: One class of trade the list does not cover. properties: code: type: string note: type: string venues: type: array description: Venues the exclusion mostly concerns. items: type: string securitySchemes: apiKeyAuth: type: apiKey description: >- ### API key (programmatic access — recommended) Send your API key in the `X-Api-Key` header. Keys start with `nxs_` and are created in the dashboard (or via **POST /api/keys** with a session JWT). Each key is scoped to **one chain and one network** (for example `CARDANO_MAINNET`), fixed at creation time. It cannot query a different network on the same chain, and it cannot query a different chain at all. A mismatched `network` parameter returns **400 Network Mismatch**. Create one key per chain and network under the same account. This is the credential most integrations should use. name: X-Api-Key in: header bearerAuth: type: http description: >- ### JWT session token (browser / mobile apps) A short-lived JWT issued by `/api/auth/login` or `/api/auth/device`, sent as `Authorization: Bearer `. This is the **session** credential for the web dashboard and mobile apps, not for server-to-server API access. For programmatic API access use an **API key** in the `X-Api-Key` header instead — do **not** put an `nxs_` API key in this Bearer field. scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.