BlockVectra Top Up API

openapi: 3.2.0
info:
  title: BlockVectra Top-up Topup API
  description: Query top-up availability, retrieve a deposit address, and list on-chain deposits. Use your API key in the x-api-key header for account-specific requests.
  version: 0.4.1
servers:
- url: https://api.blockvectra.com
tags:
- name: Top Up
paths:
  /v1/topup/status:
    get:
      summary: Get top-up availability
      description: 'Public top-up availability, supported networks and tokens, and the minimum deposit amount. Requires no credentials; responses include Access-Control-Allow-Origin: *.'
      responses:
        '200':
          description: Current availability.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              schema:
                type: string
              example: public, max-age=30
            Access-Control-Allow-Origin:
              schema:
                type: string
              example: '*'
          content:
            application/json:
              schema:
                type: object
                required:
                - enabled
                - networks
                - min_deposit_usd
                - build
                properties:
                  enabled:
                    type: boolean
                    description: Whether top-up is available. False means every network is unavailable.
                  networks:
                    type: array
                    description: Every token on the networks this service supports.
                    items:
                      type: object
                      required:
                      - network
                      - chain_id
                      - token
                      - enabled
                      properties:
                        network:
                          type: string
                          description: Lower-case chain slug, the same as `chain` of deposit-address.
                          example: base_mainnet
                        chain_id:
                          type: integer
                          example: 8453
                        token:
                          type: string
                          description: Token symbol of a configured USD stablecoin, e.g. USDC, USDT, USDG.
                          example: USDC
                        enabled:
                          type: boolean
                          description: Whether this network and token are available for top-up.
                  min_deposit_usd:
                    type: string
                    description: Global minimum deposit amount in USD formatted to 6 decimal places, configured by operations.
                    example: '0.010000'
                  build:
                    type:
                    - string
                    - 'null'
                    pattern: ^[0-9a-f]{12}$
                    description: Opaque identifier of the running deployment (12 lowercase hex). It changes on every deploy and rollback, including redeploys of the same release; null when unknown. It carries no host, environment or source details.
                    example: 3f8a1c9b2e4d
        '404':
          description: Top-up API is disabled or endpoint not found; error code `not_found`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error; error code `internal_error`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Deposit service temporarily unavailable; error code `unavailable` (retryable).
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Top Up
      operationId: getV1TopupStatus
      x-operation-id-source: derived
  /v1/topup/deposit-address:
    get:
      summary: Get deposit address
      description: Get the customer EVM deposit address and currently available networks and tokens. Unavailable networks are omitted. Returns 409 topup_disabled when top-up is unavailable.
      security:
      - apiKeyHeader: []
      responses:
        '200':
          description: Successful retrieval of deposit address and network configurations.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                type: object
                required:
                - address
                - min_deposit_usd
                - deposits_url
                - networks
                properties:
                  address:
                    type: string
                    description: EIP-55 checksummed EVM deposit address.
                    example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                  min_deposit_usd:
                    type: string
                    description: Global minimum deposit amount in USD formatted to 6 decimal places, configured by operations.
                    example: '0.010000'
                  deposits_url:
                    type: string
                    description: URL to query customer deposit records.
                    example: https://api.blockvectra.com/v1/topup/deposits
                  networks:
                    type: array
                    description: List of currently available EVM networks and supported whitelist tokens. Closed or paused networks are omitted.
                    items:
                      type: object
                      required:
                      - chain
                      - chain_id
                      - name
                      - typical_credit_seconds
                      - explorer_tx_url
                      - tokens
                      properties:
                        chain:
                          type: string
                          description: Lower-case chain slug identifying the network.
                          example: base_mainnet
                        chain_id:
                          type: integer
                          description: EVM chain ID.
                          example: 8453
                        name:
                          type: string
                          description: Display name of the network.
                          example: Base
                        typical_credit_seconds:
                          type: integer
                          description: Typical credit latency in seconds after transaction inclusion.
                          example: 30
                        explorer_tx_url:
                          type: string
                          description: Block explorer transaction URL template.
                          example: https://basescan.org/tx/{tx_hash}
                        tokens:
                          type: array
                          description: Whitelist stablecoins supported on this network.
                          items:
                            type: object
                            required:
                            - symbol
                            - contract
                            - decimals
                            - min_amount_raw
                            properties:
                              symbol:
                                type: string
                                description: Token symbol of a configured USD stablecoin, e.g. USDC, USDT, USDG.
                                example: USDC
                              contract:
                                type: string
                                description: EIP-55 checksummed token contract address.
                                example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                              decimals:
                                type: integer
                                description: Token decimals (6 to 18).
                                example: 6
                              min_amount_raw:
                                type: string
                                description: Minimum deposit amount in raw atomic units.
                                example: '1000000'
        '400':
          description: Both `Authorization` and `x-api-key` headers are present (even if empty); error code `invalid_request`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Missing or invalid API key. Error codes: - `missing_api_key`: The `x-api-key` header is absent and no `Authorization` header is present. - `invalid_api_key`: The `x-api-key` header is empty, or the API key is unknown, disabled or revoked. - `unauthenticated`: The request carries an `Authorization` header that is not a valid console token; customers should use `x-api-key` only.'
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Top-up API is disabled or endpoint not found; error code `not_found`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Top-up is closed globally or all networks are closed; error code `topup_disabled`. No address is allocated, and a previously allocated address stays the customer's.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error; error code `internal_error`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'Deposit service temporarily unavailable, or deposit address pool exhausted. Both are retryable. Error codes: - `deposit_unavailable`: Deposit address temporarily unavailable. - `unavailable`: Deposit service temporarily unavailable.'
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Top Up
      operationId: getV1TopupDepositAddress
      x-operation-id-source: derived
  /v1/topup/deposits:
    get:
      summary: List deposit history
      description: Query deposit transfer history for the authenticated customer.
      security:
      - apiKeyHeader: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of deposit records to return per page.
      - name: before
        in: query
        required: false
        schema:
          type: integer
          format: int64
          minimum: 1
        description: Cursor for pagination, returning records with deposit_id strictly less than this value. Must be a positive signed 64-bit integer (at most 9223372036854775807).
      - name: tx_hash
        in: query
        required: false
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
        description: Filter deposits by 0x-prefixed 64-character transaction hash (case-insensitive).
      responses:
        '200':
          description: Paginated list of deposit transfers.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_before
                properties:
                  items:
                    type: array
                    description: List of deposit transfer records.
                    items:
                      type: object
                      required:
                      - deposit_id
                      - chain
                      - chain_id
                      - token
                      - contract
                      - amount
                      - tx_hash
                      - tx_log_ordinal
                      - block_number
                      - external_ref
                      - status
                      - reason
                      - credited_units
                      - credited_cu
                      - detected_at
                      properties:
                        deposit_id:
                          type: integer
                          format: int64
                          description: Unique transfer record ID.
                          example: 42
                        chain:
                          type: string
                          description: Lower-case chain slug.
                          example: base_mainnet
                        chain_id:
                          type: integer
                          description: EVM chain ID.
                          example: 8453
                        token:
                          type: string
                          description: Token currency symbol.
                          example: USDC
                        contract:
                          type: string
                          description: EIP-55 checksummed token contract address.
                          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                        amount:
                          type: string
                          description: Deposit amount in USD truncated to 6 decimal places.
                          example: '25.000000'
                        tx_hash:
                          type: string
                          description: On-chain transaction hash.
                          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                        tx_log_ordinal:
                          type: integer
                          description: Position of the Transfer log within the transaction receipt logs.
                          example: 0
                        block_number:
                          type: integer
                          description: Block height where the transaction was mined.
                          example: 123456789
                        external_ref:
                          type: string
                          description: Immutable deposit identity in eip155 format.
                          example: eip155:8453:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890:0
                        status:
                          type: string
                          enum:
                          - processing
                          - credited
                          - not_credited
                          description: Status of the deposit.
                          example: credited
                        reason:
                          type:
                          - string
                          - 'null'
                          enum:
                          - below_minimum
                          - large_amount
                          - other
                          - null
                          description: Reason why deposit was not credited. Null unless status is not_credited.
                          example: null
                        credited_units:
                          type:
                          - integer
                          - 'null'
                          description: Credited account balance units. Null unless status is credited.
                          example: 250000
                        credited_cu:
                          type:
                          - integer
                          - 'null'
                          description: Credited compute units. Null unless status is credited.
                          example: 250000000
                        detected_at:
                          type: string
                          format: date-time
                          description: RFC 3339 UTC timestamp when the transfer was detected and recorded.
                          example: 2026-10-02 10:00:00+00:00
                  next_before:
                    type:
                    - integer
                    - 'null'
                    description: Cursor for the next page, equal to the deposit_id of the last item, or null if page is not full.
                    example: null
        '400':
          description: Invalid query parameters (`limit`, `before`, `tx_hash`), unknown parameters, or conflicting authentication headers; error code `invalid_request`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Missing or invalid API key. Error codes: - `missing_api_key`: The `x-api-key` header is absent and no `Authorization` header is present. - `invalid_api_key`: The `x-api-key` header is empty, or the API key is unknown, disabled or revoked. - `unauthenticated`: The request carries an `Authorization` header that is not a valid console token; customers should use `x-api-key` only.'
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Top-up API is disabled or endpoint not found; error code `not_found`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error; error code `internal_error`.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Deposit service temporarily unavailable; error code `unavailable` (retryable).
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Top Up
      operationId: getV1TopupDeposits
      x-operation-id-source: derived
