AI 에이전트를 위한 블록체인 RPC 및 문서 MCP

AI 에이전트를 블록체인 RPC 및 문서 MCP에 연결하세요. 키 없이 기능을 탐색하고, HTTP를 통해 가입한 후, API key로 RPC 및 Data API를 호출합니다.

키가 필요 없는 문서 MCP 엔드포인트로 블록체인 RPC 메서드, Data API 데이터셋, 요금 및 문서를 탐색하는 것부터 시작하세요. AI 에이전트는 일등 사용자입니다. 개발자와 AI 에이전트는 동일한 API, 규칙, 한도 및 가격을 사용합니다.

탐색: 문서 MCP, llms.txt, OpenAPI 및 공개 JSON을 사용하여 체인과 메서드를 선택합니다. 키 없는 RPC 호출은 해당 체인의 public.methods로 제한됩니다.
HTTP를 통해 계정 생성: 프로그래밍 방식 회원가입에 따라 지갑 서명으로 로그인하고 API key를 생성합니다. MCP의 how_to_get_api_key는 이 별도의 HTTP 흐름에 대한 지침을 반환합니다.
데이터 API 호출: 키를 BLOCKVECTRA_API_KEY에 보관하고 인증된 RPC 또는 Data API 요청에 사용합니다. 키가 필요한 MCP 도구의 경우 클라이언트의 x-api-key 헤더를 구성하세요. 각 도구의 허용된 작업은 아래에 나열되어 있습니다.

1. 기계 판독 가능한 컨텍스트 및 사양

BlockVectra는 LLM 에이전트와 개발자 도구를 위한 파일을 제공합니다:

llms.txt 인덱스

llmstxt.org 규약에 따라, 이 파일들은 에이전트에게 사이트와 엔드포인트에 대한 구조화된 요약을 제공합니다:

메인 사이트 인덱스: 메인 사이트 llms.txt — 메인 사이트, 지원 체인, 요금 및 공개 API 개요.
문서 인덱스: 문서 llms.txt — 각 문서 페이지의 제목과 설명이 포함된 카탈로그.

전체 문서 단일 파일 (`llms-full.txt`)

전체 문서: llms-full.txt — 모든 영문 문서 페이지의 전문을 하나의 일반 텍스트 Markdown 파일로 제공하며, 에이전트의 시스템 프롬프트에 로드하거나 검색 증강 생성(RAG) 파이프라인에 수집하기에 적합합니다.

다운로드 가능한 OpenAPI 3.1 사양

문서 사이트는 에이전트 프레임워크, 도구 생성기 또는 API 클라이언트로 직접 가져올 수 있는 OpenAPI 3.1 YAML 파일을 제공합니다:

JSON-RPC API 사양: /openapi/json-rpc.yaml — 지원 메서드, 체인별 메서드 정책, 오류 응답 및 연산 단위(CU) 계량.
Data API 사양: /openapi/data.yaml — 인덱싱된 블록, 트랜잭션, 전송, 잔액, 보유자 및 관련 데이터셋에 대한 REST 엔드포인트 정의.
Push API 사양: /openapi/push.yaml — HTTP 구독 관리, 모니터링 대상 지갑 주소, 웹훅 이벤트, 서명 및 재생(replay).

지갑 주소 활동에 대해서는 블록체인 Webhook API 가이드를 참조하세요. ERC-20 USDT / USDC 결제 알림에 대해서는 결제 수신 서버 예제를 사용하세요. 개발자와 AI 에이전트는 x-api-key를 사용하여 HTTP Push API를 통해 구독을 생성하고 관리합니다. 문서 MCP는 이러한 가이드의 검색 및 조회를 지원합니다.

경로 버전 관리, 이전 버전과의 호환성 규칙, 에이전트 및 SDK 개발자를 위한 권장 사항은 API 버전 관리 및 호환성을 참조하세요. 주요 프레임워크(ElizaOS, viem, wagmi, Coinbase AgentKit) 전반의 즉시 사용 가능한 레시피는 에이전트 프레임워크 레시피를 참조하세요.

Model Context Protocol (MCP) 서버

BlockVectra는 Streamable HTTP를 통해 상태 비저장(stateless), 키 불필요 MCP 서버를 제공합니다:

