# Get list of transactions

Returns a paginated list of transactions based on the provided filters.

Endpoint: GET /transactions
Version: 1.0.0
Security: ApiKeyAuth

## Query parameters:

  - `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: "transaction_hash", "-transaction_hash", "block_number", "-block_number", "initiator", "-initiator", "target", "-target", "is_success", "-is_success", "confirmed_at", "-confirmed_at", "created_at", "-created_at"

  - `initiator_address` (array)
    Filter transactions by initiator addresses (exact match)
    Example: ["0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a","0x123456789abcdef123456789abcdef123456789ab"]

  - `target_address` (array)
    Filter transactions by target addresses (exact match)
    Example: ["0xdAC17F958D2ee523a2206206994597C13D831ec7","0x9876543210abcdef9876543210abcdef98765432"]

  - `address` (array)
    Filter transactions where any of the addresses is either initiator or target address
    Example: ["0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a","0xdAC17F958D2ee523a2206206994597C13D831ec7"]

  - `chain_gids` (array)
    Filter transactions by blockchain chain GIDs
    Example: ["eip155:1","eip155:56","eip155:137"]

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

## Response 200 fields (application/json):

  - `items` (array, required)
    List of blockchain transactions with their asset transfers

  - `items.transaction_hash` (string, required)
    Hash of the transaction on the blockchain
    Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

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

The chain_gid is a case-sensitive string uniquely identifying a blockchain.
It is composed of:
- namespace — a short identifier describing an ecosystem or standard (e.g. eip155, cosmos)
- reference — an identifier for a specific blockchain within that namespace

Syntax

chain_id = namespace ":" reference
namespace = [-a-z0-9]{3,8}
reference = [-_a-zA-Z0-9]{1,32}


Examples
- eip155:1 — Ethereum mainnet
- eip155:56 — Binance Smart Chain
- cosmos:cosmoshub-4 — Cosmos Hub mainnet
- bip122:000000000019d6689c085ae165831e93 — Bitcoin mainnet
    Example: "eip155:1"

  - `items.chain_family` (string, required)
    Chain family that identifies blockchain ecosystems united by common protocol or account model.

Available families:
- evm: Ethereum Virtual Machine-based blockchains
- bitcoin: Bitcoin and Bitcoin-compatible networks
- solana: Solana blockchain ecosystem
- tron: Tron blockchain ecosystem

The chain family is used to determine which blockchain ecosystem
the address belongs to and how it should be generated or validated.
    Enum: "evm", "bitcoin", "solana", "tron"

  - `items.block_number` (integer)
    Block number containing the transaction
    Example: 1974382

  - `items.initiator` (object, required)
    Reference to a blockchain address with minimal system context

  - `items.initiator.value` (string, required)
    A blockchain address in its native format. This is a generic schema for any blockchain address,
including addresses, smart contract addresses, and token contract addresses.

The actual format depends on the blockchain network:

- EVM chains (Ethereum, BSC, Polygon, etc.): 0x followed by 40 hexadecimal characters
  - Example: 0x8521E8b15eCEF4D4269Fded3E6694225E096959E

- Bitcoin: Various formats depending on address type
  - P2PKH (Legacy): Starts with 1, Example: 1GxHzNEymq1MLhxpdWAMJLN1UusYJ2Sy45
  - P2SH (Wrapped SegWit): Starts with 3, Example: 3Do92Dmff87UuY9Yiu2iFG2Kj9bpRaeJSF
  - P2WPKH (Native SegWit): Starts with bc1, Example: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08

- Solana: Base58 encoded, 32-44 characters
  - Example: 5EYCAe5ijiHbZBU14TyKHADUrkaAfc4ZyTXKRVKp49F8

- Tron: Base58 encoded addresses starting with T
  - Example: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

- Cosmos ecosystem: Bech32 format with chain-specific prefix
  - Example: cosmos1vx8knpllrj7n963p9ttd80w47kpacrhuts497x

This schema is intentionally generic to support addresses from any blockchain.
The specific validation rules depend on the blockchain network and address type.
    Example: "0x8521E8b15eCEF4D4269Fded3E6694225E096959E"

  - `items.initiator.is_known` (boolean, required)
    Whether this address is known/managed by the system (internal) or external
    Example: true

  - `items.target` (object)
    Reference to a blockchain address with minimal system context

  - `items.transfers` (array, required)
    Collection of asset transfers within this transaction (e.g., ERC-20, ETH, BTC outputs, Solana SPL tokens). Always contains at least one transfer.

  - `items.transfers.asset_gid` (string, required)
    Asset identifier in CAIP-19 format. Identifies a asset across blockchains.
Format: /:
Examples: - Ethereum ETH: eip155:1/slip44:60 - Ethereum USDT ERC-20: eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7
    Example: "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7"

  - `items.transfers.sequence` (integer, required)
    Sequential index of the transfer within the transaction, starting from 0. Defines order of transfers and ensures uniqueness per transaction.

  - `items.transfers.kind` (string, required)
    Type of asset transfer within a blockchain transaction
    Enum: "native", "fungible"

  - `items.transfers.sender` (object)
    Reference to a blockchain address with minimal system context

  - `items.transfers.recipient` (object)
    Reference to a blockchain address with minimal system context

  - `items.transfers.amount` (string, required)
    Amount transferred in the smallest unit of the asset (without decimal adjustment)
    Example: "1000000000000000000"

  - `items.transfers.meta` (object)
    Additional blockchain-specific metadata for the transfer. The structure varies based on the blockchain's
technical requirements and available transaction data. This field contains essential metadata that helps
identify and process transfers within the context of their respective blockchain ecosystems.

  - `items.is_success` (boolean, required)
    Whether the transaction executed successfully
    Example: true

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

  - `items.confirmed_at` (string)
    Timestamp when the transaction was confirmed on the blockchain
    Example: "2024-01-15T14:30:00Z"

  - `meta` (object, required)

  - `meta.limit` (integer, required)
    Number of items per page
    Example: 20

  - `meta.page` (integer, required)
    Current page number
    Example: 1

  - `meta.total` (integer, required)
    Total number of items available
    Example: 42

  - `meta.total_pages` (integer, required)
    Total number of pages available
    Example: 3

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

  - `type` (string, required)
    A URI reference that identifies the problem type
    Example: "https://docs.vilna.io/apis/problems/invalid-request"

  - `title` (string, required)
    A short, human-readable summary of the problem type
    Example: "Invalid Request"

  - `status` (integer, required)
    The HTTP status code
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem
    Example: "Validation error"

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem
    Example: "/errors?id=XXXXXX-xxxxx"

  - `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 default fields (application/problem+json):

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem
    Example: "An unexpected error occurred while processing your request"

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem
    Example: "/errors/1234567890"

  - `status` (integer, required)
    The HTTP status code
    Example: 500

  - `title` (string, required)
    A short, human-readable summary of the problem type
    Example: "Internal Server Error"

  - `type` (string, required)
    A URI reference that identifies the problem type
    Example: "https://api.vilna.io/problems/internal-error"