# List transactions

List blockchain transactions with filtering, sorting, and pagination.

Endpoint: GET /transactions
Version: 0.27.5
Security: Auth

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

  - `hash` (array)
    Filter transactions by transaction hash.

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

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

  - `is_confirmed` (boolean)
    Filter transactions by confirmation 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 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:mainnet` — Tron mainnet
    Example: eip155:1

  - `items.hash` (string, required)
    Transaction hash identifier on the blockchain.
    Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

  - `items.is_success` (boolean, required)
    Transaction execution status.

  - `items.confirmed_at` (any, required)
    Timestamp when the transaction reached required confirmations. Null if the transaction is not yet confirmed.

  - `items.created_at` (string, required)
    Timestamp when the resource was created.
    Example: 2024-01-15T10:30:00Z

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

  - `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 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/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: /errors?id=XXXXXX-xxxxx

  - `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: resource.not_found

  - `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/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: /errors?id=XXXXXX-xxxxx

  - `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: resource.not_found

## 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/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: /errors?id=XXXXXX-xxxxx

  - `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: resource.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.
    Example: https://docs.vilna.io/apis/problems/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: /errors?id=XXXXXX-xxxxx

  - `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: resource.not_found