엔드포인트: MCP 엔드포인트 (JSON-RPC 2.0을 수신하는 HTTP POST, GET은 405 반환)
전송 방식: MCP Streamable HTTP (상태 비저장, API key 불필요)

사용 가능한 도구

read_doc(path, lang?): /md/{lang}/{path}.md에서 문서 페이지의 원시 Markdown 내용을 반환합니다. 내부 상대 경로(예: quickstart, guides/ai-agents, api/json-rpc, chains)를 허용합니다.
search_docs(query, lang?, limit?): 제목, 경로 및 요약 전반에 걸쳐 문서 페이지를 검색합니다.
list_chains(): GET /v1/chains에서 지원되는 블록체인 네트워크, 정적 파라미터 및 메서드 정책을 읽습니다.
get_status(): GET /v1/status에서 실시간 서비스 준비 상태, 네트워크 상태, 최신 블록 높이 및 동기화 지연을 읽습니다.
get_pricing(): GET /v1/plans에서 연산 단위(CU) 가중치, 무료 플랜 파라미터 및 기본 키 한도를 읽습니다.
estimate_usage(lines?, method?, calls_per_day?): 하나 이상의 메서드에 대해 연산 단위(CU), 총 정가 비용, 주기 무료 할당량을 차감한 순 비용을 추정합니다(다중 행 lines: [{method, calls_per_day}] 또는 단일 method 및 calls_per_day 지원). 또한 key_defaults의 키별 속도 제한을 보고하고 트래픽이 단일 키 한도를 초과할 때 필요한 API key 수를 제안합니다.
how_to_get_api_key(lang?): JSON-RPC 및 Data API에 대한 API key 전달 단계 및 요청 인증 형식을 반환합니다.
get_method_info(method, chain?): 특정 메서드에 대한 체인 가용성, 연산 단위(CU) 가중치, 100만 회 호출당 가격 및 문서 링크를 반환합니다. JSON-RPC 가용성은 GET /v1/chains의 methods.allow 및 deny를 따르며, Data API 데이터셋 범위는 GET /v1/status의 data_features와 체인 카탈로그의 data: true를 따릅니다.
explain_error(reason?, code?, http_status?): 오류 카탈로그에서 오류 설명, 과금 영향, 재시도 가능 여부 및 복구 조치를 조회합니다.
list_docs(lang?): 문서 인덱스에서 상대 경로 및 제목과 함께 모든 문서 페이지를 나열합니다.
rpc_call(chain, method, params?): API key를 사용하여 지원 체인에서 읽기 전용 JSON-RPC 2.0 호출을 실행합니다(readOnlyHint: true). 쓰기 메서드(예: eth_sendRawTransaction)는 거부되므로 대신 send_raw_transaction을 사용하세요. 전체 접근을 위해 MCP 클라이언트 구성에 x-api-key 헤더가 필요하거나, 가능한 경우 키 없는 퍼블릭 엔드포인트를 사용합니다.
data_api_get(chain, path, query?): API key를 사용하여 지원 체인 및 경로에 대해 Data API에 GET 요청을 보냅니다(readOnlyHint: true). MCP 클라이언트 구성에 x-api-key 헤더가 필요합니다.
get_account(): API key를 사용하여 GET /v1/account에서 계정 잔액, 연산 단위(CU), 속도 제한 및 키 파라미터를 조회합니다(readOnlyHint: true). MCP 클라이언트 구성에 x-api-key 헤더가 필요합니다.
get_deposit_address(): API key를 사용하여 GET /v1/topup/deposit-address에서 전용 온체인 입금 주소, 지원 네트워크 및 토큰을 조회합니다(readOnlyHint: true). 나열된 네트워크 및 토큰으로만 입금하세요. MCP 클라이언트 구성에 x-api-key 헤더가 필요합니다.
send_raw_transaction(chain, raw_tx): eth_sendRawTransaction을 통해 서명된 원시 트랜잭션을 지원 체인에 브로드캐스트합니다(destructiveHint: true). 전체 접근을 위해 MCP 클라이언트 구성에 x-api-key 헤더가 필요하거나, 해당 체인에서 허용되는 경우 키 없는 퍼블릭 엔드포인트를 사용합니다.

키가 필요한 도구

키가 필요한 도구는 온체인 쿼리, 트랜잭션, Data API 요청 또는 계정 작업을 실행하기 위해 API key가 필요합니다.

