# List transactions

List blockchain transactions with filtering, sorting, and pagination.

Endpoint: GET /transactions
Version: 2.0.0
Security: Auth

## Security:

  - `Auth` (unknown)
    apiKey in header X-Api-Key scopes: api:transaction:read

## Query parameters:

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

  - `page` (integer)
    Page number for pagination.

  - `chain_gid` (array)
    Filter transactions by blockchain identifier (CAIP-2 format).

  - `txid` (array)
    Filter transactions by transaction id.

  - `block_number` (array)
    Filter transactions by block number.

  - `is_success` (boolean)
    Filter transactions by execution status.

  - `address` (array)
    Filter transactions by the addresses they touch. Repeat the parameter to
pass multiple values; transactions touching any of them are returned (OR
semantics). Combined with `tag_id` as a union.

  - `tag_id` (array)
    Filter transactions by address tag identifier (UUID). Repeat the parameter
to pass multiple values; transactions touching an address with any of these
tags are returned (OR semantics). Combined with `address` as a union.

  - `sort_by` (string)
    Field to sort results by. Use `-` prefix for descending order.

## Response 200:

  - `200` (unknown)
    Paginated list of transactions.

## Response 200 fields (application/json):

  - `items` (array, required)
    List of blockchain transactions.

  - `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:728126428`: Tron mainnet
    Example: eip155:1

  - `items.txid` (string, required)
    Native transaction id of the chain (hash for EVM and Tron, txid for Bitcoin).
    Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

  - `items.created_at` (string, required)
    Point in time in RFC 3339 format.
    Example: 2024-01-15T10:30:00Z

  - `items.details` (any, required)
    Transaction summary details for the chain family identified by `family`. This value matches
the chain family of the transaction's `chain_gid`.

  - `items.details.family` (string, required)
    Chain family of the transaction, the discriminator of `TransactionSummaryDetails`.
    Enum: "evm", "tron", "bitcoin"

  - `items.details.block_height` (integer, required)
    Height of the block that carries the transaction.

  - `items.details.is_success` (boolean, required)
    Whether the transaction executed without reverting.

  - `references` (object, required)
    Related objects included in the response, keyed by ID.
    Example: {"tokens":{"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7":{"gid":"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7","symbol":"USDT","name":"Tether USD","decimals":6}},"blockchain…

  - `references.tokens` (object)
    Map of tokens indexed by their CAIP-19 Asset GID.

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

  - `references.addresses` (object)
    Map of tracked addresses to labels. Presence in this map means the address is tracked.

  - `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.
    Example: {"limit":20,"page":1,"total":42,"total_pages":3}

  - `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:

  - `400` (unknown)
    Bad request (e.g., missing or invalid fields). Invalid text may be reported as address.label_invalid, address.meta_invalid, public_key.label_invalid, invoice.comment_invalid, invoice.metadata_invalid.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad 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: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code 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

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

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

  - `fields.reason` (string, required)
    Why this field is invalid.
    Example: 32

## Response 401:

  - `401` (unknown)
    Missing or invalid authentication credentials.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad 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: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code 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 403:

  - `403` (unknown)
    Insufficient permissions.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad 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: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code 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 503:

  - `503` (unknown)
    The operation is temporarily unavailable. Please try again later.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad 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: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code 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:

  - `default` (unknown)
    Unexpected error.

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

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad 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: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code 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 400 examples:

  - `The request body contains malformed JSON` (unknown)

## Response 401 examples:

  - `The API service refused authentication` (unknown)

## Response 403 examples:

  - `The API key lacks the required permission` (unknown)

## Response 503 examples:

  - `The operation cannot be completed at present` (unknown)