openapi: 3.1.0
info:
  title: BlockVectra Top-up 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.1.0
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:
            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
                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.
                    example: "1.000000"
        "404":
          description: Top-up API is disabled or endpoint not found; error code `not_found`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error; error code `internal_error`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Deposit service unavailable; error code `unavailable` (retryable).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /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.
          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.
                    example: "1.000000"
                  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: Invalid request parameters or conflicting authentication headers;
            error code `invalid_request`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Missing or invalid API key. Error codes: - `missing_api_key`: No credential provided in `x-api-key`. - `invalid_api_key`: 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."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Top-up API is disabled or endpoint not found; error code `not_found`.
          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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error; error code `internal_error`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: "Deposit service or deposit address temporarily unavailable. Both are retryable. Error codes: - `deposit_unavailable`: Deposit address temporarily unavailable. - `unavailable`: Deposit service unavailable."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /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
            minimum: 1
            maximum: 9223372036854776000
          description: Cursor for pagination, returning records with deposit_id strictly
            less than this value.
        - 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.
          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
                          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. Only present when status is
                            not_credited.
                          example: null
                        credited_units:
                          type:
                            - integer
                            - "null"
                          description: Credited balance units. Only present when status is credited.
                          example: 250000
                        credited_cu:
                          type:
                            - integer
                            - "null"
                          description: Credited compute units. Only present when 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-02T10:00:00Z
                  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`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Missing or invalid API key. Error codes: - `missing_api_key`: No credential provided in `x-api-key`. - `invalid_api_key`: 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."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Top-up API is disabled or endpoint not found; error code `not_found`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error; error code `internal_error`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Deposit service unavailable; error code `unavailable` (retryable).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    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:
                  type: string
                  description: Request identifier, identical to the x-request-id response header.
                    Quote it when reporting an incident so operators can trace
                    the request.
                  example: 7f3c1a52b9e04a1d9c2f6e5b8d4a0c37
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: BlockVectra API key for direct Agent authentication.
servers:
  - url: https://api.blockvectra.com