API key 보안:

헤더에서만 엄격하게 읽기: API key는 오직 MCP 클라이언트 HTTP 요청 헤더(x-api-key: rgw_... 또는 Authorization: Bearer rgw_...)에서만 읽힙니다.
채팅에 키를 절대 입력하지 마세요: 도구 인수나 대화 채팅창에 API key 또는 개인키를 절대 전달하지 마세요. 도구 인수와 대화 기록은 대화 로그 및 컨텍스트에 포함되므로 인수에 키를 전달하면 거부됩니다.

API key 헤더 없이 호출되면 이러한 도구는 isError: true를 반환하고 에이전트를 how_to_get_api_key 및 프로그래밍 방식 온보딩 가이드로 안내합니다.

MCP 클라이언트에서 연결하기

일반적인 개발 환경 및 프레임워크 전반에서 https://docs.blockvectra.com/mcp의 BlockVectra 문서 MCP 서버에 연결할 수 있습니다.

API key 없이 시작하세요. MCP 엔드포인트에 연결하고 list_chains를 호출한 다음 read_doc으로 빠른 시작을 읽어보세요. Data API 또는 계정 도구가 필요할 때 클라이언트의 HTTP 헤더에 API key를 추가하세요. 키 없는 RPC 접근은 각 체인의 퍼블릭 메서드 정책을 따릅니다.

x-api-key 헤더는 선택 사항입니다. API key가 없어도 클라이언트는 모든 읽기 전용 문서 도구(read_doc, search_docs, list_docs), 체인 검색(list_chains), 실시간 상태(get_status), 요금 추정(get_pricing, estimate_usage), 오류 설명(explain_error) 및 퍼블릭 엔드포인트에서 허용된 메서드를 사용할 수 있습니다. 키가 필요한 도구(제한된 메서드에 대한 rpc_call, send_raw_transaction, data_api_get, get_account, get_deposit_address)를 사용할 때는 x-api-key 헤더에 API key를 구성하세요.

Claude Code

CLI를 사용하여 MCP 서버에 연결합니다:

claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp

인증된 도구를 위해 선택적 API key를 포함하려면 --header(또는 -H) 옵션을 전달하세요:

claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header "x-api-key: YOUR_API_KEY"

공식 문서: Claude Code MCP 문서.

Cursor

Cursor의 MCP 구성에 서버를 추가합니다:

{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}

Cursor는 base64로 인코딩된 구성 eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9({"url":"https://docs.blockvectra.com/mcp"}를 나타냄)을 사용하는 딥 링크를 통한 원클릭 설치도 지원합니다:

cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9

인증된 도구(Data API 또는 계정 관리)가 필요한 경우 API key가 포함된 headers 객체를 추가하세요:

{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

공식 문서: Cursor MCP 문서 및 Cursor 설치 링크.

VS Code

VS Code에서는 type: "http"를 사용하여 최상위 servers 키 아래의 .vscode/mcp.json에 서버를 구성합니다:

{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}

인증된 도구가 필요한 경우 headers 객체를 추가하세요:

{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

민감한 자격 증명을 저장할 때 VS Code는 키를 하드코딩하는 대신 입력 변수나 환경 파일을 참조하는 것을 지원합니다. 명령 팔레트 작업 MCP: Add Server를 사용하여 서버를 추가할 수도 있습니다.

공식 문서: VS Code MCP 서버 문서 및 VS Code MCP 구성 레퍼런스.

Codex

OpenAI Codex CLI를 사용하여 서버를 추가합니다:

codex mcp add blockvectra --url https://docs.blockvectra.com/mcp

config.toml에서 서버 URL을 구성합니다:

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"

인증된 도구가 필요한 경우 config.toml에 요청 헤더를 구성하세요:

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }

또는 환경 변수에서 헤더를 매핑합니다:

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }

공식 문서: OpenAI Codex CLI MCP 문서.

Gemini CLI

Gemini CLI 구성에서 Streamable HTTP용 httpUrl을 사용하여 mcpServers 아래에 서버를 추가합니다:

{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}

인증된 도구가 필요한 경우 API key가 포함된 headers 객체를 추가하세요:

{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

공식 문서: Gemini CLI MCP 서버 문서.

OpenAI Responses API

OpenAI Responses API를 호출할 때 type: "mcp"와 함께 tools 배열에 MCP 서버를 전달합니다:

OPENAI_API_BASE="https://api.openai.com/v1"
curl "$OPENAI_API_BASE/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "blockvectra",
      "server_url": "https://docs.blockvectra.com/mcp",
      "require_approval": "never"
    }],
    "input": "..."
  }'

인증된 도구가 필요한 경우 도구 정의에 headers 필드를 포함하세요:

{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}

공식 문서: OpenAI MCP 도구 가이드 및 OpenAI Responses API 레퍼런스.

Windsurf

Windsurf에서는 serverUrl 필드를 사용하여 mcpServers 아래에 서버를 구성합니다:

{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}

인증된 도구가 필요한 경우 API key가 포함된 headers 객체를 추가하세요:

{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf는 "x-api-key": "${env:BLOCKVECTRA_API_KEY}"와 같이 환경 변수를 참조하는 것도 지원합니다.

공식 문서: Windsurf MCP 문서.

Claude Desktop 및 claude.ai

커스텀 커넥터는 사용자 인터페이스를 통해 구성됩니다:

claude.ai: Customize > Connectors로 이동하여 + Add를 클릭하고, Add custom connector를 선택한 후 URL을 입력합니다:
```
https://docs.blockvectra.com/mcp
```
Claude Desktop: 계정 설정 메뉴를 열고 커넥터 인터페이스를 통해 커스텀 커넥터를 구성합니다.

해당 URL에 연결하면 Claude가 인증 정보 없이 가이드를 검색하고, Markdown 문서를 읽고, 지원 체인을 검사하고, 네트워크 상태를 확인하며, 요금 추정치를 계산할 수 있습니다.

공식 문서: Claude 커스텀 커넥터 가이드.

2. 퍼블릭 JSON 엔드포인트 (키 불필요)

에이전트는 과금 대상 요청을 보내기 전에 사용 가능한 체인, 실시간 상태 및 플랜 파라미터를 검사할 수 있습니다. 이러한 엔드포인트는 모두 API key가 필요하지 않습니다:

GET /v1/status 및 GET /v1/chains는 인증이 필요 없고 과금되지 않습니다.
GET /v1/plans는 공개되어 있으며 인증이 필요 없습니다.

세 가지 모두 Access-Control-Allow-Origin: *를 전송합니다.

서비스 상태 (`GET /v1/status`)

서비스 준비 상태 및 각 퍼블릭 체인의 동기화 상태를 반환합니다:

curl -s "https://api.blockvectra.com/v1/status"

응답 필드:

checked_at: 스냅샷이 생성된 시점 (RFC 3339 / ISO 8601 UTC).
gateway.status: 서비스 실행 상태입니다. ok는 서비스가 준비되었음을 의미하고, degraded는 복구될 때까지 유료 요청이 거부됨을 의미합니다. 이 값은 개별 체인의 노드 상태와 무관합니다.
chains[]: 대중에게 제공되는 체인 목록:
- chain: 체인 슬러그 (예: robinhood_mainnet).
- name: 사람이 읽을 수 있는 표시 이름.
- chain_id: EIP-155 Chain ID (10진수 정수).
- jsonrpc: JSON-RPC 제공 여부.
- data: Data API 제공 여부.
- data_features: 이 체인에서 사용 가능한 Data API 기능 (data가 false일 때 빈 배열).
- data_status: Data API 실행 상태 (ok, syncing, 또는 unavailable; data가 true일 때만 존재).
- status: 체인 노드 상태 (ok 또는 unavailable).
- head: 최신 블록 정보 — block (최신 블록 높이), time (블록 타임스탬프), lag_seconds (블록 시간이 현재 시간보다 얼마나 지연되었는지) — 또는 알 수 없는 경우 null.

응답 예시:

{
  "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
      }
    }
  ]
}

체인 파라미터 (`GET /v1/chains`)

각 퍼블릭 체인의 정적 파라미터 및 메서드 정책을 반환합니다:

curl -s "https://api.blockvectra.com/v1/chains"

응답 필드:

chains[]: 퍼블릭 체인 및 정적 파라미터:
- chain: 체인 슬러그.
- name: 사람이 읽을 수 있는 표시 이름.
- chain_id: EIP-155 Chain ID.
- jsonrpc: JSON-RPC 제공 여부.
- data: Data API 제공 여부.
- ws: WebSocket 연결 지원 여부.
- subscriptions: 지원되는 WebSocket 구독 유형 (예: newHeads, logs).
- methods: 메서드 정책:
  - allow: 허용된 메서드 이름 (예: eth_call, debug_traceTransaction).
  - deny: 거부된 메서드 또는 접두사 와일드카드 패턴 (예: eth_newFilter). 거부된 메서드가 허용된 메서드보다 우선합니다.
- max_logs_block_range: 단일 eth_getLogs 요청에서 허용되는 최대 블록 범위.
- state_window_blocks: 블록 단위의 과거 상태 보존 윈도우. 전체 이력을 사용할 수 있는 경우 null.
- info: 체인별 공개 확장 데이터 (예약됨, 현재는 빈 객체 {}).
- public: 인증 없는 퍼블릭 엔드포인트 구성 (또는 null):
  - url: 퍼블릭 요청을 위한 기본 URL.
  - methods: 퍼블릭 엔드포인트에서 허용되는 메서드.
  - rate_limit: 속도 제한 (per_ip_rps, burst, batch_max).
  - history_blocks: 퍼블릭 엔드포인트에서 접근 가능한 블록 이력.
  - send_raw_rate_limit: eth_sendRawTransaction을 통한 트랜잭션 브로드캐스트 속도 제한.

응답 예시:

{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "ws": true,
      "subscriptions": [
        "newHeads",
        "logs"
      ],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "debug_traceTransaction"
        ],
        "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": {},
      "public": {
        "url": "https://api.blockvectra.com/v1/robinhood_mainnet/public",
        "methods": [
          "eth_chainId",
          "net_version",
          "eth_blockNumber",
          "eth_call"
        ],
        "rate_limit": {
          "per_ip_rps": 3,
          "burst": 20,
          "batch_max": 10
        },
        "history_blocks": 128,
        "send_raw_rate_limit": {
          "per_ip_rps": 1,
          "burst": 3
        }
      }
    }
  ]
}

플랜 및 메서드 가중치 (`GET /v1/plans`)

플랜 파라미터는 GET https://console-api.blockvectra.com/v1/plans에서 제공됩니다. 에이전트는 런타임에 이 엔드포인트를 쿼리하여 활성 무료 플랜 한도와 각 메서드의 연산 단위(CU) 가중치를 읽을 수 있습니다:

free: 무료 플랜 파라미터 — signup_units (가입 지급액, 단위 기준), monthly_units (주기 충전 기준, 단위 기준), window_days (사용 주기 일수), max_calls_per_sec (무료 플랜 초당 호출 수 한도).
pricing: 유료 플랜 파라미터 — units_per_usd (1 USD당 단위), cu_per_unit (단위당 CU), min_topup_usd (USD 기준 최소 충전 금액).
method_weights: 호출당 CU 가중치, 각각 { "method": string, "cu_weight": number }. method는 JSON-RPC 메서드 이름 또는 패턴, 목록에 없는 메서드의 기본 가중치, 또는 data.<op>와 같은 Data API 작업을 지정합니다. 가중치는 메서드별로 적용되며 체인별로 나뉘지 않습니다.

3. 인증 및 키 보안

RPC 호출을 수행하는 에이전트는 다음 규칙을 따라야 합니다:

인증: 세 가지 방법 중 하나로 API key를 전달합니다. 경로 전달 방식: POST /v1/{chain}/{api_key} — 경로 형식은 경로의 키만 사용하고 두 헤더는 모두 무시합니다. x-api-key 헤더 전달 방식: x-api-key: $BLOCKVECTRA_API_KEY와 함께 POST /v1/{chain}. Authorization 헤더 전달 방식: Authorization: Bearer $BLOCKVECTRA_API_KEY와 함께 POST /v1/{chain}. 두 헤더가 모두 있는 경우 비어 있지 않은 x-api-key가 우선합니다. Bearer는 x-api-key가 없거나 비어 있을 때만 사용됩니다. 동일한 키가 모든 지원 체인과 Data API(키를 x-api-key 헤더로만 허용)에서 작동합니다.
키 보안: API key는 서버 측 환경 변수(예: BLOCKVECTRA_API_KEY) 또는 비밀 관리자(secrets manager)에 보관하세요. 브라우저 코드나 클라이언트 측 번들에 키를 절대 포함하지 마세요. 엔드포인트는 Access-Control-Allow-Origin: *를 반환하지만 브라우저가 아닌 백엔드 서비스에서 호출하도록 설계되었습니다.
계량 및 업그레이드: 사용량은 연산 단위(CU)로 계량됩니다. 각 메서드는 가중치에 따라 CU를 소비하며 잔액, CU 버킷 및 무료 플랜 속도 제한은 모든 체인에서 공유됩니다. 유료 충전 후에는 무료 플랜의 초당 호출 수 한도가 더 이상 적용되지 않으며, 각 키는 여전히 CU 속도 제한 및 버스트 용량을 갖습니다. 사용하지 않은 무료 크레딧은 크레딧 잔액에 유지되며 계속 사용할 수 있습니다. 자세한 내용은 요금 페이지를 참조하세요.

