# Robinhood Chain 연동 가이드: RPC 클라이언트, 컨트랙트 배포 및 이벤트 리스닝

> Source: https://docs.blockvectra.com/ko/guides/robinhood-chain/

공개 연결 확인과 인증된 읽기에는 Robinhood Chain RPC를, 메인넷에서 지원되는 데이터셋 조회에는 Data API를 사용하세요. 개발자와 AI 에이전트는 동일한 엔드포인트를 사용합니다. 메인넷과 테스트넷 요청은 분리하여 관리해야 합니다.

## 이 가이드에서 다루는 작업

* viem 또는 ethers를 사용해 공개 읽기로 [Robinhood Chain RPC 확인](#connect-with-viem-or-ethers) 후 인증된 메서드에 API key 사용.
* 테스트넷 작업을 실행하기 전에 `eth_chainId`를 읽어 [테스트넷 RPC 연결 확인](#testnet).
* 데이터셋 지원 여부를 확인한 후 메인넷 Data API로 [토큰화 주식 활동 조회](#tokenized-stock-data)(해당 지표는 주식 가격이 아닌 온체인 활동을 나타냄).

## RPC 및 WebSocket 접근

* **공개 RPC URL**: API key가 필요 없는 엔드포인트, 지원되는 공개 메서드 및 속도 제한은 [Robinhood Chain 메인넷 페이지](https://blockvectra.com/en/chains/robinhood_mainnet/) 또는 [테스트넷 페이지](https://blockvectra.com/en/chains/robinhood_testnet/)에서 확인할 수 있습니다.
* **API key를 사용하는 JSON-RPC**: 아래 엔드포인트와 curl 예제를 사용하세요. 로그 조회는 [eth\_getLogs 메서드 레퍼런스](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) 및 [블록 범위 한도 가이드](https://docs.blockvectra.com/en/guides/getlogs-block-range/)를 참조하세요.
* **API key를 사용하는 WebSocket**: 아래 WebSocket 엔드포인트를 사용하고 `newHeads` 및 `logs` 구독은 [WebSocket 구독 가이드](https://docs.blockvectra.com/en/guides/websocket-subscriptions/)를 따르세요. 공개 RPC 접근은 HTTP JSON-RPC만 지원되며, WebSocket 연결에는 API key가 필요합니다.

## 네트워크 정보 및 엔드포인트

Robinhood Chain에 대한 모든 요청은 URL 경로에서 슬러그 `robinhood_mainnet`을 사용하여 대상 네트워크를 명시적으로 식별합니다. JSON-RPC는 URL 경로 기반 인증과 요청 헤더 인증(`x-api-key`)을 모두 지원하며, Data API는 `/v1/data/robinhood_mainnet/` 아래에서 REST 엔드포인트를 제공합니다.

아래 파라미터와 엔드포인트는 현재 활성화된 네트워크 파라미터를 반영합니다:

| 파라미터 / 엔드포인트 | 값 / 템플릿 | 인증 방식 |
|---|---|---|
| Chain ID (EIP-155) | `4663` | — |
| JSON-RPC (경로 키) | `POST https://api.blockvectra.com/v1/robinhood_mainnet/{api_key}` | URL 경로에 API key 전달 |
| JSON-RPC (헤더 키) | `POST https://api.blockvectra.com/v1/robinhood_mainnet` | x-api-key: {api_key} 헤더 전달 |
| WebSocket (경로 키) | `wss://api.blockvectra.com/v1/robinhood_mainnet/{api_key}` | URL 경로에 API key 전달 |
| WebSocket (헤더 키) | `wss://api.blockvectra.com/v1/robinhood_mainnet` | x-api-key: {api_key} 또는 Authorization: Bearer {api_key} 헤더 전달 |
| WebSocket 구독 유형 | `newHeads, logs` | — |
| Data API 기본 URL | `GET https://api.blockvectra.com/v1/data/robinhood_mainnet/…` | x-api-key: {api_key} 헤더 전달 |
| 퍼블릭 상태 엔드포인트 | `GET https://api.blockvectra.com/v1/status` | 인증 불필요 (퍼블릭) |

## viem 또는 ethers로 연결하기

개발자와 AI 에이전트는 동일한 서버 사이드 설정을 사용할 수 있습니다. Node.js 24 이상, viem 2 또는 ethers 6을 사용하고 공개 읽기부터 시작하세요. API key가 필요한 메서드와 WebSocket에는 환경 변수에 `BLOCKVECTRA_API_KEY`를 안전하게 설정하세요. API key 및 API key가 포함된 RPC URL은 브라우저 코드, 로그, 버전 관리 시스템에 노출되지 않도록 주의해야 합니다.

이 코드를 `network.mjs`로 저장하세요. 테스트넷에서 먼저 시작하고, 메인넷으로 전환하려면 `BLOCKVECTRA_CHAIN=robinhood_mainnet`을 설정하세요. 이 스크립트는 [GET /v1/chains](https://api.blockvectra.com/v1/chains)에서 `chain_id`와 메서드 정책을 읽어옵니다. API key 없는 공개 읽기의 경우 카탈로그의 `public.url`을 사용하고 `public.methods`에 나열된 메서드만 호출해야 합니다. 공개 HTTP가 가능하다고 해서 WebSocket 접근까지 가능한 것은 아닙니다.

```js
const chainSlug = process.env.BLOCKVECTRA_CHAIN ?? 'robinhood_testnet';
const key = process.env.BLOCKVECTRA_API_KEY;
const catalogUrl = 'https://api.blockvectra.com/v1/chains';
const response = await fetch(catalogUrl, { signal: AbortSignal.timeout(15_000) });
if (!response.ok) throw new Error(`Chains HTTP ${response.status}`);
const catalog = await response.json();
export const chainInfo = catalog.chains.find(item => item.chain === chainSlug);
if (!chainInfo || !Number.isSafeInteger(chainInfo.chain_id) || chainInfo.chain_id <= 0) {
  throw new Error('Missing chain or chain_id');
}
export function allows(method) {
  const matches = pattern => pattern.endsWith('*')
    ? method.startsWith(pattern.slice(0, -1)) : pattern === method;
  if (!key) return (chainInfo.public?.methods ?? []).some(matches);
  return (chainInfo.methods?.allow ?? []).some(matches)
    && !(chainInfo.methods?.deny ?? []).some(matches);
}
if (!allows('eth_chainId')) throw new Error('eth_chainId is unavailable');
export const rpcUrl = key
  ? new URL(`./${chainSlug}/${encodeURIComponent(key)}`, catalogUrl).href
  : chainInfo.public?.url;
if (!rpcUrl) throw new Error('Public RPC is unavailable; set BLOCKVECTRA_API_KEY');
```

`viem-client.mjs`로 저장하고 `npm install viem@2`로 설치한 다음 `node viem-client.mjs`를 실행하세요.

```js
import { createPublicClient, defineChain, http } from 'viem';
import { chainInfo, rpcUrl } from './network.mjs';

export const chain = defineChain({
  id: chainInfo.chain_id,
  name: chainInfo.name,
  nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
  rpcUrls: { default: { http: [rpcUrl] } },
});
export const client = createPublicClient({ chain, transport: http(rpcUrl) });
if (await client.getChainId() !== chain.id) throw new Error('RPC chain ID mismatch');
console.log(await client.getBlockNumber());
```

ethers를 사용하는 경우 `ethers-client.mjs`로 저장하고 `npm install ethers@6`으로 설치한 다음 `node ethers-client.mjs`를 실행하세요.

```js
import { JsonRpcProvider } from 'ethers';
import { chainInfo, rpcUrl } from './network.mjs';

const provider = new JsonRpcProvider(rpcUrl, chainInfo.chain_id, { batchMaxCount: 1 });
const network = await provider.getNetwork();
if (network.chainId !== BigInt(chainInfo.chain_id)) throw new Error('RPC chain ID mismatch');
console.log(await provider.getBlockNumber());
provider.destroy();
```

## Foundry 또는 Hardhat으로 배포하기

먼저 [테스트넷 수도꼭지(faucet)](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/)에서 배포자 주소로 테스트 ETH를 받으세요. 메인넷 트랜잭션에는 메인넷 ETH가 필요합니다. [공식 네트워크 및 배포 가이드](https://docs.robinhood.com/chain/deploy-smart-contracts/)에 메인넷 및 테스트넷 chain ID가 나열되어 있습니다(접속일: 2026-10-07). 이 페이지의 엔드포인트 표는 `/v1/chains` 데이터를 사용합니다.

`network.mjs`에서 선택한 URL과 chain ID를 내보냅니다. 트랜잭션을 브로드캐스트하기 전에 `methods.allow` 및 `methods.deny`를 기준으로 `eth_sendRawTransaction` 허용 여부를 확인하세요.

```bash
export RPC_URL="$(node --input-type=module -e "import { rpcUrl, allows } from './network.mjs'; if (!allows('eth_sendRawTransaction')) throw new Error('Broadcast unavailable'); console.log(rpcUrl)")"
export CHAIN_ID="$(node --input-type=module -e "import { chainInfo } from './network.mjs'; console.log(chainInfo.chain_id)")"
```

`Hello.sol` 작성, 도구 설정, 트랜잭션 브로드캐스트 및 receipt 확인은 공통 [Foundry 또는 Hardhat 배포 튜토리얼](https://docs.blockvectra.com/en/guides/deploy-contract/)을 계속 진행하세요.

## WebSocket으로 컨트랙트 이벤트 리스닝하기

`watch-logs.mjs`로 저장하고 감시할 배포 컨트랙트 또는 토큰 컨트랙트 주소로 `LOG_ADDRESS`를 설정하세요. `node watch-logs.mjs`를 실행합니다. 이 코드는 `logs`를 구독하기 전에 `/v1/chains`에서 `ws` 및 `subscriptions` 지원 여부를 확인합니다.

```js
import { createPublicClient, webSocket, isAddress } from 'viem';
import { chain } from './viem-client.mjs';
import { chainInfo, rpcUrl } from './network.mjs';

if (!process.env.BLOCKVECTRA_API_KEY) throw new Error('WebSocket requires BLOCKVECTRA_API_KEY');
const address = process.env.LOG_ADDRESS;
if (!chainInfo.ws || !chainInfo.subscriptions?.includes('logs')) {
  throw new Error('WebSocket logs are unavailable; use HTTP backfill or webhook push');
}
if (!address || !isAddress(address)) throw new Error('Set LOG_ADDRESS');
const wsUrl = new URL(rpcUrl);
wsUrl.protocol = 'wss:';
const client = createPublicClient({ chain, transport: webSocket(wsUrl.href) });
const unwatch = client.watchEvent({
  address, poll: false,
  onLogs: logs => console.log(logs),
  onError: error => console.error(error),
});
process.once('SIGINT', () => { unwatch(); process.exit(0); });
```

리스너가 시작된 후, 다른 터미널에서 동일한 배포 환경 변수를 사용하여 `ping()` 트랜잭션을 전송합니다:

```bash
cast send "$CONTRACT_ADDRESS" "ping()" --rpc-url "$RPC_URL" \
  --private-key "$DEPLOYER_PRIVATE_KEY"
```

마지막으로 처리한 블록을 유지하고 `(blockHash, transactionHash, logIndex)` 조합으로 중복을 제거하세요. 재연결 후에는 제한된 범위의 `eth_getLogs` 요청으로 누락된 블록을 백필하고, 블록체인 리오그(reorg) 발생 시 `removed`로 표시된 로그를 조정하세요. 자세한 내용은 [WebSocket 구독](https://docs.blockvectra.com/en/guides/websocket-subscriptions/) 및 [블록 범위 한도](https://docs.blockvectra.com/en/guides/getlogs-block-range/)를 참조하세요.

HTTPS 수신기로 주소 이벤트를 전송받으려면 **GET /v1/push/chains에서 지원 체인**과 확인 수 설정을 확인하고 `x-api-key` 헤더를 사용하세요. 구독 생성, 서명 검증, 중복 제거 및 재생 처리는 [Webhook 푸시 가이드](https://docs.blockvectra.com/en/guides/webhook-push/)를 따르세요. 메인넷 토큰화 주식 활동 조회는 [주식 데이터 가이드](https://docs.blockvectra.com/en/guides/stocks/)를 참조하세요.

## 직접 실행하는 curl 예제

표준 HTTP 클라이언트를 사용하여 즉시 JSON-RPC 호출을 수행할 수 있습니다. `{api_key}`를 실제 BlockVectra API key로 대체하세요:

**eth_chainId (Header)**

`x-api-key` 요청 헤더를 사용하여 EIP-155 체인 ID를 조회합니다:

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


  **eth_blockNumber (Path)**

URL 경로에 API key를 전달하여 최신 블록 번호를 조회합니다:

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


### 응답 구조

응답은 JSON-RPC 2.0 사양을 따릅니다:

* **성공**: `jsonrpc: "2.0"`, 동일한 `id`, 16진수 인코딩된 수량이 담긴 `result` 문자열을 포함하는 봉투를 반환합니다(`eth_chainId`는 16진수 체인 ID 반환, `eth_blockNumber`는 최신 블록 높이 반환).
* **허용되지 않은 메서드**: 네트워크에서 허용되지 않은 메서드를 요청하면 JSON-RPC 오류 코드 `-32601`(`method not available`, 과금되지 않음)을 반환합니다.
* **윈도우 범위 밖 쿼리**: 상태 보존 윈도우보다 이전의 과거 상태를 요청하면 JSON-RPC 오류 코드 `-32011`(과금되지 않음)을 반환합니다.
* **유효하지 않은 파라미터**: 잘못된 형식이나 허용되지 않은 요청 파라미터는 JSON-RPC 오류 코드 `-32602`(과금되지 않음)를 반환합니다.

## 지원 기능 및 메서드 정책

Robinhood Chain에서 지원되는 JSON-RPC 메서드, 로그 블록 범위 한도 및 과거 상태 보존 기간은 `GET /v1/chains`를 통해 동적으로 게시됩니다. 실행 추적(`debug_traceTransaction`을 포함한 `debug_trace*`)은 해당 체인의 메서드 정책에 따라 관리됩니다:

### 네트워크 파라미터 및 호출 제한

- **eth_getLogs 블록 범위**: 요청당 최대 1000개 블록
- **과거 상태 조회 범위**: 최근 900개 블록 (범위를 초과한 조회는 -32011 반환)
- **실행 추적 (debug_trace*)**: 지원됨 (debug_traceTransaction, debug_traceCall, debug_traceBlockByNumber, debug_traceBlockByHash)

체인별 허용 메서드: [지원 체인](https://docs.blockvectra.com/en/chains/)

## 테스트넷

트랜잭션에 필요한 테스트 ETH를 얻으려면 [Robinhood Chain 테스트넷 수도꼭지(faucet) 가이드](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/)를 참조하세요.

Robinhood Chain 테스트넷(체인 ID: 46630)은 `https://api.blockvectra.com/v1/robinhood_testnet` 엔드포인트에서 메인넷과 동일한 API key를 사용하며, `x-api-key` 요청 헤더를 통해 인증합니다.

테스트넷 요청은 메인넷과 동일한 CU 가중치를 적용받으며 동일한 잔액 및 무료 크레딧에서 차감됩니다. Robinhood Chain 테스트넷에서 사용 가능한 JSON-RPC 메서드와 과거 상태 보존 기간은 `GET /v1/chains`를 통해 동적으로 게시됩니다.

API key 없이 테스트넷을 읽고, WebSocket으로 로그를 스트리밍한 후, 동일한 키를 메인넷으로 전환하는 실행 가능한 3단계 스타터는 [Robinhood Chain 테스트넷 스타터 가이드](https://docs.blockvectra.com/en/guides/robinhood-testnet-starter/)를 참조하세요.

```bash
curl -s "https://api.blockvectra.com/v1/robinhood_testnet" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'
```

예상 응답:

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

| 파라미터 / 엔드포인트 | 값 / 템플릿 | 인증 방식 |
|---|---|---|
| Chain ID (EIP-155) | `46630` | — |
| JSON-RPC (경로 키) | `POST https://api.blockvectra.com/v1/robinhood_testnet/{api_key}` | URL 경로에 API key 전달 |
| JSON-RPC (헤더 키) | `POST https://api.blockvectra.com/v1/robinhood_testnet` | x-api-key: {api_key} 헤더 전달 |
| WebSocket (경로 키) | `wss://api.blockvectra.com/v1/robinhood_testnet/{api_key}` | URL 경로에 API key 전달 |
| WebSocket (헤더 키) | `wss://api.blockvectra.com/v1/robinhood_testnet` | x-api-key: {api_key} 또는 Authorization: Bearer {api_key} 헤더 전달 |
| WebSocket 구독 유형 | `newHeads, logs` | — |
| Data API 기본 URL | `아직 지원되지 않음` | — |
| 퍼블릭 상태 엔드포인트 | `GET https://api.blockvectra.com/v1/status` | 인증 불필요 (퍼블릭) |

### 네트워크 파라미터 및 호출 제한

- **eth_getLogs 블록 범위**: 요청당 최대 1000개 블록
- **과거 상태 조회 범위**: 최근 1023개 블록 (범위를 초과한 조회는 -32011 반환)
- **실행 추적 (debug_trace*)**: 지원됨 (debug_traceTransaction, debug_traceCall, debug_traceBlockByNumber, debug_traceBlockByHash)

체인별 허용 메서드: [지원 체인](https://docs.blockvectra.com/en/chains/)

## 토큰화 주식 데이터

Robinhood Chain에서 BlockVectra Data API는 두 개의 엔드포인트를 통해 토큰화 주식에 대한 일일 온체인 지표와 메타데이터를 제공합니다:

* **일일 리더보드 (`GET /v1/data/robinhood_mainnet/stocks`)**: 지정된 UTC 날짜의 토큰화 주식 일일 활동 리더보드로, 전송 활동 내림차순으로 정렬됩니다.
* **단일 토큰화 주식 조회 (`GET /v1/data/robinhood_mainnet/stocks/{token}`)**: 토큰 주소별 토큰 컨트랙트 메타데이터 및 최대 30일간의 최근 일일 지표.

자세한 요청 파라미터, 응답 봉투 구조(`StockDailyListEnvelope` 및 `StockTokenEnvelope`), 페이지네이션 참고 사항 및 CU 소모량 추정치는 [토큰화 주식 가이드](https://docs.blockvectra.com/en/guides/stocks/)를 참조하세요.

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

## 시작하기 및 API Key 발급

신규 계정 가입 시 30,000,000 CU 무료 제공 — 신용카드 불필요.

먼저 API key가 필요 없는 공개 엔드포인트 `https://api.blockvectra.com/v1/robinhood_mainnet/public`을 사용해 볼 수 있습니다(지갑 관련 JSON-RPC 메서드만 제공, Data API는 키 필요. 메서드 및 한도는 `/v1/chains` 기준). 더 높은 속도 제한이 필요한 경우 회원가입을 진행하세요.

* **웹 콘솔**: 이더리움 지갑 서명으로 가입하고 [콘솔](https://console.blockvectra.com/login/?next=%2Fkeys%2F)에서 API key를 생성합니다. 설정 세부 정보는 [빠른 시작 가이드](https://docs.blockvectra.com/en/quickstart/)를 참조하세요.
* **프로그래밍 방식 회원가입**: 자율 AI 에이전트, 자동화 스크립트, CI 파이프라인은 브라우저 없이 이더리움 지갑 서명(EIP-191)을 사용하여 로그인하고 API key를 발급받을 수 있습니다. [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/en/guides/programmatic-signup/)를 따르세요.
* **AI 에이전트**: 자율 AI 에이전트는 공식 Model Context Protocol (MCP) 서버를 사용하여 Robinhood Chain의 기능을 탐색할 수 있습니다. [BlockVectra에 AI 에이전트 연결하기](https://docs.blockvectra.com/en/guides/ai-agents/)를 참조하세요.
* **한도 상향**: 충전 후에는 계정 전체의 초당 호출 수 한도가 해제됩니다. 각 키는 여전히 Compute Unit(CU) 속도 및 버스트 한도의 적용을 받습니다. 현재 요율과 청구 단위는 [요금 페이지](https://blockvectra.com/en/pricing/)를 참조하세요.

## 다음 단계

* [데이터셋 디렉터리 둘러보기](https://blockvectra.com/en/data/): BlockVectra가 인덱싱하는 모든 데이터셋 확인.
* [무료 플랜 및 요금 확인](https://blockvectra.com/en/pricing/#free): 내 계정에 포함된 혜택 확인.
* [콘솔 로그인](https://console.blockvectra.com/login/?next=%2Fkeys%2F): API key 생성.