# List invoices

List invoices with filtering and pagination.

Endpoint: GET /invoices
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

  - `status` (array)
    Filter invoices by status.
    Enum: "pending", "underpaid", "paid", "confirmed", "overpaid", "cancelled", "expired"

  - `sort_by` (string)
    Field to sort results by. Use - prefix for descending order.
    Enum: "created_at", "-created_at", "updated_at", "-updated_at", "expires_at", "-expires_at", "status", "-status"

## Response 200 fields (application/json):

  - `items` (array, required)
    Example: [{"id":"550e8400-e29b-41d4-a716-446655440000","address":"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18","asset_gid":"eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955","amount":"42500000","received_amount":"0","status":"pending","expires_at":"2024-01-15T13:00:00Z","metadata":{"order_id":"1234"},"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"}]

  - `items.id` (string, required)
    Unique identifier (UUID v4).
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `items.address` (string, required)
    Blockchain address in its native format.

Format by network:
- EVM: 0x + 40 hex chars (normalized to [EIP-55](https://eips.ethereum.org/EIPS/eip-55) checksum on import)
- Bitcoin: P2PKH (1...), P2SH (3...), P2WPKH (bc1...)
- Solana: Base58, 32-44 chars
- Tron: Base58, starts with T
    Example: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"

  - `items.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/bep20:0x55d398326f99059fF775485246999027B3197955 — USDT on BNB Smart Chain
- tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t — USDT on Tron
- eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 — USDC on Polygon
    Example: "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955"

  - `items.amount` (string, required)
    Amount in the smallest asset unit.
    Example: "42500000"

  - `items.received_amount` (string, required)
    Amount in the smallest asset unit.
    Example: "0"

  - `items.status` (string, required)
    Current status of the invoice.
    Enum: "pending", "underpaid", "paid", "confirmed", "overpaid", "cancelled", "expired"

  - `items.expires_at` (string, required)
    Deadline for payment.
    Example: "2024-01-15T13:00:00Z"

  - `items.metadata` (object, required)
    Optional key-value pairs for storing additional information about the invoice.
    Example: {"order_id":"1234"}

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

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

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

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

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

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