# List address UTXOs

List unspent Bitcoin outputs held by the address.

Endpoint: GET /addresses/{address}/utxos
Version: 0.23.9
Security: Auth

## Path parameters:

  - `address` (string, required)
    Blockchain address in its native format (e.g., 0x8521E8b15eCEF4D4269Fded3E6694225E096959E for EVM chains).

## Query parameters:

  - `chain_gid` (array)
    Filter UTXOs by blockchain identifiers (CAIP-2 format). If not specified, returns all bip122 chains.
    Example: ["bip122:000000000019d6689c085ae165831e93"]

  - `limit` (integer)
    Maximum number of items to return.
    Example: 20

  - `page` (integer)
    Page number for pagination.
    Example: 1

  - `sort_by` (string)
    Field to sort results by. Use - prefix for descending order.
    Enum: "hash", "-hash", "amount", "-amount", "block_number", "-block_number"

## Response 200 fields (application/json):

  - `items` (array, required)
    List of unspent outputs.

  - `items.chain_gid` (string, required)
    Blockchain identifier in [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) format.

Format: {namespace}:{reference}
- namespace: Ecosystem identifier (3-8 chars, lowercase)
- reference: Blockchain identifier within namespace (1-32 chars)

Examples:
- eip155:1 — Ethereum mainnet
- eip155:56 — BNB Smart Chain mainnet
- eip155:137 — Polygon mainnet
- bip122:000000000019d6689c085ae165831e93 — Bitcoin mainnet
- tron:mainnet — Tron mainnet

  - `items.address` (string, required)
    Blockchain address in its native format.

Format by network:
- EVM: 0x + 40 hex chars (normalized to [EIP-55](https://eips.ethereum.org/EIPS/eip-55) checksum on import)
- Bitcoin: P2PKH (1...), P2SH (3...), P2WPKH (bc1...)
- Solana: Base58, 32-44 chars
- Tron: Base58, starts with T

  - `items.hash` (string, required)
    Transaction hash identifier on the blockchain.

  - `items.vout_index` (integer, required)
    Output index within the transaction.

  - `items.amount` (object, required)
    Asset amount in base units, plus a human-readable value when we know
the token's decimals.

  - `items.amount.base` (string, required)
    Amount in the smallest asset unit.

  - `items.amount.formatted` (string)
    Human-readable amount.

  - `items.script_pubkey_hex` (string, required)
    Hex-encoded locking script of the address.
    Example: "0014751e76e8199196d454941c45d1b3a323f1433bd6"

  - `items.block_number` (integer, required)
    Block number/height on the blockchain.

  - `references` (object, required)
    Related objects included in the response, keyed by ID.

  - `references.blockchains` (object, required)
    Map of blockchains indexed by their CAIP-2 Chain GID.

  - `meta` (object, required)
    Pagination metadata returned on every list response. page and limit echo the values used to build this page (defaults are applied when the request omits them). total and total_pages reflect the full result set after any filters are applied.

  - `meta.limit` (integer, required)
    Page size used to build this response.

  - `meta.page` (integer, required)
    Index of the page returned, starting at 1.

  - `meta.total` (integer, required)
    Total number of items matching the request across all pages.

  - `meta.total_pages` (integer, required)
    Total number of pages available at the current limit.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/invalid-request"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Invalid Request"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "Validation error"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "blockchain.name_too_long"

  - `fields` (array)
    List of invalid fields in the request

  - `fields.name` (string, required)
    The name of the invalid field
    Example: "meta"

  - `fields.reason` (string, required)
    Why this field is invalid
    Example: "Exceeded maximum data size — must not exceed 1000 characters"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/unauthorized"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Unauthorized"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 401

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "Missing or invalid authentication credentials"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "auth.unauthorized"

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/forbidden"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Forbidden"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 403

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "You do not have permission to perform this action"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "chain.not_allowed"

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/not-found"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Not Found"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 404

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "The requested resource was not found"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "blockchain.not_found"

## Response default fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.