components:
  schemas:
    RequestId:
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      example: 019a1234-5678-7abc-8def-0123456789ab
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - data
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - missing_api_key
              - invalid_api_key
              - unauthenticated
              - not_found
              - topup_disabled
              - deposit_unavailable
              - unavailable
              - internal_error
              description: Standard error code.
              example: invalid_request
            message:
              type: string
              description: Static English error message without user input echo.
              example: invalid request
            data:
              type: object
              required:
              - reason
              - docs_url
              - retryable
              - request_id
              properties:
                reason:
                  type: string
                  description: Error reason identifier, identical to code.
                  example: invalid_request
                docs_url:
                  type: string
                  format: uri
                  description: Documentation URL for the error code.
                  example: https://docs.blockvectra.com/en/errors/#invalid_request
                retryable:
                  type: boolean
                  description: Whether the client may retry this request. True only for unavailable and deposit_unavailable.
                  example: false
                request_id:
                  $ref: '#/components/schemas/RequestId'
                  description: Fresh canonical lowercase UUIDv7, identical to the x-bv-request-id response header. Quote it when reporting an incident so operators can trace the request.
                  example: 019a1234-5678-7abc-8def-0123456789ab
  headers:
    RequestId:
      description: 'Fresh request identifier, identical to error.data.request_id on error responses. `GET /v1/topup/status` responses carry `Access-Control-Expose-Headers: x-bv-request-id` for any origin, with or without an `Origin` header (allow-origin `*`). Enabled `POST /v1/topup/x402/purchase` responses with an allowed `Origin` expose `x-bv-request-id, PAYMENT-REQUIRED, PAYMENT-RESPONSE` without an `Authorization` header. Every other non-OPTIONS request carries it only when the request has an allowed `Origin` AND an `Authorization` header. This applies to all response statuses, including errors such as 401 and 404. OPTIONS responses never carry it. For requests other than GET /v1/topup/status and enabled POST /v1/topup/x402/purchase, responses without an allowed Origin or without an Authorization header do not carry it.'
      schema:
        $ref: '#/components/schemas/RequestId'
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: BlockVectra API key for direct Agent authentication.