Khởi động nhanh

Nhà phát triển và AI agent có thể dùng thử RPC công khai mà không cần API key, sau đó tạo API key để tiếp tục.

1. Đọc chiều cao khối không cần API key

Gọi điểm cuối JSON-RPC công khai cho chuỗi ví dụ robinhood_mainnet mà không cần tạo tài khoản hoặc cung cấp API key:

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

id: 1 của phản hồi khớp với yêu cầu này; result là chiều cao khối dạng thập lục phân và có thể thay đổi giữa các lệnh gọi. Nếu phản hồi chứa error, hãy kiểm tra mã lỗi và lý do. Xem điểm cuối RPC công khai miễn phí để biết các phương thức công khai, phạm vi lịch sử và giới hạn theo từng IP.

2. Tạo API key

Truy cập console, đăng nhập bằng GitHub, Google hoặc ví Ethereum (tài khoản của bạn được tạo ở lần đăng nhập đầu tiên), và tạo một API key. Mã bí mật (secret) chỉ hiển thị một lần: hãy lưu trữ cẩn thận và đặt làm biến môi trường BLOCKVECTRA_API_KEY. Tránh để lộ trong mã nguồn trình duyệt phía client. Tài khoản mới nhận 30,000,000 CU khi đăng ký — không cần thẻ tín dụng.

3. Gửi lệnh gọi xác thực đầu tiên

Đọc chiều cao khối của cùng một chuỗi với header x-api-key. URL kết thúc bằng tên chuỗi, không có dấu gạch chéo ở cuối:

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

result tiếp tục là chiều cao khối dạng thập lục phân. Yêu cầu này tiêu thụ CU; xem tài liệu tham khảo JSON-RPC để biết trọng số phương thức và mã lỗi, và Bảng giá để biết mức giá hiện tại. Một key mới tạo có hiệu lực sau khoảng 5 giây; nếu nhận được invalid_api_key, hãy chờ một lát và thử lại. Xem Các lỗi thường gặp bên dưới đối với các lỗi khác.

4. Tiếp tục với tác vụ kinh doanh

• Truy vấn hoạt động cổ phiếu token hóa on-chain trên Robinhood Chain
• Backfill log HyperEVM theo từng phân đoạn
• Nhận hoạt động ví và chuyển token bằng webhook

Tham khảo

API key và số dư

Template khởi đầu hoàn chỉnh: blockvectra/agent-quickstart

Mỗi key có dạng tiền tố rgw_ theo sau bởi 64 ký tự hex, ví dụ rgw_1f2e... (rút gọn). Giữ bí mật key — bất kỳ ai có key đều có thể tiêu hao số dư của bạn.

# Endpoint công khai trực tiếp:
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# Hoặc dùng mẫu fallback API key (mặc định về công khai khi chưa đặt BLOCKVECTRA_API_KEY):
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/${BLOCKVECTRA_API_KEY:-public}" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Hai điểm cuối siêu dữ liệu (metadata) công khai sau đây hiển thị trạng thái dịch vụ và cấu hình của từng chuỗi; chúng không yêu cầu API key và không bị tính phí.

Kiểm tra trạng thái hoạt động của dịch vụ và chuỗi

curl https://api.blockvectra.com/v1/status

Trả về mốc thời gian kiểm tra checked_at, trạng thái hoạt động của dịch vụ gateway.status, tiến trình đồng bộ node của từng chuỗi được hỗ trợ sync, chiều cao khối đỉnh và độ trễ head:

{
  "checked_at": "2026-10-03T13:30:47Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "data_status": "ok",
      "data_head_block": 125492675,
      "data_head_age_seconds": 3,
      "status": "ok",
      "sync": {
        "stage": "synced",
        "node_block": 125492676,
        "target_block": null
      },
      "head": {
        "block": 125492676,
        "time": "2026-10-03T13:30:45Z",
        "lag_seconds": 2
      }
    }
  ]
}

Truy vấn chuỗi được hỗ trợ và chính sách phương thức

curl https://api.blockvectra.com/v1/chains

Trả về chain_id của từng chuỗi được hỗ trợ, cờ tính năng cho JSON-RPC, Data API và WebSocket, chính sách cho phép và từ chối phương thức (methods.allow và methods.deny), giới hạn phạm vi khối log của một truy vấn max_logs_block_range, và cửa sổ trạng thái lịch sử state_window_blocks:

