# 빠른 시작

> Source: https://docs.blockvectra.com/ko/quickstart/

개발자와 AI 에이전트는 키 없이 퍼블릭 RPC를 사용해 본 다음, 키를 생성하여 계속 진행할 수 있습니다.

## 1. 키 없이 블록 높이 읽기

계정을 생성하거나 API key를 제공하지 않고 예제 체인 `robinhood_mainnet`의 퍼블릭 JSON-RPC 엔드포인트를 호출합니다:

```bash
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`은 이 요청과 일치합니다. `result`는 16진수 블록 높이이며 호출 간에 변경될 수 있습니다. 응답에 `error`가 포함되어 있으면 해당 코드와 이유를 확인하세요. 공개 메서드, 이력 범위 및 IP별 제한에 대해서는 [무료 퍼블릭 RPC 엔드포인트](https://blockvectra.com/en/free/#public-rpc)를 참조하세요.

## 2. API key 생성

[콘솔](https://console.blockvectra.com/login/?next=%2Fkeys%2F)로 이동하여 GitHub, Google 또는 이더리움 지갑으로 로그인하고(최초 로그인 시 계정이 생성됨) API key를 생성하세요. 시크릿은 한 번만 표시됩니다. 안전하게 저장하고 환경 변수 `BLOCKVECTRA_API_KEY`로 설정하세요. 클라이언트 측 브라우저 코드에는 포함하지 마세요. 신규 계정 가입 시 30,000,000 CU 무료 제공 — 신용카드 불필요.

> **No API key yet?**
>
> 이더리움 지갑이 있는 경우: [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/en/guides/programmatic-signup/)에 따라 브라우저 없이 이더리움 지갑 서명을 사용하여 가입하고 API key를 생성하세요. 지갑이 없는 경우: 사용자에게 [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F)에 로그인하여 키를 생성하고 환경 변수 `BLOCKVECTRA_API_KEY`로 설정하도록 요청하세요. 사용자에게 키를 채팅창에 붙여넣도록 요청하지 마세요.


## 3. 첫 번째 인증 호출 보내기

`x-api-key` 헤더를 사용하여 동일한 체인의 블록 높이를 읽습니다. URL은 후행 슬래시 없이 체인 이름으로 끝납니다:

```bash
: "${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`는 다시 16진수 블록 높이입니다. 이 요청은 CU를 소비합니다. 메서드 가중치 및 오류 코드는 [JSON-RPC 레퍼런스](https://docs.blockvectra.com/en/api/json-rpc/)를, 현재 요율은 [요금 페이지](https://blockvectra.com/en/pricing/)를 참조하세요. 새 키는 적용되는 데 약 5초가 걸립니다. `invalid_api_key`가 반환되면 잠시 기다렸다가 다시 시도하세요. 기타 실패에 대해서는 아래 [일반적인 오류](#common-errors)를 참조하세요.

## 4. 비즈니스 작업 계속하기

* [Robinhood Chain에서의 온체인 토큰화 주식 활동 조회](https://docs.blockvectra.com/en/guides/stocks/)
* [청크 단위로 HyperEVM 로그 백필](https://docs.blockvectra.com/en/guides/hyperevm-backfill/)
* [웹훅을 통한 지갑 활동 및 토큰 전송 수신](https://docs.blockvectra.com/en/guides/webhook-push/)

## 레퍼런스

### API key 및 잔액

완전한 스타터 템플릿: [blockvectra/agent-quickstart](https://github.com/blockvectra/agent-quickstart)

모든 키는 `rgw_` 뒤에 64자리의 16진수 문자가 붙는 형태입니다(예: `rgw_1f2e...` (생략됨)). 비밀을 유지하세요. 키를 가진 사람은 누구나 잔액을 사용할 수 있습니다.

> 잔액이 부족한 경우 서버는 HTTP 402를 반환합니다(JSON-RPC 오류 코드 `-32020`, Data API `error.code`는 `insufficient_balance`). 콘솔 [결제 관리 페이지](https://console.blockvectra.com/billing/)로 이동하여 잔액 및 충전 방법을 확인하세요.


### API 키 없이 체험하기

계정을 생성하거나 API 키를 입력하지 않고도 공개 JSON-RPC 엔드포인트를 즉시 호출할 수 있습니다. 아래 예제 엔드포인트는 IP별 속도 제한이 적용됩니다(IP당 3 req/s, 버스트 20, 배치당 최대 10회 호출). 제한을 초과하는 요청은 `public_rate_limit` 또는 `public_pool_busy` 사유와 함께 HTTP 429를 반환합니다(`Retry-After` 헤더 포함). 지원되지 않는 메서드는 JSON-RPC 오류 `-32601`(`method_not_public`)을 반환합니다.

```bash
# 직접 공개 엔드포인트 호출:
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":[]}'

# 또는 API 키 폴백 패턴 사용(BLOCKVECTRA_API_KEY가 설정되지 않은 경우 기본값으로 public 사용):
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":[]}'
```

#### 체인별 공개 엔드포인트

- Arbitrum One: https://api.blockvectra.com/v1/arb_mainnet/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)
- Base: https://api.blockvectra.com/v1/base_mainnet/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)
- BNB Smart Chain: https://api.blockvectra.com/v1/bsc_mainnet/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)
- Ethereum: https://api.blockvectra.com/v1/eth_mainnet/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)
- Ethereum Sepolia: https://api.blockvectra.com/v1/eth_sepolia/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)
- HyperEVM: https://api.blockvectra.com/v1/hyperevm_mainnet/public — 읽기 전용
- Polygon: https://api.blockvectra.com/v1/polygon_mainnet/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)
- Robinhood Chain: https://api.blockvectra.com/v1/robinhood_mainnet/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)
- Robinhood Chain Testnet: https://api.blockvectra.com/v1/robinhood_testnet/public — 읽기 및 서명된 트랜잭션 전송(eth_sendRawTransaction)

다음 두 가지 공개 메타데이터 엔드포인트는 서비스 상태와 각 체인의 구성을 보여줍니다. API key가 필요하지 않으며 과금되지 않습니다.

### 서비스 및 체인 상태 확인

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

확인 타임스탬프 `checked_at`, 서비스 작동 상태 `gateway.status`, 지원되는 각 체인의 노드 동기화 진행 상태 `sync`, 헤드 블록 높이 및 지연 시간 `head`를 반환합니다:

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

### 지원되는 체인 및 메서드 정책 조회

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

지원되는 각 체인의 `chain_id`, JSON-RPC, Data API 및 WebSocket 기능 플래그, 메서드 허용 및 거부 정책(`methods.allow` 및 `methods.deny`), 단일 쿼리 로그 블록 범위 제한 `max_logs_block_range` 및 과거 상태 윈도우 `state_window_blocks`를 반환합니다:

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

### 체인 선택

모든 BlockVectra 엔드포인트는 체인별로 범위가 지정됩니다: JSON-RPC 요청은 URL 경로에 체인 이름 `{chain}`을 포함하고, Data API 요청은 경로 앞에 이를 접두사로 사용합니다. 현재 사용 가능한 체인 및 식별자는 [지원 체인](https://docs.blockvectra.com/en/chains/)을 참조하세요.

| 체인 | {chain} | Chain ID | Tracing | 공개 엔드포인트 | WebSocket | Data API | API 키로 사용할 수 있는 메서드 수 | Webhook 푸시 | 트랜잭션 전송 | 트랜잭션 전송 (key 없는 공개 엔드포인트) | 상태 기록 보관 기간 | eth_getLogs 최대 블록 범위 | Data API 데이터셋 | 관련 테스트넷 | 관련 가이드 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| [arb_mainnet RPC 및 Data API](https://blockvectra.com/ko/chains/arb_mainnet/) | arb_mainnet | 42161 | ✓ | `https://api.blockvectra.com/v1/arb_mainnet/public` | 미지원 | 사용 가능 | 43 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 최근 6,000개 블록의 과거 상태 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 데이터 최신성 | 알 수 없음 | 알 수 없음 |
| [base_mainnet RPC 및 Data API](https://blockvectra.com/ko/chains/base_mainnet/) | base_mainnet | 8453 | — | `https://api.blockvectra.com/v1/base_mainnet/public` | 미지원 | 사용 가능 | 39 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 최근 10,000개 블록의 과거 상태 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 데이터 최신성 | 알 수 없음 | [Base](https://docs.blockvectra.com/en/guides/base/) |
| [bsc_mainnet RPC 및 Data API](https://blockvectra.com/ko/chains/bsc_mainnet/) | bsc_mainnet | 56 | — | `https://api.blockvectra.com/v1/bsc_mainnet/public` | 미지원 | 사용 가능 | 25 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 최근 100개 블록의 과거 상태 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 데이터 최신성 | 알 수 없음 | 알 수 없음 |
| [Ethereum RPC 및 Data API](https://blockvectra.com/ko/chains/eth_mainnet/) | eth_mainnet | 1 | ✓ | `https://api.blockvectra.com/v1/eth_mainnet/public` | 미지원 | 사용 가능 | 38 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 최근 250,000개 블록의 과거 상태 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 데이터 최신성 | 알 수 없음 | 알 수 없음 |
| [eth_sepolia RPC 및 Data API](https://blockvectra.com/ko/chains/eth_sepolia/) | eth_sepolia | 11155111 | — | `https://api.blockvectra.com/v1/eth_sepolia/public` | 미지원 | 사용 가능 | 29 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 알 수 없음 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 데이터 최신성 | 알 수 없음 | 알 수 없음 |
| [HyperEVM RPC 및 Data API](https://blockvectra.com/ko/chains/hyperevm_mainnet/) | hyperevm_mainnet | 999 | — | `https://api.blockvectra.com/v1/hyperevm_mainnet/public` | 미지원 | 사용 가능 | 24 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 미지원 | 미지원 | 알 수 없음 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 잔액, 보유자, NFT, 데이터 최신성 | 알 수 없음 | [HyperEVM backfill and polling](https://docs.blockvectra.com/en/guides/hyperevm-backfill/) |
| [polygon_mainnet RPC 및 Data API](https://blockvectra.com/ko/chains/polygon_mainnet/) | polygon_mainnet | 137 | ✓ | `https://api.blockvectra.com/v1/polygon_mainnet/public` | 미지원 | 사용 가능 | 43 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 최근 126개 블록의 과거 상태 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 데이터 최신성 | 알 수 없음 | 알 수 없음 |
| [Robinhood Chain RPC 및 Data API](https://blockvectra.com/ko/chains/robinhood_mainnet/) | robinhood_mainnet | 4663 | ✓ | `https://api.blockvectra.com/v1/robinhood_mainnet/public` | 지원 (newHeads, logs) | 사용 가능 | 43 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 최근 900개 블록의 과거 상태 | 1,000개 블록 | 블록, 트랜잭션, 주소 트랜잭션, 전송, 토큰 메타데이터, 잔액, 보유자, NFT, DEX 스왑, DEX 가격, 토큰화 주식, 트레이스, 데이터 최신성 | 알 수 없음 | [Robinhood Chain](https://docs.blockvectra.com/en/guides/robinhood-chain/), [Stock token multiplier](https://docs.blockvectra.com/en/guides/stock-token-multiplier/), [Tokenized stocks](https://docs.blockvectra.com/en/guides/stocks/) |
| [robinhood_testnet RPC](https://blockvectra.com/ko/chains/robinhood_testnet/) | robinhood_testnet | 46630 | ✓ | `https://api.blockvectra.com/v1/robinhood_testnet/public` | 지원 (newHeads, logs) | 아직 제공되지 않음 | 43 | [지원 · 확인 수 1–1 (기본값 1)](https://blockvectra.com/ko/webhooks/), [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/) | 지원 | 지원 | 최근 1,023개 블록의 과거 상태 | 1,000개 블록 | 미지원 | 알 수 없음 | [Testnet faucet](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/), [Robinhood Chain Testnet starter](https://docs.blockvectra.com/en/guides/robinhood-testnet-starter/) |

## API 키를 받은 후

### arb_mainnet

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### base_mainnet

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### bsc_mainnet

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### Ethereum

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### eth_sepolia

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### HyperEVM

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### polygon_mainnet

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### Robinhood Chain

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### Data API

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

[Data API](https://docs.blockvectra.com/en/api/data/)

#### WebSocket

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

[WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

### robinhood_testnet

#### eth_getLogs

```bash
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\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/en/guides/getlogs-block-range/)

#### WebSocket

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

[WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/)

[Webhook 구독 만들기](https://blockvectra.com/ko/webhooks/) · [Webhook 구독 만들기](https://docs.blockvectra.com/en/guides/webhook-push/) · [사용량과 CU](https://console.blockvectra.com/usage/) · [충전](https://console.blockvectra.com/billing/)

**HyperEVM**
HyperEVM 블록에는 HyperCore 시스템 트랜잭션(발신 주소 0x2222…2222 또는 0x20…, gasPrice 0)이 포함됩니다.
이 체인에서는 아직 트랜잭션 전송을 지원하지 않습니다(`eth_sendRawTransaction`은 `-32601` `method_not_allowed` 반환). 읽기 메서드는 정상적으로 사용할 수 있습니다.

[실시간 상태 보기 →](https://blockvectra.com/ko/status/)

이 페이지의 모든 예제는 `robinhood_mainnet`을 사용합니다.

> **팁**: 위의 매트릭스에서 예제의 서비스, 메서드 및 이력 윈도우를 지원하는 체인을 선택한 다음 `robinhood_mainnet`을 해당 `{chain}`으로 바꾸세요. 동일한 API key가 지원되는 모든 체인에서 작동합니다.

### 기타 인증 옵션 및 언어별 예제

JSON-RPC 엔드포인트는 체인별로 범위가 지정됩니다: URL 경로에 키를 포함하는 `POST /v1/{chain}/{api_key}` 또는 `x-api-key` 헤더에 키를 포함하는 `POST /v1/{chain}`. `{chain}`은 Data API에서도 사용하는 체인 이름입니다. Robinhood Chain의 경우 `robinhood_mainnet`이므로 이 페이지의 엔드포인트는 `https://api.blockvectra.com/v1/robinhood_mainnet`입니다. HTTP를 통해 `eth_subscribe`를 호출하면 `-32601`이 반환됩니다. WebSocket 구독은 [지원 체인](https://docs.blockvectra.com/en/chains/)에 체인별로 나열되어 있습니다. API는 `Access-Control-Allow-Origin: *`를 전송하지만, API key를 비밀로 유지하고 브라우저 클라이언트 측 코드가 아닌 백엔드 서비스에서 요청을 보내야 합니다.

키는 세 가지 방법 중 하나로 전달할 수 있습니다: URL 경로(`POST /v1/{chain}/{api_key}`, 경로의 키만 사용하고 두 헤더는 무시), `x-api-key` 헤더, 또는 `Authorization: Bearer <api_key>` 헤더.

#### URL 경로에 키 전달

**cURL**

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


  **TypeScript**

```ts
import { createPublicClient, http } from "viem";

const key = process.env.BLOCKVECTRA_API_KEY!;
const client = createPublicClient({
  transport: http(`https://api.blockvectra.com/v1/robinhood_mainnet/${key}`),
});

console.log(await client.getBlockNumber());

// Run with: npx tsx example.mts
```

Complete starter template: [blockvectra/multichain-viem](https://github.com/blockvectra/multichain-viem)


  **Python**

```python
import os

from web3 import Web3

w3 = Web3(Web3.HTTPProvider("https://api.blockvectra.com/v1/robinhood_mainnet/" + os.environ["BLOCKVECTRA_API_KEY"]))
print(w3.eth.block_number)
```


  **Go**

```go
// Run with: go mod init example && go get github.com/ethereum/go-ethereum && go mod tidy && go run .
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/ethereum/go-ethereum/ethclient"
)

func main() {
	client, err := ethclient.Dial("https://api.blockvectra.com/v1/robinhood_mainnet/" + os.Getenv("BLOCKVECTRA_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}
	number, err := client.BlockNumber(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(number)
}
```


  **Rust**

```toml
[dependencies]
alloy = { version = "1", features = ["provider-http", "rpc-types"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

```rust
use alloy::providers::{Provider, ProviderBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("BLOCKVECTRA_API_KEY")?;
    let url = format!("https://api.blockvectra.com/v1/robinhood_mainnet/{key}");
    let provider = ProviderBuilder::new().connect_http(url.parse()?);
    println!("{}", provider.get_block_number().await?);
    Ok(())
}
```


#### 요청 헤더에 키 전달

**cURL**

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


  **TypeScript**

```ts
import { createPublicClient, http } from "viem";

const key = process.env.BLOCKVECTRA_API_KEY!;
const client = createPublicClient({
  transport: http("https://api.blockvectra.com/v1/robinhood_mainnet", {
    fetchOptions: { headers: { "x-api-key": key } },
  }),
});

console.log(await client.getBlockNumber());

// Run with: npx tsx example.mts
```


  **Python**

```python
import os

from web3 import Web3

key = os.environ["BLOCKVECTRA_API_KEY"]
# request_kwargs replaces the provider's default headers entirely, so
# Content-Type must be repeated here or the server can't parse the body.
headers = {"Content-Type": "application/json", "x-api-key": key}
w3 = Web3(Web3.HTTPProvider("https://api.blockvectra.com/v1/robinhood_mainnet", request_kwargs={"headers": headers}))
print(w3.eth.block_number)
```


  **Go**

```go
// Run with: go mod init example && go get github.com/ethereum/go-ethereum && go mod tidy && go run .
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/ethereum/go-ethereum/ethclient"
	"github.com/ethereum/go-ethereum/rpc"
)

func main() {
	ctx := context.Background()
	c, err := rpc.DialOptions(ctx, "https://api.blockvectra.com/v1/robinhood_mainnet", rpc.WithHeader("x-api-key", os.Getenv("BLOCKVECTRA_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	number, err := ethclient.NewClient(c).BlockNumber(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(number)
}
```


  **Rust**

```toml
[dependencies]
alloy = { version = "1", features = ["provider-http", "rpc-types"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
reqwest = "0.13"
```

```rust
use alloy::providers::{Provider, ProviderBuilder};
use alloy::rpc::client::RpcClient;
use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("BLOCKVECTRA_API_KEY")?;

    let mut headers = HeaderMap::new();
    headers.insert("x-api-key", HeaderValue::from_str(&key)?);
    let http_client = reqwest::Client::builder().default_headers(headers).build()?;

    let rpc_client = RpcClient::new_http_with_client(http_client, "https://api.blockvectra.com/v1/robinhood_mainnet".parse()?);
    let provider = ProviderBuilder::new().connect_client(rpc_client);

    println!("{}", provider.get_block_number().await?);
    Ok(())
}
```


> **No trailing slash**
>
> 헤더에 키를 전달할 때 `https://api.blockvectra.com/v1/robinhood_mainnet`를 표시된 그대로 호출하세요: URL은 후행 슬래시 **없이** 체인 이름으로 끝납니다. JSON-RPC는 `/v1/{chain}` 및 `/v1/{chain}/{api_key}`에서만 제공됩니다. 후행 슬래시(`/v1/{chain}/` 등)가 있거나 체인 세그먼트가 없는 요청(`/v1` 또는 `/v1/` 등)은 빈 본문과 함께 `404`를 반환합니다.


`Authorization: Bearer <api_key>` 헤더도 사용할 수 있습니다. `POST /v1/{chain}`에서 비어 있지 않은 `x-api-key`는 Bearer보다 우선하며, Bearer는 `x-api-key`가 없거나 비어 있을 때만 사용됩니다. 경로 형태는 두 헤더를 모두 무시합니다.

### 배치 호출

배열을 전송하여 하나의 요청으로 여러 번의 호출을 수행합니다(배치당 최대 100회). 각 API key에는 CU 버킷(`cu_per_sec` 리필, `burst_cu` 용량 — 기본 속도 400 CU/s, 버스트 용량 1,600 CU; 콘솔 Keys 테이블에서 키별로 표시됨)이 있습니다. 총 CU가 키의 버스트 용량을 초과하는 단일 요청(전체 JSON-RPC 배치 포함)은 배치당 100회 호출 제한 내에 있더라도 `-32022 request_exceeds_burst`로 거부되므로 더 작은 배치로 분할하세요. 이 예제는 한 번의 왕복으로 체인 ID와 계정 잔액을 읽습니다:

**cURL**

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


  **TypeScript**

```ts
import { createPublicClient, http } from "viem";

const key = process.env.BLOCKVECTRA_API_KEY!;
const client = createPublicClient({
  transport: http("https://api.blockvectra.com/v1/robinhood_mainnet", {
    batch: true,
    fetchOptions: { headers: { "x-api-key": key } },
  }),
});

// viem coalesces concurrent requests into a single JSON-RPC batch.
const [chainId, balance] = await Promise.all([
  client.getChainId(),
  client.getBalance({ address: "0x1111111111111111111111111111111111111111" }),
]);
console.log(chainId, balance);

// Run with: npx tsx example.mts
```


  **Python**

```python
import os

from web3 import Web3

key = os.environ["BLOCKVECTRA_API_KEY"]
headers = {"Content-Type": "application/json", "x-api-key": key}
w3 = Web3(Web3.HTTPProvider("https://api.blockvectra.com/v1/robinhood_mainnet", request_kwargs={"headers": headers}))

with w3.batch_requests() as batch:
    batch.add(w3.eth.chain_id)
    batch.add(w3.eth.get_balance("0x1111111111111111111111111111111111111111"))
    chain_id, balance = batch.execute()

print(chain_id, balance)
```


  **Go**

```go
// Run with: go mod init example && go get github.com/ethereum/go-ethereum && go mod tidy && go run .
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/ethereum/go-ethereum/rpc"
)

func main() {
	ctx := context.Background()
	c, err := rpc.DialOptions(ctx, "https://api.blockvectra.com/v1/robinhood_mainnet", rpc.WithHeader("x-api-key", os.Getenv("BLOCKVECTRA_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}

	var chainID, balance string
	calls := []rpc.BatchElem{
		{Method: "eth_chainId", Result: &chainID},
		{Method: "eth_getBalance", Args: []any{"0x1111111111111111111111111111111111111111", "latest"}, Result: &balance},
	}
	if err := c.BatchCallContext(ctx, calls); err != nil {
		log.Fatal(err)
	}
	for _, call := range calls {
		if call.Error != nil {
			log.Fatal(call.Error)
		}
	}
	fmt.Println(chainID, balance)
}
```


  **Rust**

```toml
[dependencies]
alloy = { version = "1", features = ["provider-http", "rpc-types"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
reqwest = "0.13"
```

```rust
use alloy::primitives::{Address, U256};
use alloy::rpc::client::RpcClient;
use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("BLOCKVECTRA_API_KEY")?;

    let mut headers = HeaderMap::new();
    headers.insert("x-api-key", HeaderValue::from_str(&key)?);
    let http_client = reqwest::Client::builder().default_headers(headers).build()?;
    let rpc_client = RpcClient::new_http_with_client(http_client, "https://api.blockvectra.com/v1/robinhood_mainnet".parse()?);

    let address: Address = "0x1111111111111111111111111111111111111111".parse()?;
    let mut batch = rpc_client.new_batch();
    let chain_id = batch.add_call::<_, U256>("eth_chainId", &())?;
    let balance = batch.add_call::<_, U256>("eth_getBalance", &(address, "latest"))?;
    batch.send().await?;

    println!("{} {}", chain_id.await?, balance.await?);
    Ok(())
}
```


응답은 요청과 동일한 순서로 `id`와 일치하는 배열로 반환됩니다.

서버가 전체 배치를 거부하는 경우(잔액 부족, 속도 제한, 버스트 용량 초과 또는 대형 배치 — 아래 [일반적인 오류](#common-errors) 참조) 배열 대신 단일 JSON-RPC 오류 객체를 반환합니다. viem의 `batch: true` 모드는 이를 불투명한 `UnknownRpcError`로 표시하므로 실제 오류를 확인하려면 단일 호출로 다시 시도하세요.

### CU 과금 이해하기

과금되는 모든 호출은 \*\*연산 단위(CU)\*\*를 소비합니다: `eth_blockNumber`나 `eth_chainId` 같은 저렴한 호출은 비용이 가장 적게 들고, `eth_getBlockByNumber` 같은 일반적인 읽기는 조금 더 들며, `eth_call`이나 `eth_getLogs` 같은 무거운 호출은 더 많은 비용이 들고, 실행 추적 메서드(`debug_traceTransaction` 등)는 가장 많은 비용이 듭니다. 사용량은 계정별로 시간당 정산 주기마다 청구되며, 정수 청구 단위(1단위 = 1,000 CU)로 내림 처리되고 나머지는 다음 주기로 이월됩니다(여러 주기에 걸친 총 청구액은 `floor(총 CU / 1,000)` 청구 단위입니다). 정산은 주기 종료 약 15분 후에 실행됩니다. 예: 이월 508 CU + 사용 2557 CU = 3065 CU이면 3 청구 단위가 청구되고 65 CU가 다음 주기로 이월됩니다. 현재 요율은 [요금 페이지](https://blockvectra.com/en/pricing/)를 참조하세요.

전체 메서드별 가중치 표와 오류 코드는 [API 레퍼런스 → JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/)에 있습니다 — 이 페이지에서는 요청 형식만 다룹니다.

#### 일반적인 오류

| 요청 상황                                                                                                                                                                 | 반환 내용                                                                     | 조치 방법                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 알 수 없거나 아직 공개되지 않은 체인                                                                                                                                                 | `error.data.reason: "unknown_chain"` JSON 본문과 함께 HTTP `404`               | URL의 체인 이름 확인                                                                                                                                                                      |
| 체인 세그먼트가 없는 요청 (`/v1` 또는 `/v1/` 등)                                                                                                                                    | 빈 본문과 함께 HTTP `404`                                                       | URL에 체인 이름 포함 (`/v1/{chain}`)                                                                                                                                                      |
| API key 누락, 알 수 없거나 비활성화됨                                                                                                                                             | HTTP `401`, JSON-RPC 코드 `-32024` (`missing_api_key` 또는 `invalid_api_key`) | 유효하고 활성화된 API key 사용 (새로 생성되거나 교체된 키는 약 5초 내에 모든 인스턴스에 적용됩니다. 이 시간 동안 401 `invalid_api_key`를 반환하거나 과금 상태를 확인할 수 없을 때 503 `-32021`(`Retry-After` 포함)을 반환할 수 있으므로 잠시 기다린 후 다시 시도하세요) |
| 잔액이 0 이하임                                                                                                                                                             | HTTP `402`, JSON-RPC 코드 `-32020`                                          | 잔액을 충전하거나 무료 충전 주기 대기                                                                                                                                                              |
| 요청 속도가 너무 빠름 (속도 제한 또는 일시적 과부하)                                                                                                                                       | HTTP `429` (또는 `200`), JSON-RPC 코드 `-32005`                               | 나중에 다시 시도 (`Retry-After`가 있는 경우 준수)                                                                                                                                                |
| 단일 요청 또는 배치가 키 버스트 용량을 초과함 (`burst_cu`, 기본 1,600 CU; 기본 속도 400 CU/s), 또는 무료 플랜 배치가 초당 호출 한도를 초과함 (초당 25회 호출)                                                                                                  | HTTP `429`, JSON-RPC 코드 `-32022` (`request_exceeds_burst`)                | 요청을 더 작은 배치로 분할 (전송된 상태로는 성공할 수 없음)                                                                                                                                                |
| 업스트림 노드를 일시적으로 사용할 수 없음                                                                                                                                               | HTTP `200`, JSON-RPC 코드 `-32603` (`upstream unavailable`), 과금되지 않음        | 요청 재시도                                                                                                                                                                             |
| 해당 체인의 상태 윈도우를 벗어난 과거 상태 (`GET /v1/chains`의 `state_window_blocks` 참조)                                                                                                 | HTTP `200`, JSON-RPC 코드 `-32011`, 과금되지 않음                                 | 더 최근 블록 쿼리                                                                                                                                                                         |
| 트랜잭션 또는 블록을 찾을 수 없거나 응답이 너무 큼. 이더리움에서는 최근 윈도우 밖의 블록/영수증/로그 쿼리도 -32000 "old data not available due to pruning"을 반환함 (과금되지 않음, [지원 체인 → 이더리움](https://docs.blockvectra.com/en/chains/#ethereum) 참조) | HTTP `200`, JSON-RPC 코드 `-32000`                                          | 요청 수정 (해시 또는 블록 번호 확인, 잘못된 형식의 추적 해시는 트랜잭션을 찾을 수 없음을 반환함)                                                                                                                          |
| 트레이서가 허용되지 않거나 트레이스 타임아웃이 허용되지 않음 (`debug_trace` 호출)                                                                                                                  | HTTP `200`, JSON-RPC 코드 `-32602`, 과금되지 않음                                 | 허용된 기본 트레이서(`callTracer`, `flatCallTracer`, `prestateTracer`, `4byteTracer`, `noopTracer` 사용 또는 생략) 및 타임아웃 ≤ 30초 사용                                                                |
| 체인의 메서드 목록에서 허용하지 않는 메서드 ([지원 체인](https://docs.blockvectra.com/en/chains/) 참조)                                                                                                                    | HTTP `200`, JSON-RPC 코드 `-32601`, 과금되지 않음                                 | 체인에서 허용하는 메서드만 호출                                                                                                                                                                  |
| 잘못된 형식의 JSON 본문                                                                                                                                                       | HTTP `200`, JSON-RPC 코드 `-32700`, 과금되지 않음                                 | 요청 JSON 문법 수정                                                                                                                                                                      |
| 한 배치에 100회를 초과하는 호출                                                                                                                                                   | HTTP `200`, JSON-RPC 코드 `-32600` (`batch too large`), 과금되지 않음             | 배치를 최대 100회 호출로 분할                                                                                                                                                                 |

위의 거부 사례는 과금되지 않습니다. 응답을 받는 모든 수락된 호출은 메서드에 공시된 CU 가중치로 청구됩니다. 오류 코드 표에는 과금되지 않는 사례가 나열되어 있습니다([오류 코드](https://docs.blockvectra.com/en/api/json-rpc/#error-codes)의 Billed 열 참조).

### Data API 호출

Data API는 읽기 전용 체인 데이터(블록, 트랜잭션, 잔액, 보유자, DEX 활동 등)를 REST/JSON으로 제공합니다. `GET https://api.blockvectra.com/v1/data/chains`를 제외한 모든 경로는 체인 식별자로 접두사가 붙습니다: `robinhood_mainnet`은 아래의 모든 경로에서 사용된 체인 식별자(`/chains` 및 `meta`에서 반환되는 `chain` 필드)입니다. `GET https://api.blockvectra.com/v1/data/chains`는 공개 체인만 나열하며 `{"data": [...]}`만 반환합니다(`meta` 및 `next_cursor` 없음). 요청은 연산 단위(CU)로 계량되고 청구되며, 2xx 성공 응답만 과금됩니다.

모든 요청에는 JSON-RPC와 동일한 API key가 필요합니다 — `x-api-key` 헤더로 전달하세요. 체인 범위의 모든 성공 응답은 동일한 외층 구조를 사용합니다: `data`(페이로드), `next_cursor`(불투명 문자열, 다른 페이지가 있을 때만 존재 — 그렇지 않으면 키가 완전히 생략되며 결코 `null`이 아님), 그리고 `meta`(`chain`, `chain_slug`(`chain`의 대문자 형태), `chain_external_id`, `as_of_block`, `safe_block`, `finalized_block`, `coverage`, `refreshed_at`; `refreshed_at`은 `null`일 수 있으며 이는 데이터 업데이트 시간을 알 수 없어 오래된 것으로 취급해야 함을 의미합니다 — 블록 기반 엔드포인트는 항상 값을 반환함). 오류 응답은 일반적으로 `{"error":{"code","message"}}`를 포함합니다 — `409 not_indexed_yet`은 `indexed_through`(인덱싱된 가장 높은 블록)를 추가합니다. 알 수 없거나 공개되지 않은 체인은 `error.code` `not_found`와 함께 HTTP `404`를 반환합니다(과금되지 않음, 체인 이름은 정확한 소문자 슬러그여야 함). 누락되거나 알 수 없거나 비활성화된 API key는 `error.code` `missing_api_key` 또는 `invalid_api_key`와 함께 HTTP `401`을 반환합니다. 속도 제한된 요청은 HTTP `429`(`error.code` `rate_limited`, `data.reason: "key_rate_limit"`)를 반환하고, 잔액이 소진되면 HTTP `402`(`error.code` `insufficient_balance`)를 반환합니다. 둘 다 과금되지 않습니다. 2^53을 초과할 수 있는 값(잔액, 토큰 금액)은 JSON 숫자가 아닌 10진수 문자열입니다.

**블록 번호로 블록 조회:**

**cURL**

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


  **TypeScript**

```ts
const res = await fetch("https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701", {
  headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
});
const body = await res.json();
console.log(body);

// Run with: npx tsx example.mts
```


  **Python**

```python
import os, requests

res = requests.get(
    "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701",
    headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
)
print(res.json())
```


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

인덱싱된 헤드(`as_of_block`)보다 큰 번호는 가장 높은 인덱싱된 블록을 알려주는 `indexed_through`와 함께 `409`(`error.code: "not_indexed_yet"`)를 반환합니다 — 아직 데이터가 없으므로 나중에 다시 시도하세요. 체인의 커버리지 이력(`coverage.from_block`)보다 완전히 이전인 블록 번호는 `422`(`error.code: "no_coverage"`)를 반환합니다. 커버리지 내에서 유효한 행이 없는(인덱싱된 적이 없거나 reorg로 롤백된) `as_of_block` 이하의 번호는 `404`(`error.code: "not_found"`)입니다.

**데이터 최신성 확인** (추적되는 각 데이터셋이 체인 헤드보다 얼마나 지연되는지 확인 — 상태 페이지나 쿼리를 신뢰하기 전 사전 확인에 유용):

**cURL**

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


  **TypeScript**

```ts
const res = await fetch("https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness", {
  headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
});
const body = await res.json();
console.log(body);

// Run with: npx tsx example.mts
```


  **Python**

```python
import os, requests

res = requests.get(
    "https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness",
    headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
)
print(res.json())
```


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

*(요약됨: 응답에는 데이터셋당 하나의 행이 포함되며, 여기에는 `blocks` 행만 표시되었습니다. `traces` 행에는 `coverage_from_block`, `coverage_to_block` 및 `coverage_complete`도 포함됩니다.)*

이 체인에 대해 최신성 데이터를 일시적으로 사용할 수 없는 경우 부분 결과 대신 `503`(`error.code: "unavailable"`)을 반환합니다. 응답에는 `Retry-After` 헤더(초 단위)가 포함되어 있으므로 최소한 그 시간만큼 기다린 후 다시 시도하세요.

**주소의 ERC-20 잔액 조회** (토큰별로 정렬된 0이 아닌 잔액 스냅샷):

**cURL**

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


  **TypeScript**

```ts
const res = await fetch(
  "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances",
  { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! } },
);
const body = await res.json();
console.log(body);

// Run with: npx tsx example.mts
```


  **Python**

```python
import os, requests

res = requests.get(
    "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances",
    headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
)
print(res.json())
```


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

0이 아닌 잔액이 없는 주소라도 결코 `404`가 아닌 `data: []`와 함께 `200`을 반환합니다. `?limit=`(기본값 50, 최대 500)과 반환된 `next_cursor`를 전달하여 추가 페이지를 확인하세요.

블록, 트랜잭션, 주소, 토큰, NFT, DEX, 토큰화 주식 등 전체 엔드포인트 지원 범위는 [API 레퍼런스 → Data API](https://docs.blockvectra.com/en/api/data/)에서 확인할 수 있습니다.

### 추가 리소스

* [API 레퍼런스 → JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/) — 메서드, CU 가중치, 오류 코드
* [전체 JSON-RPC 레퍼런스](https://docs.blockvectra.com/en/api/json-rpc/reference/) — 지원되는 모든 메서드의 전체 사양, 파라미터 및 반환 스키마
* [API 레퍼런스 → Data API](https://docs.blockvectra.com/en/api/data/) — 체인 데이터를 위한 REST 엔드포인트
* [데이터셋](https://docs.blockvectra.com/en/datasets/) — 지원 체인 전반의 파생 데이터셋
* [가이드](https://docs.blockvectra.com/en/guides/) — API 연동, CU 관리 및 멀티체인 워크플로를 위한 실용적인 가이드
* [지원 체인](https://docs.blockvectra.com/en/chains/) — 네트워크 식별자 및 엔드포인트 URL

## 자주 묻는 질문

### 어떤 체인을 지원하나요?

9개 체인을 지원합니다: Arbitrum One, Base, BNB Smart Chain, Ethereum, Ethereum Sepolia, HyperEVM, Polygon, Robinhood Chain, Robinhood Chain Testnet. 목록은 GET /v1/chains를 따르며 새로운 체인이 출시되면 업데이트됩니다. 실시간 상태는 [상태 페이지](https://blockvectra.com/ko/status/)를 참조하십시오. [지원 체인 목록 보기](https://blockvectra.com/ko/chains/)

### WebSocket을 지원하나요?

HTTP를 통해 eth_subscribe를 호출하면 -32601이 반환됩니다. /v1/chains에서 ws가 true인 체인에서는 WebSocket을 통해 eth_subscribe를 이용할 수 있습니다. 그렇지 않은 경우에는 eth_getLogs 폴링을 사용하십시오. [지원 체인 목록 보기](https://blockvectra.com/ko/chains/)

### 과거 상태 및 트레이스를 조회할 수 있나요?

네, 가능하지만 체인마다 다릅니다. 과거 상태 보관 기간은 /v1/chains의 state_window_blocks 필드에 명시되어 있습니다(null은 전체 기록을 의미). 트레이스 제공 여부는 해당 체인의 methods.allow에 debug_trace 계열 메서드(debug_traceTransaction 등)가 포함되어 있는지에 따릅니다. 단일 eth_getLogs 요청의 최대 블록 범위는 max_logs_block_range입니다. [체인 디렉터리 및 체인별 파라미터 보기](https://blockvectra.com/ko/chains/)

### 단일 API 키를 모든 체인에서 사용할 수 있나요?

네, 가능합니다. 단일 API 키로 지원되는 모든 체인의 JSON-RPC와 이를 제공하는 체인의 Data API를 이용할 수 있습니다. API 키는 특정 체인이 아닌 계정에 귀속됩니다. [멀티체인 이용 가이드 읽기](https://docs.blockvectra.com/en/guides/one-key-many-chains/)