No API key yet?

이더리움 지갑이 있는 경우: 프로그래밍 방식 회원가입 가이드에 따라 브라우저 없이 이더리움 지갑 서명을 사용하여 가입하고 API key를 생성하세요. 에이전트의 신원은 지갑입니다. 세션 토큰이나 키를 분실한 경우 동일한 지갑으로 다시 인증하여 복구할 수 있습니다. 지갑이 없는 경우: 사용자에게 console.blockvectra.com에 로그인하여 키를 생성하고 환경 변수 BLOCKVECTRA_API_KEY로 설정하도록 요청하세요. 사용자에게 키를 채팅창에 붙여넣도록 요청하지 마세요.

잔액 조회 (`GET /v1/account`)

에이전트는 연산 단위(CU)를 소비하지 않고 키의 현재 잔액, CU 한도 및 키 파라미터를 직접 확인할 수 있습니다. 요청 형식, 속도 제한 및 전체 응답 필드 정의는 잔액 조회: GET /v1/account를 참조하세요.

4. 에이전트를 위한 체인 선택 워크플로

호출을 발송하기 전에 에이전트는 다음 단계를 따를 수 있습니다:

체인 및 메서드 정책 확인: GET /v1/chains를 호출하여 대상 체인이 존재하고 jsonrpc: true인지, 호출하려는 메서드가 methods.allow에 의해 허용되고 methods.deny에 의해 거부되지 않는지 확인합니다(거부가 우선).
실시간 상태 확인: GET /v1/status를 호출하여 gateway.status가 ok이고 대상 체인의 status가 ok인지 확인합니다. head.lag_seconds를 사용하여 체인의 데이터가 활용 사례에 충분히 최신인지 판단합니다. 체인의 노드가 동기화되지 않은 경우 eth_chainId를 제외한 모든 메서드가 JSON-RPC 오류 -32010(HTTP 200, 과금되지 않음)을 반환하므로, 에이전트는 대기 후 재시도하거나 다른 체인을 선택할 수 있습니다.
요청 전송: x-api-key 헤더와 표준 JSON-RPC 본문으로 POST /v1/{chain}을 호출합니다.

5. 최소 동작 예제

아래 예제는 /v1/chains를 읽어 eth_blockNumber를 허용하는 체인을 선택하고, /v1/status를 확인한 후 eth_blockNumber를 한 번 호출합니다.

export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. List public chains and their method policy
curl -s "https://api.blockvectra.com/v1/chains"

# 2. Check the service and per-chain status
curl -s "https://api.blockvectra.com/v1/status"

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

성공적인 호출은 표준 JSON-RPC 응답 객체를 반환합니다:

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

응답 헤더에서 요청당 CU 청구액과 남은 잔액 단위를 확인하려면 x-bv-meter: 1을 포함하세요. 헤더 동작 및 오류 사례에 대해서는 과금 및 잔액 응답 헤더를 참조하세요.

다음 단계

데이터셋 디렉터리 살펴보기: BlockVectra가 인덱싱하는 모든 데이터셋을 확인하세요.
무료 플랜 및 요금 확인: 계정에 포함된 혜택을 확인하세요.
프로그래밍 방식 회원가입 가이드를 따라 지갑 서명으로 가입하고 API key를 생성하거나, 콘솔에 로그인하여 키를 생성하세요.

AI 에이전트를 위한 블록체인 RPC 및 문서 MCP

이 페이지의 내용