{
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "ws": false,
      "subscriptions": [],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "eth_getLogs"
        ],
        "deny": [
          "eth_newFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 990000,
      "info": {}
    }
  ]
}

Chọn một chuỗi

Mỗi điểm cuối của BlockVectra đều được giới hạn theo chuỗi: các yêu cầu JSON-RPC mang tên chuỗi {chain} trong đường dẫn URL, và các yêu cầu Data API dùng nó làm tiền tố cho tuyến đường. Xem Chuỗi được hỗ trợ để biết các chuỗi hiện có và mã định danh của chúng.

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/arb_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/arb_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/arb_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/base_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/base_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/base_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/bsc_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/bsc_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/bsc_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/eth_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/eth_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/eth_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/eth_sepolia' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/eth_sepolia' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/eth_sepolia/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/hyperevm_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/hyperevm_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/hyperevm_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/polygon_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/polygon_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/polygon_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/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":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/robinhood_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/robinhood_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/robinhood_testnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/robinhood_testnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/robinhood_testnet'

Tất cả các ví dụ trên trang này đều sử dụng robinhood_mainnet.

Mẹo: chọn một chuỗi hỗ trợ dịch vụ, phương thức và cửa sổ lịch sử của ví dụ trong ma trận ở trên, sau đó thay thế robinhood_mainnet bằng {chain} của chuỗi đó. Cùng một API key hoạt động trên tất cả các chuỗi được hỗ trợ.

Các tùy chọn xác thực khác và ví dụ ngôn ngữ

Các điểm cuối JSON-RPC được xác định theo từng chuỗi: POST /v1/{chain}/{api_key} với key trong đường dẫn, hoặc POST /v1/{chain} với key trong header x-api-key. {chain} là tên chuỗi mà Data API cũng sử dụng; đối với Robinhood Chain, đó là robinhood_mainnet, vì vậy điểm cuối trên trang này là https://api.blockvectra.com/v1/robinhood_mainnet. Gọi eth_subscribe qua HTTP trả về -32601; đăng ký WebSocket được liệt kê theo từng chuỗi trong Chuỗi được hỗ trợ. API gửi Access-Control-Allow-Origin: *, nhưng bạn nên giữ bí mật API key và thực hiện yêu cầu từ dịch vụ backend thay vì mã nguồn trình duyệt phía client.

Bạn có thể truyền key theo một trong ba cách: trong đường dẫn URL (POST /v1/{chain}/{api_key}, cách này chỉ dùng key trong đường dẫn và bỏ qua cả hai header), trong header x-api-key, hoặc trong header Authorization: Bearer <api_key>.

Key nằm trong đường dẫn URL

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/$BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Key nằm trong header yêu cầu

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Header Authorization: Bearer <api_key> cũng hoạt động. Trên POST /v1/{chain}, header x-api-key không rỗng được ưu tiên hơn Bearer, và Bearer chỉ được dùng khi x-api-key vắng mặt hoặc rỗng. Định dạng đường dẫn bỏ qua cả hai header.

Lệnh gọi theo lô (Batch calls)

Gửi một mảng để thực hiện nhiều lệnh gọi trong một yêu cầu duy nhất (tối đa 100 lệnh gọi mỗi lô). Lưu ý rằng mỗi API key có một bucket CU (tốc độ nạp cu_per_sec, dung lượng burst_cu — mặc định là 400 CU/s và burst 1,600 CU; hiển thị theo từng key trong bảng Keys trên console); một yêu cầu đơn lẻ — bao gồm toàn bộ lô JSON-RPC — có tổng số CU vượt quá dung lượng burst của key sẽ bị từ chối với mã lỗi -32022 request_exceeds_burst, ngay cả khi nằm dưới giới hạn 100 lệnh gọi mỗi lô; hãy chia nhỏ thành các lô nhỏ hơn. Ví dụ này đọc chain ID và số dư tài khoản trong một lượt truyền đi - về:

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '[
    {"jsonrpc":"2.0","id":1,"method":"eth_chainId"},
    {"jsonrpc":"2.0","id":2,"method":"eth_getBalance","params":["0x1111111111111111111111111111111111111111","latest"]}
  ]'

Phản hồi trả về dưới dạng một mảng, theo đúng thứ tự của các yêu cầu, được khớp theo id.

