Webhook, WebSocket 또는 RPC 폴링 선택
지원 체인, 복구 메커니즘, 수신 엔드포인트 요구사항 및 과금 모델별로 주소 알림, 소켓 구독 및 유한 폴링을 비교합니다.
HTTPS 수신 엔드포인트로 전달받으려면 주소 Webhook을 사용하고, 지원되는 실시간 구독에는 WebSocket을 사용하며, 워크플로에 자체 커서와 복구 기능이 필요한 경우에는 유한(bounded) 폴링을 사용하세요.
개발자와 AI 에이전트를 위한 온체인 이벤트 리스너를 구축할 때는 애플리케이션 아키텍처를 네트워크 지원 역량, 전달 보장 수준, 수신 측 제약 사항 및 운영 비용에 일치시켜야 합니다.
의사결정 매트릭스
아래 표는 지원 네트워크 역량, 인프라 요구사항, 복구 전략 및 과금 모델에 걸쳐 세 가지 연동 메커니즘을 비교합니다:
| 구분 | 주소 Webhook | WebSocket 구독 | 유한 RPC 폴링 |
|---|---|---|---|
| 주요 메커니즘 | 공개 엔드포인트로 HTTPS POST를 통해 전달되는 푸시 알림 | 영구 TLS 연결(wss://)을 통한 풀 스트림(pull-stream) 구독 | 클라이언트가 시작하는 HTTP JSON-RPC 배치 또는 스케줄링된 쿼리 |
| 체인 가용성 | GET /v1/push/chains에 선언된 지원 네트워크 전체 | GET /v1/chains에서 ws: true인 네트워크; 구독 유형은 subscriptions에 표시 | GET /v1/chains의 지원 네트워크 전체에서 키 없는 공개 RPC 또는 인증된 JSON-RPC 사용 |
| 수신 측 요구사항 | 공개 접근 가능한 HTTPS URL, 유효한 TLS 인증서, 타임아웃 내 2xx 응답, 원본 본문 HMAC SHA-256 서명 검증 | 아웃바운드 TCP/TLS 클라이언트 연결(wss://); ping/pong 하트비트 및 재연결 백오프 처리 | 상태 비저장 HTTP 클라이언트 또는 스케줄링된 워커; 로컬 블록 커서 저장 |
| 전달 및 순서 보장 | 지수 재시도 백오프가 적용된 최소 1회 전달(at-least-once); 수신 측에서 이벤트 id 또는 구독 간 ref + type 기준으로 중복 제거 필요 | 단일 활성 소켓에서 엄격한 순서 프레임 전달; 연결 해제 중에는 알림 누락 | 확정된 블록 높이에 대한 결정론적 풀 응답; 클라이언트가 실행 속도 조절 |
| 체인 재구성(reorg) | chain.reorg 제어 알림 발생; 수신 측은 정식(canonical) 리플레이를 적용하기 전에 대체된 이벤트를 폐기 | 재구성된 로그 알림에 "removed": true 포함; newHeads는 부모 해시 검사 필요 | 클라이언트가 폴링 틱 간에 parentHash 체인 연속성을 추적하여 리오그 감지 |
| 장애 복구 | 서버 보존 윈도우를 통해 POST /v1/push/subscriptions/{id}/replay로 리플레이 가능; 활성화 블록 이전의 갭은 eth_getLogs 백필 필요 | 서버 측 큐 없음; 클라이언트가 재연결 후 (blockHash, transactionHash, logIndex) 기준으로 중복 제거하며 eth_getLogs로 누락 구간 백필 | 저장된 last_synced_block부터 쿼리 재개; GET /v1/chains에 공개된 네트워크의 max_logs_block_range 단위로 청크 분할 |
| 과금 모델 | UTC 일자 동안 온라인 상태인 최대 주소 수 기준 그룹별 일일 주소 수수료 + 전달된 데이터 이벤트에 대한 CU; Webhook 과금 참조 | 핸드셰이크 및 하트비트는 과금되지 않음; eth_subscribe / eth_unsubscribe 및 소켓으로 플러시된 알림 단위에 대해 CU 과금 | Compute Unit 기준으로 요청당 측정: eth_blockNumber, eth_call, eth_getLogs; 메서드 가중치와 1달러당 CU는 GET /v1/plans에서 가져오며 아래 표에 표시 |
| 적합한 사용처 | 사용자 입금 모니터링, 핫월렛 주소 추적, 가맹점 결제, 비동기 이벤트 Webhook | 실시간 newHeads 및 필터링된 logs, 반응형 봇, 지원 네트워크의 대화형 UI | 배치 대사, cron 작업, ETL 파이프라인 |
현재 환산 기준 파라미터
1 USD = 10,000 청구 단위, 1 청구 단위 = 1,000 CU(즉 1 USD = 10,000,000 CU).
환산 공식: 호출당 CU 가중치 × 1,000,000 ÷ (10,000 × 1,000) USD.
| 메서드 | 호출당 CU | 100만 회 호출당 가격(USD) |
|---|---|---|
eth_blockNumber | 1 | $0.10 |
eth_call | 15 | $1.50 |
eth_getLogs | 30 | $3.00 |
debug_traceTransaction | 100 | $10.00 |
data.block | 5 | $0.50 |
주소 Webhook을 선택해야 하는 경우
백엔드가 인바운드 HTTPS 요청을 수신할 수 있는 표준 웹 서비스로 실행되는 경우 블록체인 Webhook API를 선택하세요:
- 대규모 주소 목록: 지갑별로 영구 소켓을 유지하지 않고도 수천 개의 고객 주소에서 발생하는 입출금을 모니터링할 수 있습니다.
- 서버리스 또는 컨테이너 기반 수신 엔드포인트: 서버리스 함수(AWS Lambda, Cloudflare Workers 등)는 인바운드 webhook 요청 시 즉시 실행되므로 지속적인 연결을 유지할 필요가 없습니다.
- 자동 재시도 및 리플레이: 수신 측의 일시적인 장애는 자동 재시도 백오프로 완화됩니다. 서버 보존 윈도우 내에서는 리플레이 엔드포인트를 사용하여 누락된 전달 건을 다시 전송받을 수 있습니다.
- 활성화 경계 고려사항: 매칭은 구독 변경 사항이 적용된 후(
applied_from_block)부터 시작됩니다. 주소가 추가되기 전이나 구독이offline상태인 동안 발생한 이벤트는 과거 RPC 로그를 통해 조회해야 합니다.
프로덕션 환경의 webhook 수신 엔드포인트를 외부에 노출하기 전에 서명 검증 및 리플레이 워크플로를 검토하세요.
WebSocket 구독을 선택해야 하는 경우
낮은 지연 시간이 필요하고 프로세스가 장기 실행되는 아웃바운드 소켓을 유지할 수 있는 경우 WebSocket 구독을 선택하세요:
- 실시간 블록 헤더: 각 블록이 체인 헤드에 추가될 때
newHeads를 스트리밍합니다. - 컨트랙트 이벤트 필터: 주소 또는 특정
topic0과 일치하는 실시간 컨트랙트logs를 스트리밍합니다. - 프라이빗 환경: 인바운드 공개 HTTPS 포트를 열 수 없는 NAT나 방화벽 뒤의 로컬 스크립트, CLI 에이전트 또는 백엔드 서비스에 적합합니다.
- 네트워크 가용성 확인: GET /v1/chains에서 대상 네트워크의
ws와subscriptions를 확인하세요. HyperEVM도 WebSocket을 사용할 수 있으며, 가용성은 항상 이 카탈로그로 판단합니다. 네트워크가 WebSocket을 제공하지 않으면 연결 시 HTTP 404(unknown_chain)가 반환됩니다. - 연결 해제 처리 규율: WebSocket 알림은 연결 해제 시 서버에 보존되지 않습니다. 소켓 연결이 끊어지면 클라이언트는 무작위 지수 백오프로 재연결하고
eth_getLogs를 통해 누락된 블록을 백필해야 합니다.
필터 한도, 연결 상한(키당 20개, 계정당 50개) 및 viem 연결 예제는 WebSocket 구독 가이드를 검토하세요.
유한 RPC 폴링을 선택해야 하는 경우
스케줄링된 워커나 데이터 파이프라인을 실행하거나 WebSocket을 사용할 수 없는 네트워크에서 작업할 때는 유한 JSON-RPC 폴링을 선택하세요:
- 예약 처리 및 백필: HyperEVM(
hyperevm_mainnet)은 유한 폴링과 과거 백필에 HTTPeth_blockNumber와eth_getLogs를 계속 사용할 수 있습니다. 이는 WebSocket을 사용할 수 없다는 뜻이 아닙니다. - 제어된 쿼리 속도: 폴링을 사용하면 개발자와 AI 에이전트가 요청 빈도를 제어하고, 키별 속도 제한에 맞춰 Compute Unit 소비를 관리하며, 장기 실행 작업 중 소켓 끊김을 방지할 수 있습니다. 키별 한도 — 기본 속도 100 CU/s, 버스트 용량 400 CU; 유료 충전 후 각 키는 최소 2,000 CU/s, 버스트 10,000 CU이며 더 높은 사용자 지정 한도는 유지됩니다.
- 블록 범위 제한: 인증된
eth_getLogs쿼리는 GET /v1/chains에 공개된 네트워크의max_logs_block_range로 제한됩니다. 이 제한을 초과하면 오류 코드-32602(logs_range_too_large)가 반환됩니다. 더 넓은 구간은 대상 네트워크의max_logs_block_range를 초과하지 않는 연속 청크로 분할하세요.
| 체인 | 체인 식별자 | max_logs_block_range (블록 수) |
|---|---|---|
| Arbitrum One | arb_mainnet | 1,000 |
| Arc | arc_mainnet | 1,000 |
| Avalanche C-Chain | avax_mainnet | 1,000 |
| Base | base_mainnet | 1,000 |
| Berachain | berachain_mainnet | 1,000 |
| Boba | boba_mainnet | 1,000 |
| BNB Smart Chain | bsc_mainnet | 1,000 |
| Celo | celo_mainnet | 1,000 |
| Ethereum | eth_mainnet | 1,000 |
| Ethereum Sepolia | eth_sepolia | 1,000 |
| Fraxtal | fraxtal_mainnet | 1,000 |
| Gnosis | gnosis_mainnet | 1,000 |
| HyperEVM | hyperevm_mainnet | 1,000 |
| Ink | ink_mainnet | 1,000 |
| Katana | katana_mainnet | 1,000 |
| Linea | linea_mainnet | 1,000 |
| Metal L2 | metall2_mainnet | 1,000 |
| Mode | mode_mainnet | 1,000 |
| OP Mainnet | op_mainnet | 1,000 |
| Polygon | polygon_mainnet | 1,000 |
| Robinhood Chain | robinhood_mainnet | 1,000 |
| Robinhood Chain Testnet | robinhood_testnet | 1,000 |
| Rootstock | rootstock_mainnet | 1,000 |
| Soneium | soneium_mainnet | 1,000 |
| Sonic | sonic_mainnet | 1,000 |
| Unichain | unichain_mainnet | 1,000 |
| World Chain | world_mainnet | 1,000 |
| X Layer | xlayer_mainnet | 1,000 |
| Zora | zora_mainnet | 1,000 |
청킹 알고리즘에 대해서는 HyperEVM 로그 백필 가이드 및 eth_getLogs 블록 범위 가이드를 참조하세요.
전체 워크로드 체크리스트와 자체 테스트 방법은 RPC 제공업체 선택 방법에서 시작하세요.
소규모 폴링을 위해 제공업체를 선택할 때는 표준 RPC 청구 및 지원 범위에 대한 제공업체 비교를 참조하세요. 사용량 기반 청구와 평가판 및 구독 비용을 비교하세요. 알림 및 백필 비용은 RPC 조회와 다른 과금 단위를 사용합니다.
연동 가이드
Robinhood Chain에서의 WebSocket
Robinhood Chain에서의 실시간 newHeads 또는 필터링된 logs는 WebSocket 구독 가이드를 따라 인증 및 구독 요청을 진행하세요. 연결이 끊어지면 백오프로 재연결하고, 다시 구독하며, 저장된 커서로부터 eth_getLogs를 사용하여 누락된 블록을 백필합니다. 로그는 (blockHash, transactionHash, logIndex) 기준으로 중복을 제거하세요.
HyperEVM에서의 유한 폴링
HyperEVM(hyperevm_mainnet)의 경우 HyperEVM 로그 백필 가이드를 따라 유한 폴링 및 복구를 수행하세요. max_logs_block_range 이내의 청크 단위로 저장된 커서부터 쿼리하고, 처리가 성공하면 이벤트와 진행 상태를 함께 영구 저장하며, 불완전한 구간은 재시도합니다. 체인 연속성을 확인하고 중첩 구간을 스캔하여 리오그를 처리하세요.
다음 단계
- 데이터셋 디렉터리 둘러보기: BlockVectra가 인덱싱하는 모든 데이터셋 확인.
- 무료 플랜 및 요금 확인: 계정에 포함된 혜택 확인.
- 콘솔 로그인: API key 생성.
최종 수정일: