Connect an AI agent to BlockVectra: llms.txt, OpenAPI and public JSON

Autonomous AI agents and Large Language Model (LLM) tools need predictable discovery and machine-readable specifications. BlockVectra ships machine context files, standard OpenAPI 3.1 specifications, and keyless public JSON endpoints, so an agent can inspect supported chains, check operational status, and issue RPC calls on its own.

1. Machine-readable context and specificationsCopy Anchor Link

BlockVectra publishes files aimed at LLM agents and developer tools:

llms.txt indexesCopy Anchor Link

Following the llmstxt.org convention, these files give agents a structured summary of the site and its endpoints:

• Main site index: WWW_URL/llms.txt — overview of the main site, supported chains, pricing, and public APIs.
• Documentation index: DOCS_URL/llms.txt — catalog of every documentation page with its title and description.

Full documentation file (llms-full.txt)Copy Anchor Link

• Complete documentation: DOCS_URL/llms-full.txt — the full text of every English documentation page in one plain-text Markdown file, with interactive components removed. It can be loaded into an agent's system prompt or ingested into a Retrieval-Augmented Generation (RAG) pipeline.

Downloadable OpenAPI 3.1 specificationsCopy Anchor Link

The documentation site serves two OpenAPI 3.1 YAML files that can be imported directly into agent frameworks, tool generators, or API clients:

• JSON-RPC API specification: /openapi/json-rpc.yaml — supported methods, per-chain method policy, error responses, and Compute Unit metering.
• Data API specification: /openapi/data.yaml — REST endpoint definitions for indexed blocks, transactions, transfers, balances, holders, and related datasets.

2. Public JSON endpoints (no key required)Copy Anchor Link

An agent can inspect available chains, live status, and plan parameters before sending any metered request. None of these endpoints needs an API key:

• GET /v1/status and GET /v1/chains are unauthenticated, unbilled, and not rate-limited.
• GET /v1/plans is public and unauthenticated.

All three send Access-Control-Allow-Origin: *.

Service status (GET /v1/status)Copy Anchor Link

Returns the service's readiness and the synchronization status of each public chain:

curl -s "$BLOCKVECTRA_API_BASE/v1/status"

Response fields:

• checked_at: when the snapshot was generated (RFC 3339 / ISO 8601 UTC).
• gateway.status: service running status. ok means the service is ready; degraded means balance-admission or API key data is not ready or has expired, so paid requests are rejected until it recovers. This value is independent of any chain's node status.
• chains[]: the chains served to the public:
  • chain: chain slug (e.g. robinhood_mainnet).
  • name: human-readable display name.
  • chain_id: EIP-155 chain ID (decimal integer).
  • jsonrpc: whether JSON-RPC is served.
  • data: whether the Data API is served.
  • data_features: Data API capabilities available for this chain (an empty array when data is false).
  • data_status: Data API running status (ok or unavailable; present only when data is true).
  • status: chain node status (ok or unavailable).
  • head: latest block information — block (latest block height), time (block timestamp), and lag_seconds (how far the block time lags the current time) — or null when unknown.

Example response from the specification:

{
  "checked_at": "2026-09-28T12:00:00Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "status": "ok",
      "head": {
        "block": 73017329,
        "time": "2026-09-28T11:59:58Z",
        "lag_seconds": 2
      }
    }
  ]
}

Chain parameters (GET /v1/chains)Copy Anchor Link

Returns each public chain's static parameters and method policy:

curl -s "$BLOCKVECTRA_API_BASE/v1/chains"

Response fields:

• chains[]: public chains and their static parameters:
  • chain: chain slug.
  • name: human-readable display name.
  • chain_id: EIP-155 chain ID.
  • jsonrpc: whether JSON-RPC is served.
  • data: whether the Data API is served.
  • methods: method policy:
    • allow: allowed methods or prefix wildcard patterns (e.g. eth_*, debug_trace*).
    • deny: denied methods or prefix wildcard patterns (e.g. eth_newFilter). Denied methods take precedence over allowed ones.
  • max_logs_block_range: maximum block span allowed in a single eth_getLogs request.
  • state_window_blocks: historical state window in blocks; null when the full history is available.
  • info: per-chain public extension data (reserved; currently an empty object {}).

Example response from the specification:

{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "methods": {
        "allow": [
          "eth_*",
          "net_*",
          "web3_*",
          "debug_trace*"
        ],
        "deny": [
          "eth_newFilter",
          "eth_newBlockFilter",
          "eth_newPendingTransactionFilter",
          "eth_getFilterLogs",
          "eth_getFilterChanges",
          "eth_uninstallFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 900,
      "info": {}
    }
  ]
}

Plans and method weights (GET /v1/plans)Copy Anchor Link

Plan parameters are served by the console backend at GET https://dev-console-api.blockvectra.network/v1/plans. An agent can query this endpoint at runtime to read the active free-plan limits and the Compute Unit (CU) weight of each method:

• free: Free Plan parameters — signup_units (sign-up grant, in units), monthly_units (cycle refill watermark, in units), window_days (usage cycle length in days), and max_calls_per_sec (free-plan per-second call cap).
• pricing: paid-plan parameters — units_per_usd (units per 1 USD), cu_per_unit (CU per unit), and min_topup_usd (minimum top-up in USD).
• method_weights: per-call CU weights, each { "method": string, "cu_weight": number }. method is an exact JSON-RPC method name, a prefix rule ending in * (e.g. debug_trace*), the * row used for unlisted methods, or a Data API operation such as data.<op>. Weights are per method and are not split by chain.

3. Authentication and key securityCopy Anchor Link

Agents that issue RPC calls must follow these rules:

• Authentication: pass the API key in the x-api-key request header as x-api-key: <your_api_key>, or put it in the path: POST /v1/{chain}/{api_key}. The same key works on every supported chain, and on the Data API where it is available.
• Key security: keep API keys in server-side environment variables (for example BLOCKVECTRA_API_KEY) or a secrets manager. Never embed a key in browser code or any client-side bundle. Endpoints do return Access-Control-Allow-Origin: *, but they are meant to be called by backend services rather than from the browser.
• Metering and upgrades: usage is metered in Compute Units (CU): each method consumes CU according to its weight, and balance, CU buckets, and free-plan rate limits are shared across all chains. After a paid top-up, the free plan's per-second call cap no longer applies; each key still has a CU rate limit and burst capacity. Unused Free Credits stay in your Credits and can still be used. See the Pricing page for details.

4. Chain selection workflow for agentsCopy Anchor Link

Before dispatching calls, an agent can follow these steps:

1. Check the chain and its method policy: call GET /v1/chains, confirm that the target chain exists and has jsonrpc: true, and that the method you plan to call is allowed by methods.allow and not denied by methods.deny (deny wins).
2. Check live status: call GET /v1/status and confirm that gateway.status is ok and that the target chain's status is ok; use head.lag_seconds to decide whether the chain's data is fresh enough for your use case. When a chain's node is not synced, every method except eth_chainId returns JSON-RPC error -32010 (HTTP 200, not billed), so the agent can wait and retry or pick another chain.
3. Send the request: POST /v1/{chain} with the x-api-key header and a standard JSON-RPC body.

5. Minimal working exampleCopy Anchor Link

The example below reads /v1/chains to pick a chain that allows eth_blockNumber, checks /v1/status, and then calls eth_blockNumber once.

# API host, without a trailing /v1
export BLOCKVECTRA_API_BASE="<your_api_base_url>"
export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. List public chains and their method policy
curl -s "$BLOCKVECTRA_API_BASE/v1/chains"

# 2. Check the service and per-chain status
curl -s "$BLOCKVECTRA_API_BASE/v1/status"

# 3. Call eth_blockNumber on the chain you selected
curl -s "$BLOCKVECTRA_API_BASE/v1/robinhood_mainnet" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

A successful call returns a standard JSON-RPC response object (example from the specification):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45a27f1"
}