> ## 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. # Resolve an ADA Handle to an address > Returns the address currently holding an ADA Handle, with its stake address when it has one. A handle is a native token, so this is a live lookup: it follows the token, and changes the moment the token is spent to someone else. Accepts the handle with or without its leading dollar sign and in any casing. Both the legacy bare-name token and the CIP-68 user token are matched, and the CIP-68 one wins if both are unspent. Served from cardano-db-sync, so it is available only on networks with a chain database configured. ## OpenAPI ````yaml https://nexus.gerowallet.io/v3/api-docs get /api/handles/{handle} 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_STAGENET` 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 · 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/handles/{handle}: get: tags: - Cardano · Handles summary: Resolve an ADA Handle to an address description: >- Returns the address currently holding an ADA Handle, with its stake address when it has one. A handle is a native token, so this is a live lookup: it follows the token, and changes the moment the token is spent to someone else. Accepts the handle with or without its leading dollar sign and in any casing. Both the legacy bare-name token and the CIP-68 user token are matched, and the CIP-68 one wins if both are unspent. Served from cardano-db-sync, so it is available only on networks with a chain database configured. operationId: resolve parameters: - name: network in: query required: false schema: type: string description: >- Accepts either the value listed here (`CARDANO_MAINNET`) or its kebab-case alias (`cardano-mainnet`); matching is case-insensitive. Omit it and the network is taken from the API key. A value that disagrees with the key's own network returns 400 Network Mismatch. enum: - CARDANO_MAINNET - CARDANO_PREPROD - CARDANO_PREVIEW - APEX_PRIME_MAINNET - APEX_VECTOR_MAINNET - APEX_VECTOR_TESTNET - MIDNIGHT_MAINNET - MIDNIGHT_PREPROD - MIDNIGHT_STAGENET - BITCOIN_MAINNET - BITCOIN_TESTNET4 - name: handle in: path description: The handle, with or without the leading $ required: true schema: type: string default: '' maxLength: 16 minLength: 1 example: charles responses: '200': description: Handle resolved content: application/json: schema: $ref: '#/components/schemas/HandleDto' additionalProperties: default: '' default: '' '400': description: Not a possible ADA Handle content: '*/*': schema: $ref: '#/components/schemas/HandleDto' '404': description: No unspent output holds that handle content: '*/*': schema: $ref: '#/components/schemas/HandleDto' '501': description: No chain database configured for the network content: '*/*': schema: $ref: '#/components/schemas/HandleDto' components: schemas: HandleDto: type: object default: null description: Resolution of an ADA Handle to its current holder properties: handle: type: string default: '' description: >- The handle, normalized: lowercase and without the leading dollar sign example: charles address: type: string default: '' description: Address of the unspent output currently holding the handle token example: >- addr1qxn76cvp3s8pnq0jzcrduh8jtnatm9hjk3g7gze8kfw8gzlshsg38lrquhlmrd44nxnyh4dwfypzl93s0c737skpcygq8psfu5 stakeAddress: type: - string - 'null' default: '' description: >- Stake address of the holder. Null when the handle sits at an enterprise address, which has no stake credential. example: stake1u8ctcygnl3swtla3k66enfjt6khyjq30jcc8u0glgtquzyqaths5q policyId: type: string default: '' description: The ADA Handle minting policy example: f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a assetNameHex: type: string default: '' description: >- On-chain asset name of the token that resolved, hex-encoded, including the CIP-68 user-token prefix when there is one example: 636861726c6573 cip68: type: boolean default: false description: >- True when the resolved token is a CIP-68 user token (asset name prefixed 000de140), false for a legacy handle whose asset name is the bare UTF-8 bytes example: false 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 ````