Robinhood Chain 테스트넷 RPC 시작하기: 키 없는 읽기, WebSocket 로그, 메인넷 전환
Robinhood Chain 테스트넷 RPC로 시작하기: 퍼블릭 RPC URL, 키 없는 읽기, API key를 사용한 WebSocket 로그 구독, 수도꼭지(faucet) 접근 및 동일한 키로 메인넷 전환.
BlockVectra는 Robinhood Chain 테스트넷(Chain ID 46630)에 대해 JSON-RPC 및 WebSocket을 지원하며, 동일한 API key는 Robinhood Chain 메인넷에서도 작동합니다. 이 가이드는 Robinhood Chain 테스트넷 스타터 템플릿의 세 단계를 따릅니다: 키 없이 테스트넷 읽기, 프로그래밍 방식으로 계정 생성 및 로그 스트리밍, 동일한 키를 메인넷으로 전환하기. 엔드포인트 파라미터, 메서드 정책 및 토큰화 주식 데이터에 대해서는 Robinhood Chain 가이드를 참조하세요.
이 가이드의 RPC 엔드포인트는 BlockVectra가 제공하며, Robinhood 자체의 공개 RPC와 네트워크 매개변수는 공식 연결 문서에서 확인할 수 있습니다.
템플릿 실행
git clone https://github.com/blockvectra/robinhood-testnet-starter
cd robinhood-testnet-starter
npm install
npm run typecheckNode.js 18 이상이 필요합니다. 세 가지 스크립트는 npm run step1, npm run step2, npm run step3입니다. 선택적 환경 변수(BLOCKVECTRA_API_KEY, WALLET_PRIVATE_KEY)는 셸에서 읽어오며, .env를 자동으로 로드하지 않습니다.
한 번의 명령으로 전체 흐름 실행
npm run walkthroughnpm run walkthrough는 키 없이 테스트넷을 읽고, 필터 로그를 30초 동안 구독한 뒤, 같은 API key로 메인넷 RPC와 Data API를 읽습니다. BLOCKVECTRA_API_KEY가 비어 있지 않으면 해당 키를 재사용하고 로그인과 키 생성을 건너뜁니다. BLOCKVECTRA_API_KEY가 설정되어 있지 않고 WALLET_PRIVATE_KEY도 없으면 첫 실행에서 전용 로그인 지갑을 .agent-wallet.json에 저장하고, 이후 실행에서는 그 계정을 재사용합니다. 키가 없으면 실행할 때마다 새로운 서버 측 키가 만들어집니다. 구독 전에 src/step2-key-and-logs.ts의 예시 컨트랙트 주소를 바꾸세요.
이 명령은 같은 프로세스 안에서 키를 메인넷 읽기에 전달하므로 마스킹된 출력에서 키를 복사할 필요가 없습니다. 키 없이 읽기가 실패하면 로그인하지 않습니다. 구독이 확인되지 않거나 구독 중 오류가 발생하면 명령은 0이 아닌 코드로 종료되며 메인넷 읽기를 계속하지 않습니다. 약 30초 안에 일치하는 이벤트가 없다는 사실만으로는 실패가 아니며, 이벤트 전달을 확인하려면 일치하는 알림을 받아야 합니다.
1단계: 키 없이 테스트넷 읽기
퍼블릭 엔드포인트 https://api.blockvectra.com/v1/robinhood_testnet/public은 계정과 API key 없이 지갑 관련 JSON-RPC 메서드를 제공합니다. EIP-155 Chain ID를 직접 조회하세요:
curl -s "https://api.blockvectra.com/v1/robinhood_testnet/public" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'응답은 {"jsonrpc":"2.0","id":1,"result":"0xb626"}입니다. 0xb626은 16진수 Chain ID이며 10진수로는 46630입니다.
템플릿은 GET /v1/chains에서 체인 항목을 읽어 viem 클라이언트를 빌드하므로 체인 이름과 ID가 하드코딩되지 않습니다. src/shared.ts의 내용:
import { createPublicClient, defineChain, http, webSocket } from "viem";
export const API_BASE = "https://api.blockvectra.com/v1";
export interface ChainEntry {
chain: string;
name: string;
chain_id: number;
data: boolean;
ws: boolean;
subscriptions: string[];
public?: { url: string };
}
export async function getChain(slug: string): Promise<ChainEntry> {
const res = await fetch(`${API_BASE}/chains`);
if (!res.ok) throw new Error(`GET /v1/chains failed: ${res.status}`);
const { chains } = (await res.json()) as { chains: ChainEntry[] };
const entry = chains.find((c) => c.chain === slug);
if (!entry) throw new Error(`${slug} not found in /v1/chains`);
return entry;
}
export function toViemChain(entry: ChainEntry, rpcUrl: string) {
return defineChain({
id: entry.chain_id,
name: entry.name,
nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
rpcUrls: { default: { http: [rpcUrl] } },
});
}
export function httpClient(entry: ChainEntry, url: string, apiKey?: string) {
return createPublicClient({
chain: toViemChain(entry, url),
transport: http(url, apiKey ? { fetchOptions: { headers: { "x-api-key": apiKey } } } : undefined),
});
}
export function wsClient(entry: ChainEntry, apiKey: string) {
const base = "wss://api.blockvectra.com/v1";
const url = `${base}/${entry.chain}/${apiKey}`;
return createPublicClient({ chain: toViemChain(entry, url), transport: webSocket(url) });
}템플릿 src/step1-public-read.ts는 먼저 카탈로그의 chain_id가 양의 안전 정수인지 확인한 다음 eth_chainId와 비교하며, 일치할 때만 블록과 주소 잔액을 읽습니다. 값이 유효하지 않거나 체인 ID가 일치하지 않으면 0이 아닌 코드로 종료되고 npm run walkthrough는 로그인 전에 멈춥니다:
import { formatEther, type Address } from "viem";
import { API_BASE, getChain, httpClient } from "./shared.js";
// Step 1: no account, no key. Read Robinhood Chain Testnet through the public endpoint.
const SLUG = "robinhood_testnet";
// Any address works; override with the first CLI argument.
const address = (process.argv[2] ?? "0x0000000000000000000000000000000000000000") as Address;
const chain = await getChain(SLUG);
if (!Number.isSafeInteger(chain.chain_id) || chain.chain_id <= 0) {
throw new Error(
`invalid catalog chain_id for ${SLUG}: expected a positive safe integer, got ${String(chain.chain_id)}`,
);
}
const client = httpClient(chain, `${API_BASE}/${SLUG}/public`);
// Confirm the network before any other read.
const chainId = await client.getChainId();
if (chainId !== chain.chain_id) {
throw new Error(
`chain ID mismatch for ${SLUG}: expected ${chain.chain_id} (catalog), actual ${chainId} (eth_chainId)`,
);
}
const [blockNumber, balance] = await Promise.all([
client.getBlockNumber(),
client.getBalance({ address }),
]);
console.log(`chain : ${chain.name} (${SLUG})`);
console.log(`eth_chainId : ${chainId} (0x${chainId.toString(16)})`);
console.log(`block : ${blockNumber}`);
console.log(`balance : ${formatEther(balance)} ETH (${address})`);2단계: 프로그래밍 방식으로 계정 생성 및 로그 구독
src/step2-key-and-logs.ts는 https://console-api.blockvectra.com/v1에서 지갑(SIWE, EIP-191)으로 로그인합니다. 최초 로그인 시 계정이 생성되며, 클라이언트는 API key를 생성합니다. 신규 계정 가입 시 30,000,000 CU 무료 제공 — 신용카드 불필요.
import { loadOrCreateWallet } from "./wallet.js";
const CONSOLE_API = "https://console-api.blockvectra.com/v1";
const REF = "gh-robinhood-testnet-starter";
async function post<T>(path: string, body: unknown, token?: string): Promise<T> {
const res = await fetch(`${CONSOLE_API}${path}`, {
method: "POST",
headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${path} failed: ${res.status} ${await res.text()}`);
return (await res.json()) as T;
}
async function provisionKey(): Promise<string> {
const { account } = loadOrCreateWallet({
walletFile: ".agent-wallet.json",
privateKey: process.env.WALLET_PRIVATE_KEY,
});
console.log(`wallet: ${account.address}`);
// SIWE: ask for a challenge, sign it verbatim (EIP-191), log in. A first sign-in creates the account.
const { message } = await post<{ message: string }>("/auth/siwe/challenge", {
address: account.address,
purpose: "login",
});
const signature = await account.signMessage({ message });
const login = await post<{ session: { token: string }; account_created: boolean }>("/auth/siwe/login", {
message,
signature,
ref: REF,
});
console.log(`account_created: ${login.account_created}`);
const created = await post<{ api_key: string }>("/keys", { label: "robinhood-testnet-starter" }, login.session.token);
return created.api_key;
}
const apiKey = process.env.BLOCKVECTRA_API_KEY?.trim() || (await provisionKey());BLOCKVECTRA_API_KEY가 비어 있지 않으면 2단계는 로그인과 지갑 파일 읽기 및 생성을 건너뜁니다. 그렇지 않으면 WALLET_PRIVATE_KEY가 우선 적용되며, 값이 잘못되면 지갑 파일로 대체하지 않고 실행을 중단합니다. 이 변수가 없으면 첫 실행에서 현재 작업 디렉터리의 .agent-wallet.json에 전용 로그인 지갑을 저장하고, 이후 같은 디렉터리에서 실행하면 같은 ID를 재사용합니다. 계정은 해당 지갑이 처음 로그인할 때 만들어집니다. 구현은 src/wallet.ts에 있습니다.
이 파일에는 평문 개인 키가 들어 있으며 최초 생성 시 POSIX 모드 0600으로 생성되고 *wallet*.json 패턴에 해당하므로 Git에서 무시됩니다. 보호하고 백업하세요. 커밋하지 말고, 개인 키를 명령줄에 넣지 말고, 자금이 있는 지갑은 사용하지 마세요. ID가 손상되었거나 유효하지 않거나 읽거나 쓸 수 없으면 2단계는 SIWE 챌린지 전에 중단하며 파일을 덮어쓰거나 새 ID로 바꾸지 않습니다. walkthrough는 여전히 1단계 공개 읽기를 먼저 수행합니다. 기존 API key가 없으면 실행할 때마다 새로운 서버 측 키가 만들어지고 키는 자동으로 폐기되지 않습니다. 계정을 재사용해도 키가 자동으로 재사용되지는 않습니다.
WebSocket URL은 경로에 키를 포함합니다: wss://api.blockvectra.com/v1/robinhood_testnet/{api_key}. 템플릿은 구독하기 전에 GET /v1/chains에서 실시간 ws 플래그와 subscriptions 목록을 확인합니다:
이 저장소에서 템플릿의 구독 구현을 실행하세요. eth_subscribe가 구독 ID를 반환한 뒤에만 30초 관찰 구간을 시작하며, 종료 시 eth_unsubscribe가 true를 반환해야 합니다. 연결·구독 오류나 구독 해제 실패가 발생하면 연속 실행은 메인넷으로 진행하지 않습니다. 로그가 없는 관찰 구간만으로 구독 성공을 확인할 수는 없습니다.
npm run step2모든 logs 구독 필터는 address 또는 topic0을 포함해야 합니다. 예제 주소를 모니터링하려는 컨트랙트 주소로 바꾸세요. 필터 규칙, 종료 코드 및 재연결에 대한 자세한 내용은 WebSocket 구독 가이드를 참조하세요.
3단계: 동일한 키를 메인넷으로 전환
npm run walkthrough는 2단계에서 얻거나 재사용한 동일한 키를 같은 프로세스 안에서 메인넷 읽기에 전달합니다. npm run step3를 단독으로 실행하려면 BLOCKVECTRA_API_KEY에 기존 API key가 있어야 하며, 단독으로 실행한 2단계는 상위 셸 환경을 설정하지 않습니다. 메인넷 슬러그는 robinhood_mainnet입니다. 아래는 RPC로 블록을 읽고 Data API로 주식 토큰의 온체인 활동을 읽는 코드 조각이며, 주식 시세가 아닙니다:
const apiKey = process.env.BLOCKVECTRA_API_KEY?.trim();
if (!apiKey) {
throw new Error(
"Set BLOCKVECTRA_API_KEY to an existing API key (create one in the console), " +
"or run `npm run walkthrough` to get a key and use it for the mainnet read in one process.",
);
}
const mainnet = await getChain("robinhood_mainnet");
// JSON-RPC with the key: the chain slug changes.
const client = httpClient(mainnet, `${API_BASE}/${mainnet.chain}`, apiKey);
console.log(`mainnet block: ${await client.getBlockNumber()}`);
// Data API: Robinhood stock-token leaderboard (see the Robinhood Chain guide).
const res = await fetch(`${API_BASE}/data/${mainnet.chain}/stocks`, { headers: { "x-api-key": apiKey } });
if (!res.ok) throw new Error(`Data API failed: ${res.status} ${await res.text()}`);
console.log(JSON.stringify(await res.json(), null, 2).slice(0, 2000));curl을 사용한 동일한 리더보드 엔드포인트:
curl -s -H "x-api-key: $BLOCKVECTRA_API_KEY" \
"https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks"Data API는 메인넷 전용입니다: GET /v1/chains에서 robinhood_testnet은 data: false로 보고되고 robinhood_mainnet은 data: true로 보고됩니다. 요청 파라미터 및 응답 외층 구조는 토큰화 주식 가이드를 참조하세요.
API에서 한도 및 기능 확인
실시간 jsonrpc, data, ws, subscriptions 플래그, 허용된 JSON-RPC 메서드, 로그 블록 범위, 상태 보존 기간 및 각 체인의 퍼블릭 엔드포인트를 확인하려면 GET /v1/chains를 조회하세요. 현재 가격과 플랜 한도는 GET /v1/plans에서 확인할 수 있습니다.
curl -s "https://api.blockvectra.com/v1/chains"관련 가이드
- 테스트넷 RPC URL 및 한도 확인.
- 트랜잭션을 전송하기 전에 테스트넷 수도꼭지(faucet)에서 테스트 ETH 받기.
다음 단계
- 데이터셋 디렉터리 살펴보기: BlockVectra가 인덱싱하는 모든 데이터셋을 확인하세요.
- 무료 플랜 및 요금 확인: 계정에 포함된 혜택을 확인하세요.
- 콘솔에 로그인: API key를 생성하세요.
최종 수정일: