BlockVectra Account API

openapi: 3.2.0
info:
  title: BlockVectra JSON-RPC Account API
  version: 2.2.3
  termsOfService: https://blockvectra.com/en/terms/
  description: 'BlockVectra JSON-RPC 2.0 API. Send requests to `https://api.blockvectra.com/v1/robinhood_mainnet` with your API key in the `x-api-key` header, or put the key in the path: `/v1/{chain}/{api_key}`. All methods are metered in Compute Units (CU) and rate-limited per key.'
servers:
- url: https://api.blockvectra.com/v1
  description: BlockVectra JSON-RPC and Data API
tags:
- name: Account
  description: Read-only lookup of the caller's own API key's balance and limits by x-api-key; never billed (Section 1).
paths:
  /account:
    get:
      tags:
      - Account
      operationId: getAccount
      summary: Get the API key's own balance and limits
      description: '`GET /v1/account`. Returns the balance and limits of the API key sent in `x-api-key`. This operation is itself free: it is never billed, carries no usage row, and answers 200 with the current balance even when it is zero or negative (it never returns 402).


        **When to use**: use this operation to check an account''s remaining balance and a key''s rate limits and CU cap without spending CU on a billed call.


        **Behavior**: the key is read from the `x-api-key` request header only (a path key or `Authorization: Bearer` key is never read), exactly like the Data API, unlike the JSON-RPC lane, which also reads a path key and a Bearer key. This operation has its own request-rate limit, 5 requests per second per key id per service instance, independent of CU and billing; going over it returns 429. The response never carries a numeric account id, only the key''s own `key_id`.


        **Request example**: `GET /v1/account` with the header `x-api-key: `.


        **Response example**: the `accountOk` example on the 200 response.


        **Errors**: every error this operation can return is listed below. It is never billed, so every error (and every 200) is unbilled alike.


        | HTTP | Error | Retryable |

        |---:|---|---|

        | 401 | `missing_api_key` (no header) or `invalid_api_key` (unknown, disabled or revoked) | No: check the API key |

        | 403 | `key_expired`: a valid key past its expiry | No: create a new key in the console |

        | 429 | `rate_limited` (5 requests/second per key id, per service instance), sent with `Retry-After` | Yes: retry after `Retry-After` |

        | 503 | `auth_unavailable` (key store stale) or `billing_unavailable` (billing data stale or not yet loaded), sent with `Retry-After` | Yes: retry after `Retry-After` |'
      security:
      - ApiKeyHeader: []
      responses:
        '200':
          $ref: '#/components/responses/AccountOk'
        '401':
          $ref: '#/components/responses/AccountError'
        '403':
          $ref: '#/components/responses/AccountError'
        '429':
          $ref: '#/components/responses/AccountRetryableError'
        '503':
          $ref: '#/components/responses/AccountRetryableError'
components:
  examples:
    accountOk:
      summary: Account balance and limits response
      value:
        key_id: k_9f2a
        plan: paid
        balance_units: 182345
        balance_cu: 182345000
        balance_as_of_age_ms: 1200
        key:
          cu_per_sec: 50
          burst_cu: 500
          cu_cap: null
          cu_cap_remaining: null
          expires_at: null
  schemas:
    AccountError:
      type: object
      description: Error envelope of `GET /v1/account`.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            data:
              type: object
              description: Every error this operation produces carries `reason`, `docs_url`, `retryable` and `request_id` (see Section 4).
              properties:
                reason:
                  type: string
                  description: Stable snake_case cause code; see the reasons table in Section 4 for the possible values.
                docs_url:
                  type: string
                  description: '`<docs base>/errors/#<reason>`, explaining the cause and the fix.'
                retryable:
                  type: boolean
                  description: Whether sending the identical request again later can succeed.
                request_id:
                  type: string
                  description: Same value as the `x-bv-request-id` response header.
    AccountResponseBody:
      type: object
      description: Success response of `GET /v1/account`. Never carries a numeric account id, only the key's own `key_id`.
      required:
      - key_id
      - plan
      - balance_units
      - balance_cu
      - balance_as_of_age_ms
      - key
      properties:
        key_id:
          type: string
          description: The API key's own id.
        plan:
          type: string
          enum:
          - free
          - paid
          description: '`free` when the key''s account has a free-plan call-rate allowance; `paid` otherwise.'
        balance_units:
          type: integer
          description: The settled account balance minus total unsettled account usage rounded up to whole units once; hourly settlement rounds down so the balance can rise by up to one unit after settlement. May be zero or negative; this operation is never billed and never returns 402 for it.
        balance_cu:
          type: integer
          description: '`balance_units` in CU at the current price (`balance_units * denominator / numerator`, truncated toward zero).'
        balance_as_of_age_ms:
          type: integer
          description: Milliseconds since the balance above was read from its data source.
        key:
          type: object
          required:
          - cu_per_sec
          - burst_cu
          - cu_cap
          - cu_cap_remaining
          - expires_at
          properties:
            cu_per_sec:
              type: integer
              description: The key's CU-per-second rate limit (its token-bucket refill rate).
            burst_cu:
              type: integer
              description: The key's CU burst capacity (its token-bucket size).
            cu_cap:
              type:
              - integer
              - 'null'
              description: The key's lifetime CU cap, or `null` when the key is uncapped.
            cu_cap_remaining:
              type:
              - integer
              - 'null'
              description: CU left under `cu_cap` by this service instance's own count, or `null` when the key is uncapped. May be zero or negative.
            expires_at:
              type:
              - string
              - 'null'
              format: date-time
              description: RFC 3339, or `null` when the key never expires.
  responses:
    AccountOk:
      description: 'The API key''s own balance and limits. Never billed, so it answers 200 even when the balance is zero or negative. Carries `Access-Control-Allow-Origin: *`.

        '
      headers:
        Access-Control-Allow-Origin:
          description: CORS allow-list.
          schema:
            type: string
            example: '*'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountResponseBody'
          examples:
            accountOk:
              $ref: '#/components/examples/accountOk'
    AccountRetryableError:
      description: 'Retryable after `Retry-After`: 429 `rate_limited` (over 5 requests/second for this key id, per service instance) or 503 `auth_unavailable` (key store stale) / `billing_unavailable` (billing data stale or not yet loaded, no balance number). None of these is billed; neither is a 200.

        '
      headers:
        Access-Control-Allow-Origin:
          description: CORS allow-list.
          schema:
            type: string
            example: '*'
        Retry-After:
          description: Recommended wait time in seconds before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountError'
    AccountError:
      description: 'Not retryable without changing something first: 401 `missing_api_key` (no `x-api-key` header) / `invalid_api_key` (unknown, disabled or revoked; one identical body for all three), or 403 `key_expired` (a valid key past its expiry). None of these is billed; neither is a 200.

        '
      headers:
        Access-Control-Allow-Origin:
          description: CORS allow-list.
          schema:
            type: string
            example: '*'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountError'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key. When it is not empty it takes precedence over `Authorization`. Leading and trailing whitespace is trimmed.
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <api_key>`. Only the prefixes `Bearer ` and `bearer ` are accepted. Used only when `x-api-key` is missing or empty.'
x-rpc-methods:
  tracers:
    allowed:
    - callTracer
    - flatCallTracer
    - prestateTracer
    - 4byteTracer
    - noopTracer
    omitted: default struct logger
    max_timeout_secs: 30
  cu:
    weights: Per-method CU weights are published by GET /v1/plans; unlisted methods use the '*' entry. debug_trace* and trace_* are ordinary prefix rows in that table, resolved by the same rule as every other method.
    resolution: exact > longest prefix (pattern ending in *) > the '*' row
    resolution_examples:
      eth_call: exact match
      debug_traceTransaction: matches the debug_trace* prefix rule
      web3_sha3: falls back to the '*' row
  price:
    description: Prices are defined by the plan and published by GET /v1/plans (the pricing object and the per-method CU weights). No price is hard-coded in this document.
    cu_per_unit: Defined by the pricing object of GET /v1/plans.
    settlement: The CU consumed by an account in each hourly period is converted to billing units, rounded down, with the CU price from GET /v1/plans.
    admission: A request is blocked when the account balance minus the unsettled CU converted to billing units (rounded up) is zero or less.
x-rpc-errors:
- code: -32700
  source: service
  http: 200
  message: parse error
  reason: parse_error
  billed: false
- code: -32600
  source: service
  http: 200
  message: invalid request
  reason: invalid_request
  billed: false
- code: -32600
  source: service
  http: 200
  message: 'batch too large: max <N> calls'
  reason: batch_too_large (+max)
  billed: false
- code: -32600
  source: service
  http: 200
  message: 'invalid request: ambiguous member name'
  reason: invalid_request
  billed: false
- code: -32601
  source: service
  http: 200
  message: 'method not available: <method>'
  reason: method_not_allowed
  billed: false
- code: -32600
  source: service
  http: 404
  message: unknown chain
  reason: unknown_chain
  billed: false
- code: -32602
  source: service
  http: 200
  message: 'eth_getLogs block range too large: max <N> blocks'
  reason: logs_range_too_large
  billed: false
- code: -32602
  source: service
  http: 200
  message: tracer not allowed
  reason: invalid_params
  billed: false
- code: -32602
  source: service
  http: 200
  message: trace timeout not allowed
  reason: invalid_params
  billed: false
- code: -32010
  source: service
  http: 200
  message: node is syncing; calls are temporarily unavailable
  reason: node_syncing
  billed: false
- code: -32011
  source: service
  http: 200
  message: historical state is not available beyond the most recent <N> blocks
  reason: state_window
  billed: false
- code: -32011
  source: service
  http: 200
  message: requested history is not completely indexed
  reason: range_not_indexed
  billed: false
- code: -32011
  source: service
  http: 200
  message: requested history is not ready
  reason: history_not_ready
  billed: false
- code: -32000
  source: service
  http: 200
  message: transaction not found
  reason: not_found
  billed: false
- code: -32000
  source: service
  http: 200
  message: block not found
  reason: not_found
  billed: false
- code: -32000
  source: service
  http: 200
  message: upstream response too large
  reason: response_too_large
  billed: false
- code: -32005
  source: service
  http: 200
  message: service overloaded, retry later
  reason: overloaded
  billed: false
- code: -32005
  source: service
  http: 503
  message: service overloaded, retry later
  reason: overloaded
  billed: false
- code: -32005
  source: service
  http: 429
  message: rate limit exceeded
  reason: key_rate_limit | free_plan_call_limit | concurrency_limit
  billed: false
- code: -32022
  source: service
  http: 429
  message: request cost <N> CU exceeds burst capacity <M> CU
  reason: request_exceeds_burst
  billed: false
- code: -32022
  source: service
  http: 429
  message: request has <N> calls, exceeding the free-plan limit of <M> calls per second
  reason: free_plan_batch_too_large (+max)
  billed: false
- code: -32603
  source: service
  http: 200
  message: upstream unavailable
  reason: upstream_unavailable
  billed: false
- code: -32603
  source: service
  http: 200
  message: no response from upstream
  reason: upstream_unavailable
  billed: false
- code: -32603
  source: service
  http: 200
  message: malformed upstream response
  reason: upstream_unavailable
  billed: false
- code: -32603
  source: service
  http: 200
  message: unexpected service error
  reason: internal_error
  billed: false
- code: -32020
  source: service
  http: 402
  message: insufficient balance
  reason: balance_exhausted | free_grant_exhausted
  billed: false
- code: -32024
  source: service
  http: 401
  message: 'missing API key: send it in the request path (/v1/{chain}/<api_key>) or in the x-api-key header'
  reason: missing_api_key
  billed: false
- code: -32024
  source: service
  http: 401
  message: 'invalid API key: it is unknown, disabled or revoked; check the key in the console'
  reason: invalid_api_key
  billed: false
- code: -32025
  source: service
  http: 403
  message: API key expired; create a new key in the console
  reason: key_expired
  billed: false
- code: -32025
  source: service
  http: 403
  message: API key CU cap exhausted; create a new key in the console
  reason: key_cap_exhausted (+cu_cap)
  billed: false
- code: -32021
  source: service
  http: 503
  message: authentication data temporarily unavailable
  reason: auth_unavailable
  billed: false
- code: -32021
  source: service
  http: 503
  message: billing data temporarily unavailable
  reason: billing_unavailable
  billed: false
- code: 4444
  source: node
  http: 200
  message: pruned history unavailable
  billed: false
- code: -32000
  source: node
  http: 200
  message: historical state ... is not available
  billed: false
- code: -32000
  source: node
  http: 200
  message: old data not available due to pruning...
  billed: false
- code: -32000
  source: node
  http: 200
  message: missing trie node ...
  billed: false
- code: -32002
  source: node
  http: 200
  message: <node message>
  billed: false
- code: -32003
  source: node
  http: 200
  message: <node message>
  billed: false
- code: -32601
  source: node
  http: 200
  message: <node message>
  billed: false
- code: -32603
  source: node
  http: 200
  message: <node message>
  billed: false
- code: -32600
  source: node
  http: 200
  message: <node message>
  billed: false
- code: '*'
  source: node
  http: 200
  message: <node message>
  billed: true
- code: -32601
  source: service
  http: 200
  message: method is not available on the public endpoint
  reason: method_not_public
  billed: false
- code: -32005
  source: service
  http: 429
  message: public request rate limit exceeded
  reason: public_rate_limit
  billed: false
- code: -32005
  source: service
  http: 429
  message: public chain pool is busy
  reason: public_pool_busy
  billed: false