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

> Source: https://docs.blockvectra.com/ko/guides/ai-agents/

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

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

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

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

### llms.txt 인덱스

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

* **메인 사이트 인덱스**: [메인 사이트 llms.txt](https://blockvectra.com/llms.txt) — 메인 사이트, 지원 체인, 요금 및 공개 API 개요.
* **문서 인덱스**: [문서 llms.txt](https://docs.blockvectra.com/llms.txt) — 각 문서 페이지의 제목과 설명이 포함된 카탈로그.

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

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

### 다운로드 가능한 OpenAPI 3.1 사양

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

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

지갑 주소 활동에 대해서는 [블록체인 Webhook API 가이드](https://docs.blockvectra.com/en/guides/webhook-push/)를 참조하세요. ERC-20 USDT / USDC 결제 알림에 대해서는 [결제 수신 서버 예제](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks)를 사용하세요. 개발자와 AI 에이전트는 `x-api-key`를 사용하여 HTTP Push API를 통해 구독을 생성하고 관리합니다. 문서 MCP는 이러한 가이드의 검색 및 조회를 지원합니다.

경로 버전 관리, 이전 버전과의 호환성 규칙, 에이전트 및 SDK 개발자를 위한 권장 사항은 [API 버전 관리 및 호환성](https://docs.blockvectra.com/en/api/versioning/)을 참조하세요. 주요 프레임워크(ElizaOS, viem, wagmi, Coinbase AgentKit) 전반의 즉시 사용 가능한 레시피는 [에이전트 프레임워크 레시피](https://docs.blockvectra.com/en/guides/agent-frameworks/)를 참조하세요.

### Model Context Protocol (MCP) 서버

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

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

#### 사용 가능한 도구

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

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

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

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

공식 문서: [Claude Code MCP 문서](https://code.claude.com/docs/en/mcp).

#### Cursor

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

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

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

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

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

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

공식 문서: [Cursor MCP 문서](https://cursor.com/docs/context/mcp) 및 [Cursor 설치 링크](https://cursor.com/docs/context/mcp/install-links).

#### VS Code

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

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

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

```json
{
  "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 서버 문서](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) 및 [VS Code MCP 구성 레퍼런스](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

#### Codex

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

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

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

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

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

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

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

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

공식 문서: [OpenAI Codex CLI MCP 문서](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

#### Gemini CLI

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

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

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

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

공식 문서: [Gemini CLI MCP 서버 문서](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

#### OpenAI Responses API

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

```bash
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` 필드를 포함하세요:

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

공식 문서: [OpenAI MCP 도구 가이드](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) 및 [OpenAI Responses API 레퍼런스](https://developers.openai.com/api/reference/resources/responses/methods/create).

#### Windsurf

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

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

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

```json
{
  "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 문서](https://docs.devin.ai/desktop/cascade/mcp).

#### Claude Desktop 및 claude.ai

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

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

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

공식 문서: [Claude 커스텀 커넥터 가이드](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

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

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

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

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

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

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

```bash
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`.

응답 예시:

```json
{
  "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`)

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

```bash
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`을 통한 트랜잭션 브로드캐스트 속도 제한.

응답 예시:

```json
{
  "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 속도 제한 및 버스트 용량을 갖습니다. 사용하지 않은 무료 크레딧은 크레딧 잔액에 유지되며 계속 사용할 수 있습니다. 자세한 내용은 [요금 페이지](https://blockvectra.com/en/pricing/)를 참조하세요.

> **No API key yet?**
>
> 이더리움 지갑이 있는 경우: [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/en/guides/programmatic-signup/)에 따라 브라우저 없이 이더리움 지갑 서명을 사용하여 가입하고 API key를 생성하세요. 에이전트의 신원은 지갑입니다. 세션 토큰이나 키를 분실한 경우 [동일한 지갑으로 다시 인증하여 복구](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)할 수 있습니다. 지갑이 없는 경우: 사용자에게 [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F)에 로그인하여 키를 생성하고 환경 변수 `BLOCKVECTRA_API_KEY`로 설정하도록 요청하세요. 사용자에게 키를 채팅창에 붙여넣도록 요청하지 마세요.


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

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

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

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

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

## 5. 최소 동작 예제

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

**cURL**

```bash
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":[]}'
```


  **TypeScript**

```typescript
const apiKey = process.env.BLOCKVECTRA_API_KEY;

if (!apiKey) {
  throw new Error("Missing BLOCKVECTRA_API_KEY");
}

type ChainFacts = {
  chain: string;
  jsonrpc: boolean;
  methods: { allow: string[]; deny: string[] };
};

function matches(pattern: string, method: string): boolean {
  if (pattern === "*") return true;
  if (pattern.endsWith("*")) return method.startsWith(pattern.slice(0, -1));
  return pattern === method;
}

// 1. Fetch the public chain directory
const chainsRes = await fetch("https://api.blockvectra.com/v1/chains");
const { chains } = (await chainsRes.json()) as { chains: ChainFacts[] };

// 2. Select a chain that serves JSON-RPC and allows eth_blockNumber
const selected = chains.find(
  (chain) =>
    chain.jsonrpc &&
    !chain.methods.deny.some((pattern) => matches(pattern, "eth_blockNumber")) &&
    chain.methods.allow.some((pattern) => matches(pattern, "eth_blockNumber")),
);

if (!selected) {
  throw new Error("No chain found that allows eth_blockNumber");
}

// 3. Confirm the service and the selected chain are ready
const statusRes = await fetch("https://api.blockvectra.com/v1/status");
const status = await statusRes.json();
const chainStatus = status.chains?.find(
  (chain: { chain: string }) => chain.chain === selected.chain,
);

if (status.gateway?.status !== "ok" || chainStatus?.status !== "ok") {
  throw new Error(`Chain ${selected.chain} is currently unavailable`);
}

// 4. Call eth_blockNumber on the selected chain
const defaultEndpoint = "https://api.blockvectra.com/v1/robinhood_mainnet";
const rpcUrl = `${defaultEndpoint.slice(0, defaultEndpoint.lastIndexOf("/"))}/${selected.chain}`;
const rpcRes = await fetch(rpcUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "x-bv-meter": "1",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_blockNumber",
    params: [],
  }),
});

console.log("Response:", await rpcRes.json());
```


  **Python**

```python
import os
import requests

api_key = os.environ["BLOCKVECTRA_API_KEY"]


def matches(pattern: str, method: str) -> bool:
    if pattern == "*":
        return True
    if pattern.endswith("*"):
        return method.startswith(pattern[:-1])
    return pattern == method


# 1. Fetch the public chain directory
chains = requests.get("https://api.blockvectra.com/v1/chains").json()["chains"]

# 2. Select a chain that serves JSON-RPC and allows eth_blockNumber
selected = next(
    (
        chain
        for chain in chains
        if chain["jsonrpc"]
        and not any(matches(p, "eth_blockNumber") for p in chain["methods"]["deny"])
        and any(matches(p, "eth_blockNumber") for p in chain["methods"]["allow"])
    ),
    None,
)

if selected is None:
    raise RuntimeError("No chain found that allows eth_blockNumber")

# 3. Confirm the service and the selected chain are ready
status = requests.get("https://api.blockvectra.com/v1/status").json()
chain_status = next(
    (c for c in status["chains"] if c["chain"] == selected["chain"]),
    None,
)

if (
    status["gateway"]["status"] != "ok"
    or chain_status is None
    or chain_status["status"] != "ok"
):
    raise RuntimeError(f"Chain {selected['chain']} is currently unavailable")

# 4. Call eth_blockNumber on the selected chain
default_endpoint = "https://api.blockvectra.com/v1/robinhood_mainnet"
rpc_url = f"{default_endpoint.rsplit('/', 1)[0]}/{selected['chain']}"
rpc_response = requests.post(
    rpc_url,
    headers={
        "Content-Type": "application/json",
        "x-api-key": api_key,
        "x-bv-meter": "1",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []},
).json()

print("Response:", rpc_response)
```


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

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

응답 헤더에서 요청당 CU 청구액과 남은 잔액 단위를 확인하려면 `x-bv-meter: 1`을 포함하세요. 헤더 동작 및 오류 사례에 대해서는 [과금 및 잔액 응답 헤더](https://docs.blockvectra.com/en/guides/billing-rules/#http-status-codes-and-billing-rules)를 참조하세요.

## 다음 단계

* [데이터셋 디렉터리 살펴보기](https://blockvectra.com/en/data/): BlockVectra가 인덱싱하는 모든 데이터셋을 확인하세요.
* [무료 플랜 및 요금 확인](https://blockvectra.com/en/pricing/#free): 계정에 포함된 혜택을 확인하세요.
* [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/en/guides/programmatic-signup/)를 따라 지갑 서명으로 가입하고 API key를 생성하거나, [콘솔에 로그인](https://console.blockvectra.com/login/?next=%2Fkeys%2F)하여 키를 생성하세요.