Nếu thay vào đó máy chủ từ chối toàn bộ lô — do số dư không đủ, giới hạn tốc độ, dung lượng burst hoặc lô quá lớn (xem Các lỗi thường gặp bên dưới) — máy chủ sẽ trả về một đối tượng lỗi JSON-RPC duy nhất thay vì một mảng; chế độ batch: true của viem sau đó sẽ hiển thị lỗi này dưới dạng UnknownRpcError không rõ chi tiết, vì vậy hãy thử lại bằng một lệnh gọi đơn lẻ để xem lỗi thực tế.

Hiểu về thanh toán CU

Mọi lệnh gọi bị tính phí đều tiêu thụ Compute Units (CU): các lệnh gọi nhẹ như eth_blockNumber hoặc eth_chainId có chi phí thấp nhất, các lần đọc thông thường như eth_getBlockByNumber tốn nhiều hơn một chút, các lệnh gọi nặng hơn như eth_call hoặc eth_getLogs tốn nhiều hơn, và các phương thức truy vết thực thi (như debug_traceTransaction) tốn nhiều nhất. Mức sử dụng được tính phí theo từng tài khoản cho mỗi khoảng thời gian một giờ, làm tròn xuống đến các đơn vị thanh toán nguyên (1 đơn vị = 1,000 CU), phần dư còn lại được chuyển tiếp sang kỳ tiếp theo (do đó qua các kỳ, tổng số đơn vị bị tính phí là floor(tổng CU / 1,000)); việc quyết toán diễn ra khoảng 15 phút sau khi kết thúc kỳ. Ví dụ: 508 CU chuyển tiếp + 2557 CU tiêu thụ = 3065 CU, dẫn đến 3 đơn vị thanh toán bị tính phí và 65 CU được chuyển tiếp sang kỳ tiếp theo. Xem Bảng giá để biết mức giá hiện tại.

Bảng trọng số đầy đủ theo từng phương thức và mã lỗi có trong Tài liệu tham khảo API → JSON-RPC — trang này chỉ trình bày định dạng của một yêu cầu.

Các lỗi thường gặp

Các trường hợp bị từ chối ở trên không bao giờ bị tính phí. Mọi lệnh gọi được chấp nhận và nhận được phản hồi đều bị tính phí theo trọng số CU đã công bố của phương thức; bảng mã lỗi liệt kê các trường hợp không bị tính phí (xem cột Được tính phí trong Mã lỗi).

Gọi Data API

Data API cung cấp dữ liệu chuỗi chỉ đọc (khối, giao dịch, số dư, người nắm giữ, hoạt động DEX, v.v.) dưới dạng REST/JSON. Mọi tuyến đường ngoại trừ GET https://api.blockvectra.com/v1/data/chains đều có tiền tố là mã định danh chuỗi: robinhood_mainnet là mã định danh chuỗi (trường chain được trả về bởi /chains và trong meta) được sử dụng trong mọi đường dẫn bên dưới. GET https://api.blockvectra.com/v1/data/chains chỉ liệt kê các chuỗi công khai và chỉ trả về {"data": [...]} (không có meta, không có next_cursor). Các yêu cầu được đo lường và tính phí bằng Compute Units (CU); chỉ các phản hồi thành công 2xx mới bị tính phí.

Mỗi yêu cầu đều yêu cầu cùng một API key như JSON-RPC — truyền key trong header x-api-key. Mọi phản hồi thành công theo phạm vi chuỗi đều sử dụng cùng một cấu trúc phản hồi: data (dữ liệu tải trọng), next_cursor (chuỗi opaque, chỉ xuất hiện khi còn trang tiếp theo — nếu không key này sẽ hoàn toàn vắng mặt, không bao giờ là null), và meta (chain, chain_slug (dạng chữ hoa của chain), chain_external_id, as_of_block, safe_block, finalized_block, coverage, refreshed_at; refreshed_at có thể là null, có nghĩa là thời gian cập nhật dữ liệu chưa xác định và nên coi là cũ — các điểm cuối dựa trên khối luôn trả về giá trị). Các phản hồi lỗi thường chứa {"error":{"code","message"}} — 409 not_indexed_yet bổ sung indexed_through (khối được lập chỉ mục cao nhất). Chuỗi không xác định hoặc không công khai trả về HTTP 404 với error.code not_found (không tính phí; tên chuỗi phải là slug chữ thường chính xác); API key bị thiếu, không xác định hoặc bị vô hiệu hóa trả về HTTP 401 với error.code missing_api_key hoặc invalid_api_key. Các yêu cầu bị giới hạn tốc độ trả về HTTP 429 (error.code rate_limited, data.reason: "key_rate_limit"), và số dư cạn kiệt trả về HTTP 402 (error.code insufficient_balance); cả hai đều không bị tính phí. Các giá trị có thể vượt quá 2^53 (số dư, số lượng token) là các chuỗi thập phân, không bao giờ là số JSON.

