> ## 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.

# Get UTxOs for many Cardano addresses in one call

> Unspent UTxOs for up to 50 addresses in a single call, answered from one yaci-store query instead of one request per address. Every requested address appears in the response, in request order, with an empty utxos array when it holds nothing, so the response can be zipped against the request. The 50-address cap is a load guard: a single hot address can hold tens of thousands of lifetime outputs, so an uncapped batch would let one call saturate the backend. The response is also row-capped (5000 UTxOs across the whole batch by default). If the cap is hit, EVERY entry carries "truncated": true and the response is incomplete - including entries that came back empty, because the rows are ordered newest-first across the batch rather than per address. Split the request into smaller batches when you see it; the field is absent otherwise. Served by YACI direct SQL with no provider fallback.



## OpenAPI

````yaml https://nexus.gerowallet.io/v3/api-docs post /api/addresses/utxos
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 <token>` 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/addresses/utxos:
    post:
      tags:
        - Cardano · Addresses
      summary: Get UTxOs for many Cardano addresses in one call
      description: >-
        Unspent UTxOs for up to 50 addresses in a single call, answered from one
        yaci-store query instead of one request per address. Every requested
        address appears in the response, in request order, with an empty utxos
        array when it holds nothing, so the response can be zipped against the
        request. The 50-address cap is a load guard: a single hot address can
        hold tens of thousands of lifetime outputs, so an uncapped batch would
        let one call saturate the backend. The response is also row-capped (5000
        UTxOs across the whole batch by default). If the cap is hit, EVERY entry
        carries "truncated": true and the response is incomplete - including
        entries that came back empty, because the rows are ordered newest-first
        across the batch rather than per address. Split the request into smaller
        batches when you see it; the field is absent otherwise. Served by YACI
        direct SQL with no provider fallback.
      operationId: getUtxosByAddresses
      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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkAddressUtxosRequest'
        required: true
      responses:
        '200':
          description: UTxOs per address
          content:
            application/json:
              schema:
                type: array
                additionalProperties:
                  default: ''
                contains:
                  default: ''
                items:
                  $ref: '#/components/schemas/AddressUtxosDto'
                  default: ''
                unevaluatedItems:
                  default: ''
        '400':
          description: Empty list, more than 50 addresses, or a malformed address
          content:
            application/json:
              schema:
                type: string
                additionalProperties:
                  default: ''
                default: ''
                example:
                  error: At most 50 addresses per call
        '501':
          description: No YACI datasource configured for the network
          content:
            application/json:
              schema:
                type: string
                additionalProperties:
                  default: ''
                default: ''
                example:
                  error: Not Implemented
components:
  schemas:
    BulkAddressUtxosRequest:
      type: object
      default: null
      description: Bulk address UTxO lookup request
      properties:
        addresses:
          type: array
          default: ''
          description: Cardano addresses, max 50 per call
          example:
            - >-
              addr1qxy8p07tr8k3x5nc4sr77gvkcs7g54rd0dtwjyeuc4x0dhqxq6xg4d6dxr5x5qa6a3g2p6a0f7yq5j6l9k2z0t7lqvsqk8j0z
          items:
            type: string
            pattern: ^[a-zA-Z0-9]{10,150}$
          maxItems: 50
          minItems: 0
      required:
        - addresses
    AddressUtxosDto:
      type: object
      default: null
      description: UTxOs held by one address, as returned by the bulk address lookup
      properties:
        address:
          type: string
          default: ''
          description: The address exactly as it appeared in the request
          example: >-
            addr1qxy8p07tr8k3x5nc4sr77gvkcs7g54rd0dtwjyeuc4x0dhqxq6xg4d6dxr5x5qa6a3g2p6a0f7yq5j6l9k2z0t7lqvsqk8j0z
        utxos:
          type: array
          default: ''
          description: >-
            Unspent UTxOs at the address, newest first. Empty when the address
            holds none.
          items:
            $ref: '#/components/schemas/AddressUtxoDto'
        truncated:
          type: boolean
          default: false
          description: >-
            Present and true only when the batch exceeded the server's row cap.
            The whole response is then incomplete, including entries that look
            empty: split the request into smaller batches.
          example: true
    AddressUtxoDto:
      type: object
      properties:
        txHash:
          type: string
        txIndex:
          type: integer
          format: int32
        address:
          type: string
        stakeAddress:
          type: string
        paymentCred:
          type: string
        epoch:
          type: integer
          format: int32
        blockHeight:
          type: integer
          format: int32
        blockTime:
          type: integer
          format: int32
        slot:
          type: integer
          format: int64
        value:
          type: string
        datumHash:
          type: string
        inlineDatum:
          $ref: '#/components/schemas/InlineDatumDto'
        referenceScript:
          $ref: '#/components/schemas/ReferenceScriptDto'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/AssetBalanceDto'
        spent:
          type: boolean
        blockHash:
          type: string
        cborHex:
          type: string
    InlineDatumDto:
      type: object
      properties:
        bytes:
          type: string
        value:
          $ref: '#/components/schemas/JsonNode'
    ReferenceScriptDto:
      type: object
      properties:
        hash:
          type: string
        size:
          type: integer
          format: int32
        type:
          type: string
        bytes:
          type: string
        value:
          $ref: '#/components/schemas/JsonNode'
    AssetBalanceDto:
      type: object
      properties:
        unit:
          type: string
        policyId:
          type: string
        assetName:
          type: string
        fingerprint:
          type: string
        quantity:
          type: string
        decimals:
          type: integer
          format: int32
        hasOnchainMetadata:
          type: boolean
    JsonNode: {}
  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 <token>`. 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

````