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

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

이 가이드에서 다루는 작업

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

RPC 및 WebSocket 접근

• 공개 RPC URL: API key가 필요 없는 엔드포인트, 지원되는 공개 메서드 및 속도 제한은 Robinhood Chain 메인넷 페이지 또는 테스트넷 페이지에서 확인할 수 있습니다.
• API key를 사용하는 JSON-RPC: 아래 엔드포인트와 curl 예제를 사용하세요. 로그 조회는 eth_getLogs 메서드 레퍼런스 및 블록 범위 한도 가이드를 참조하세요.
• API key를 사용하는 WebSocket: 아래 WebSocket 엔드포인트를 사용하고 newHeads 및 logs 구독은 WebSocket 구독 가이드를 따르세요. 공개 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 엔드포인트를 제공합니다.

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

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에서 chain_id와 메서드 정책을 읽어옵니다. API key 없는 공개 읽기의 경우 카탈로그의 public.url을 사용하고 public.methods에 나열된 메서드만 호출해야 합니다. 공개 HTTP가 가능하다고 해서 WebSocket 접근까지 가능한 것은 아닙니다.

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를 실행하세요.

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를 실행하세요.

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)에서 배포자 주소로 테스트 ETH를 받으세요. 메인넷 트랜잭션에는 메인넷 ETH가 필요합니다. 공식 네트워크 및 배포 가이드에 메인넷 및 테스트넷 chain ID가 나열되어 있습니다(접속일: 2026-10-07). 이 페이지의 엔드포인트 표는 /v1/chains 데이터를 사용합니다.

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

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 배포 튜토리얼을 계속 진행하세요.

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

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

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() 트랜잭션을 전송합니다:

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

마지막으로 처리한 블록을 유지하고 (blockHash, transactionHash, logIndex) 조합으로 중복을 제거하세요. 재연결 후에는 제한된 범위의 eth_getLogs 요청으로 누락된 블록을 백필하고, 블록체인 리오그(reorg) 발생 시 removed로 표시된 로그를 조정하세요. 자세한 내용은 WebSocket 구독 및 블록 범위 한도를 참조하세요.

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

직접 실행하는 curl 예제

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

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

응답 구조

응답은 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를 얻으려면 Robinhood Chain 테스트넷 수도꼭지(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 테스트넷 스타터 가이드를 참조하세요.

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

예상 응답:

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

토큰화 주식 데이터

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

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

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

완전한 스타터 템플릿: blockvectra/robinhood-stock-tokens

시작하기 및 API Key 발급

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

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

다음 단계

• 데이터셋 디렉터리 둘러보기: BlockVectra가 인덱싱하는 모든 데이터셋 확인.
• 무료 플랜 및 요금 확인: 내 계정에 포함된 혜택 확인.
• 콘솔 로그인: API key 생성.