Data API를 통한 토큰화 주식 일별 온체인 지표 조회

예제 체인 robinhood_mainnet에서의 컨트랙트 배포 및 이벤트 수신은 RPC 및 WebSocket 가이드를 참고하세요.

3단계 작업: 온체인 주식 활동 조회

최신 기록된 UTC 일자의 가장 활발한 토큰화 주식을 찾고, 전송 횟수와 보유자 수를 확인합니다.

하나의 API key로 메인넷 주식 토큰 활동 및 보유자 데이터를 조회하여 활동 대시보드를 구성할 수 있습니다. 이는 주식 호가가 아닌 온체인 활동 지표입니다.

1. API key 없이 최신 블록 조회

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

JSON-RPC의 result는 16진수 형태의 최신 블록 번호입니다. 이 퍼블릭 RPC 호출에는 키가 필요하지 않으며, 3단계의 Data API 쿼리에는 키가 필요합니다.

2. 동일한 체인을 위한 키 생성

콘솔에 로그인하고 API Keys 페이지를 엽니다. 키를 생성하고 대화상자에 표시된 시크릿을 저장하세요. 동일한 키로 robinhood_mainnet의 JSON-RPC와 Data API를 모두 이용할 수 있습니다.

브라우저 없이 HTTP를 사용하는 AI Agent의 경우, 프로그래밍 방식 회원가입 가이드에 따라 이더리움 지갑 서명으로 가입하고 키를 생성하세요. 사용자에게 채팅창에 키를 붙여넣도록 요청하지 마세요.

3. 발급받은 키로 주식 활동 조회

아래의 replace-with-your-key를 저장해 둔 키로 교체한 후 서버 또는 로컬 터미널에서 명령을 실행하세요. day를 생략하면 가장 최근에 기록된 일자가 선택되며, limit=5는 전송 활동 내림차순으로 정렬된 최대 5개의 주식을 반환합니다.

export BLOCKVECTRA_API_KEY='replace-with-your-key'

curl -sS "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?limit=5" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

응답에서 다음 필드를 확인하세요:

data 배열이 비어 있으면 활동 기록이 없음을 의미합니다. 결과에서 특정 주식을 자세히 확인하려면 아래 설명된 대로 해당 token 값을 사용하여 GET /robinhood_mainnet/stocks/{token}을 호출하세요.

토큰화 주식 데이터셋 소개

BlockVectra Data API는 토큰화 주식에 대한 일별 온체인 지표와 메타데이터를 제공합니다. 이 데이터셋은 일별 전송, 발행, 소각, 순공급량 변화, 보유자 분포, 탈중앙화 거래소(DEX) 거래 지표를 집계하여 개발자가 토큰화 주식의 공개 온체인 활동을 추적할 수 있도록 지원합니다.

이 데이터셋을 지원하는 체인 목록은 지원 체인 페이지를 참조하세요.

• 기본 URL: https://api.blockvectra.com/v1/data — GET /chains를 제외한 모든 Data API 경로는 체인 식별자로 시작합니다 (예: https://api.blockvectra.com/v1/data/{chain}/…).
• 체인 예시: robinhood_mainnet (경로 파라미터 예시로 사용됨. 이 데이터셋을 제공하는 전체 체인은 지원 체인 참조).
• 인증: x-api-key: $BLOCKVECTRA_API_KEY 요청 헤더에 API key를 제공하세요.
• 과금 및 지원 범위: 연산 단위(CU)로 계량되며, 2xx 성공 응답에 대해서만 과금됩니다. 체인에서 주식 데이터셋을 지원하지 않는 경우 엔드포인트는 HTTP 422 no_coverage를 반환합니다 (과금되지 않음).

일별 리더보드 (GET /{chain}/stocks)

GET /{chain}/stocks 엔드포인트는 지정된 UTC 날짜의 토큰화 주식 일별 활동 리더보드를 반환하며, 표시용 메타데이터(심볼, 이름 등)를 포함하고 전송 활동 내림차순(가장 활동적인 토큰이 먼저 나옴)으로 정렬됩니다.

요청 파라미터

• {chain} (경로 파라미터, 필수): 체인 식별자 (예: robinhood_mainnet).
• day (쿼리 파라미터, 선택): YYYY-MM-DD 형식의 UTC 달력 날짜. 생략 시 기록된 최신 날짜로 기본 설정됩니다 (활동이 기록되지 않은 경우 data: []와 함께 200 반환). 유효한 YYYY-MM-DD 달력 날짜가 아닌 경우 HTTP 400을 반환합니다 (error.code = "bad_request").
• limit (쿼리 파라미터, 선택): 반환할 최대 레코드 수. 기본값은 50이며, 500을 초과하는 값은 500으로 제한됩니다. 0 또는 정수가 아닌 값을 전달하면 HTTP 400을 반환합니다 (error.code = "bad_request").

페이지네이션 동작

이 엔드포인트는 페이지네이션을 지원하지 않습니다. limit 파라미터는 반환되는 최대 레코드 수를 제한합니다. 응답을 감싸는 StockDailyListEnvelope(data 및 meta)에서 주식 엔드포인트는 next_cursor를 반환하지 않습니다 (키 자체가 완전히 없으며 null로도 반환되지 않음).

코드 예시

예제 체인 robinhood_mainnet의 스타터 템플릿: blockvectra/robinhood-stock-tokens

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

응답 구조

응답 구조는 data와 meta를 포함하는 StockDailyListEnvelope입니다:

• data (배열): 일별 리더보드 레코드(StockDaily) 목록으로, 전송 활동 내림차순(가장 활동적인 토큰 우선)으로 정렬됩니다. 각 항목에는 토큰 식별자(token, symbol, name), 전송 활동(transfers, unique_senders, unique_receivers), 공급량 지표(mint_raw_amount, burn_raw_amount, net_supply_change), 분포 지표(holder_count, top10_holder_share_bps), DEX 거래 지표(dex_swap_count, dex_raw_volume), 갱신 타임스탬프(refreshed_at)가 포함됩니다.
• meta (객체): 체인 메타데이터(chain, chain_slug, chain_external_id, as_of_block, safe_block, finalized_block, coverage, refreshed_at). meta.refreshed_at은 null일 수 있습니다. null은 해당 데이터의 갱신 시간을 알 수 없으며 최신이 아닌 것으로 취급해야 함을 의미합니다. 블록 기반 엔드포인트는 항상 값을 반환합니다.

단일 토큰화 주식 조회 (GET /{chain}/stocks/{token})

GET /{chain}/stocks/{token} 엔드포인트는 토큰 주소를 기준으로 특정 토큰화 주식의 메타데이터와 최근 최대 30일간의 일별 지표를 가져옵니다.

요청 파라미터

• {chain} (경로 파라미터, 필수): 체인 식별자 (예: robinhood_mainnet).
• {token} (경로 파라미터, 필수): 20바이트 토큰 컨트랙트 주소. 0x 접두사는 선택 사항이며 대소문자를 모두 지원합니다 (반환되는 주소는 0x 뒤에 40자리 소문자 16진수로 정규화됩니다). 유효하지 않은 주소 형식은 HTTP 400을 반환합니다 (error.code = "bad_request").
• {token}이 알려진 토큰화 주식이 아닌 경우 HTTP 404를 반환합니다 (error.code = "not_found"). {chain}이 알 수 없는 체인인 경우 HTTP 404를 반환합니다 (error.code = "unknown_chain").

코드 예시

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

응답 구조

응답 구조는 data와 meta를 포함하는 StockTokenEnvelope입니다:

• data (객체): 토큰 컨트랙트 메타데이터(address, symbol, name, decimals, created_block, created_tx_hash, factory, creator, mint_address, burn_address, refreshed_at) 및 최근 일별 지표 배열 daily를 포함하는 StockToken 객체입니다.
  • daily (배열): 최근 최대 30일간의 일별 지표(StockDailyMetric) 배열로, 날짜 내림차순(최신순)으로 정렬됩니다. 각 일별 항목은 위의 리더보드와 동일한 지표 스키마를 공유합니다 (중복되는 token, symbol, name 필드 제외).
• meta (객체): 리더보드 응답과 일치하는 체인 메타데이터 객체입니다.

주요 반환 필드 설명

일별 지표 필드 (StockDaily 및 StockDailyMetric)

리더보드와 단일 토큰 과거 일별 항목 모두 다음 핵심 필드를 포함합니다:

토큰 메타데이터 필드 (StockToken)

단일 토큰을 쿼리할 때 외부 data 객체는 컨트랙트 메타데이터와 최근 일별 지표를 포함합니다:

인코딩 규칙

API는 수치 정밀도와 일관성을 보존하기 위해 모든 엔드포인트에서 엄격한 인코딩 규칙을 준수합니다:

• 화폐/금액 안전성 (Money-safety): 2^53을 초과할 수 있는 모든 값(256비트 정수, 예: mint_raw_amount, burn_raw_amount, net_supply_change, dex_raw_volume)은 JSON 숫자가 아닌 10진수 문자열로 직렬화되며, 지수 표기법이나 16진수 표기법을 사용하지 않습니다. 이를 통해 JavaScript와 같은 런타임 환경에서 정밀도 손실을 방지합니다. JavaScript/TypeScript에서는 BigInt(str)로 파싱하고(예: const net = BigInt(body.data.daily[0].net_supply_change)), Python에서는 int(str)로 파싱하세요. 2^53보다 훨씬 작은 카운터(transfers, unique_senders, unique_receivers, holder_count, top10_holder_share_bps, dex_swap_count, created_block)는 일반 JSON 숫자입니다.
• 바이너리 및 16진수 값: 주소는 0x 뒤에 40자리의 소문자 16진수 문자이며, 해시는 0x 뒤에 64자리의 소문자 16진수 문자입니다. 반환되는 모든 16진수 값은 반드시 소문자입니다.
• 타임스탬프 및 날짜: refreshed_at과 같은 타임스탬프는 YYYY-MM-DDTHH:MM:SSZ(초 단위 정밀도의 ISO-8601 UTC)를 사용합니다. 일별 집계(day)는 일반 달력 날짜(YYYY-MM-DD)를 사용합니다.

사용량 추정치 (매일 50개 토큰 갱신)

Data API 쿼리는 플랫폼 메서드 가중치에 따라 연산 단위(CU)를 소비합니다. 아래 추정치는 50개의 토큰이 각각 매일 1회 GET /{chain}/stocks/{token}을 호출하는 시나리오를 활성 메서드 가중치에 따라 평가한 것입니다:

시작하기 및 업그레이드

무료 할당량은 개발, 테스트 및 가벼운 워크로드에 이상적입니다. 트래픽이 확장되어 더 높은 동시성이나 더 많은 연산 단위가 필요한 경우 콘솔 결제 페이지에서 온체인 충전을 진행하세요. 온체인에서 확인되고 적립되면 계정 전반의 초당 호출 수 제한이 해제됩니다. 각 키는 JSON-RPC 문서에 설명된 대로 CU 속도 및 버스트 제한을 계속 적용받습니다. 사용하지 않은 무료 크레딧은 크레딧 잔액에 유지되며 계속 사용할 수 있습니다. 현재 요율 및 청구 단위는 가격 정책 페이지를 참조하세요.

다음 단계

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