Tra cứu khối theo số:

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": {
    "number": 72838701,
    "hash": "0x9f2c1e7a4b6d3f805e1c9a72b4d6f1e0a3c8b5d7e2f4a1c6b9d3e7f0a2c4b6d8",
    "parent_hash": "0x1a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a",
    "timestamp": "2026-09-26T05:41:07Z",
    "miner": "0x00000000000000000000000000000000000a4b05",
    "gas_limit": 32000000,
    "gas_used": 4821932,
    "base_fee_per_gas": "100000000",
    "state_root": "0x2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d",
    "transactions_root": "0x3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e",
    "receipts_root": "0x4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f",
    "tx_count": 239,
    "size": 48213,
    "l1_block_number": null,
    "extra": {}
  },
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:03Z"
  }
}

Số khối cao hơn đỉnh đã lập chỉ mục (as_of_block) sẽ trả về 409 (error.code: "not_indexed_yet") cùng với indexed_through cho biết khối được lập chỉ mục cao nhất — dữ liệu chưa có ở đó, vì vậy hãy thử lại sau. Số khối hoàn toàn trước phạm vi lịch sử được bao phủ của chuỗi (coverage.from_block) trả về 422 (error.code: "no_coverage"). Trong phạm vi bao phủ, số khối tại hoặc dưới as_of_block không có bản ghi trực tiếp (chưa từng được lập chỉ mục, hoặc bị rollback bởi reorg) trả về 404 (error.code: "not_found").

Kiểm tra độ mới của dữ liệu (mức độ trễ của từng tập dữ liệu được theo dõi so với đỉnh chuỗi — hữu ích cho trang trạng thái hoặc kiểm tra trước khi tin cậy vào kết quả truy vấn):

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": [
    {
      "dataset": "blocks",
      "category": "raw",
      "max_block_number": 72838957,
      "max_day": null,
      "max_time": "2026-09-27T02:15:01Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "checked_at": "2026-09-27T02:15:07Z"
    }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:07Z"
  }
}

(Đã rút gọn: phản hồi có một hàng cho mỗi tập dữ liệu; chỉ hàng blocks được hiển thị. Hàng traces cũng có thêm coverage_from_block, coverage_to_block và coverage_complete.)

Nếu dữ liệu độ mới tạm thời không khả dụng cho chuỗi này, phản hồi trả về 503 (error.code: "unavailable") thay vì kết quả một phần; phản hồi mang header Retry-After (giây) — hãy đợi ít nhất khoảng thời gian đó rồi thử lại.

Liệt kê số dư ERC-20 của một địa chỉ (ảnh chụp nhanh được lọc cho các số dư khác 0, sắp xếp theo token):

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": [
    { "token": "0x0bd7d308f8e1639fab988df18a8011f41eacad73", "balance": "185371464119396", "symbol": "WETH", "decimals": 18 },
    { "token": "0x2295f15bd4914ae9b4685f01d52f4e6f89bf8b03", "balance": "10000000000000000", "symbol": "WNVDA", "decimals": 18 }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:10:00Z"
  }
}

Địa chỉ không có số dư khác 0 vẫn trả về 200 với data: [] — không bao giờ là 404. Truyền ?limit= (mặc định 50, tối đa 500) và next_cursor được trả về để phân trang qua các trang tiếp theo.

Tài liệu bao quát toàn bộ các điểm cuối — khối, giao dịch, địa chỉ, token, NFT, DEX, cổ phiếu token hóa — có sẵn trong Tài liệu tham khảo API → Data API.

Đọc thêm

• Tài liệu tham khảo API → JSON-RPC — phương thức, trọng số CU, mã lỗi
• Tài liệu tham khảo JSON-RPC đầy đủ — đặc tả đầy đủ, tham số và lược đồ trả về cho tất cả phương thức được hỗ trợ
• Tài liệu tham khảo API → Data API — điểm cuối REST cho dữ liệu chuỗi
• Tập dữ liệu — tập dữ liệu phái sinh trên các chuỗi được hỗ trợ
• Hướng dẫn — hướng dẫn thực tế về tích hợp API, quản lý CU và quy trình làm việc đa chuỗi
• Chuỗi được hỗ trợ — mã định danh mạng và URL điểm cuối

FAQ