# List transactions

List blockchain transactions with filtering, sorting, and pagination.

Endpoint: GET /transactions
Version: 0.23.9
Security: Auth

## Query parameters:

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

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

  - `chain_gid` (array)
    Filter transactions by blockchain identifier (CAIP-2 format).
    Example: ["eip155:1","eip155:56"]

  - `hash` (array)
    Filter transactions by transaction hash.
    Example: ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"]

  - `block_number` (array)
    Filter transactions by block number.
    Example: [18500000]

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

  - `is_confirmed` (boolean)
    Filter transactions by confirmation status.
    Example: true

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

## Response 200 fields (application/json):

  - `items` (array, required)
    List of blockchain transactions.
    Example: [{"chain_gid":"eip155:1","hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","block_number":18500000,"is_success":true,"confirmed_at":null,"created_at":"2024-01-15T10:30:00Z"}]

  - `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.
    Example: true

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

  - `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; value is label or null.

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