# Get transaction

Get transaction details with events and balance changes.

Endpoint: GET /transactions/{chain_gid}/{txid}
Version: 2.0.0
Security: Auth

## Security:

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

## Path parameters:

  - `chain_gid` (string, required)
    Blockchain identifier in CAIP-2 format (namespace:reference).

  - `txid` (string, required)
    Native transaction id of the chain.

## Response 200:

  - `200` (unknown)
    Transaction details with events and balance changes.

## Response 200 fields (application/json):

  - `item` (object, required)
    Transaction with the decoded events of its chain family and the balance changes of tracked
addresses. `details.family` equals the chain family of `chain_gid`.
    Example: {"chain_gid":"eip155:1","txid":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","created_at":"2024-01-15T10:30:00Z","activity":[{"chain_gid":"eip155:1","txid":"0x1234567890abcdef12…

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

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

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

  - `item.activity` (array, required)
    Balance changes for tracked addresses.

  - `item.activity.address` (string, required)
    Blockchain address in the native format of its chain, as carried by transaction data.
The bound is wider than `AddressValue` and there is no character restriction, because a
transaction payload can name an address the project never imported.
    Example: 0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4

  - `item.activity.asset_gid` (string, required)
    Global asset identifier in [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) format.
Format: `{chain_gid}/{asset_path}`
**Examples**:
- `eip155:1/slip44:60`: ETH on Ethereum
- `eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7`: USDT on Ethereum
- `eip155:56/erc20:0x55d398326f99059fF775485246999027B3197955`: USDT on BNB Smart Chain
- `tron:728126428/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`: USDT on Tron
- `eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`: USDC on Polygon
    Example: eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7

  - `item.activity.direction` (string, required)
    Direction of the asset movement relative to the tracked address.
    Enum: "in", "out"

  - `item.activity.delta` (object, required)
    Signed balance change in base units, plus a human-readable value
when we know the token's decimals.

  - `item.activity.delta.base` (string, required)
    Signed amount in the smallest asset unit.

  - `item.activity.delta.formatted` (string)
    Human-readable signed amount.

  - `item.activity.entry_kind` (string, required)
    Movement classification. Known values include `native_transfer`, `token_transfer`,
`network_fee`, `stake`, `stake_withdrawal`, `utxo_spend`, and `utxo_create`. Additional
values may be returned; display unfamiliar values as generic movements.

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

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

  - `item.details.events` (array, required)
    Decoded events of the transaction, ordered by `event_index`.

  - `item.details.events.event_index` (integer, required)
    Zero-based index within its container, bounded to the signed 64-bit range.
Unique only within the transaction version that names it; consumers preserve the integer exactly.
    Example: 0

  - `item.details.events.kind` (string, required)
    Event kind, the discriminator of `EVMTransactionEvent`.
    Enum: "transfer", "approval", "interaction", "contract_creation"

  - `item.details.events.amount` (object, required)
    Asset amount in base units, plus a human-readable value when we know
the token's decimals.
    Example: {"base":"1000000000","formatted":"1.0"}

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

  - `item.details.events.amount.formatted` (string)
    Human-readable amount.

  - `item.details.events.operation` (string, required)
    Kind of movement the transfer records.
    Enum: "transfer", "mint", "burn"

  - `item.details.events.outcome` (string, required)
    Result in the recorded execution, including ancestor rollback; independent of chain reorganization.
    Enum: "succeeded", "reverted"

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

  - `item.details.block` (object, required)
    Block that carries the transaction.
    Example: {"block_hash":"0x9f1c2a3b4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8","block_height":18500000}

  - `item.details.block.block_hash` (string, required)
    Native block hash in the format of the selected family; not a transaction identifier.
    Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

  - `item.details.gas_used` (integer, required)
    Actual transaction receipt gasUsed; not a fee, gas limit or cumulative block gas.

  - `item.details.fee` (object)
    Actual total TRX commission in SUN and its identified fee payer. Resolve the native asset
from the chain catalog; resources are separate.
    Example: {"payer_address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","amount":{"base":"1100000","formatted":"1.1"}}

  - `item.details.resources` (object)
    Transaction resource usage. All counters, including zero, are present. Caller and creator
Energy quota usage together must not exceed `energy_used`. These counters do not represent
monetary debits or remaining resource balances.
    Example: {"energy_used":130285,"caller_energy_quota_used":0,"creator_energy_quota_used":130285,"bandwidth_quota_used":345}

  - `item.details.resources.energy_used` (integer, required)
    Total receipt energy_usage_total, including applicable penalty.

  - `item.details.resources.caller_energy_quota_used` (integer, required)
    Caller Energy quota consumed (receipt energy_usage), excluding Energy paid with TRX.

  - `item.details.resources.creator_energy_quota_used` (integer, required)
    Contract creator Energy quota contribution (receipt origin_energy_usage).

  - `item.details.resources.bandwidth_quota_used` (integer, required)
    Charged Bandwidth quota (receipt net_usage), not total transaction bytes or proof of its owner.

  - `item.details.events` (array, required)
    The decoded event of the transaction, when the version carries one.

  - `item.details.events.kind` (string, required)
    Event kind, the discriminator of `BitcoinTransactionEvent`.
    Enum: "utxo_transfer"

  - `item.details.events.is_coinbase` (boolean, required)
    Whether the transaction mints the block subsidy.

  - `item.details.events.inputs` (array, required)
    Outputs this transaction spends, ordered by input index.

  - `item.details.events.inputs.input_index` (integer, required)
    Position of an input or an output inside its transaction.
    Example: 0

  - `item.details.events.outputs` (array, required)
    Outputs this transaction creates, ordered by output index.

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

## 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 404:

  - `404` (unknown)
    Requested resource does not exist.

## Response 404 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 429:

  - `429` (unknown)
    Capacity or action cooldown exceeded.

## Response 429 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 502:

  - `502` (unknown)
    Invalid upstream response or integration failure.

## Response 502 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 504:

  - `504` (unknown)
    Shared request deadline exhausted.

## Response 504 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 404 examples:

  - `The address does not exist in this project` (unknown)

  - `The invoice does not exist in this project` (unknown)

## Response 503 examples:

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