# Data API를 통한 토큰화 주식 일별 온체인 지표 조회 > Source: https://docs.blockvectra.com/ko/guides/stocks/ > 데이터는 공개된 온체인 기록을 기반으로 하며 참고용으로만 제공됩니다. 투자 조언에 해당하지 않습니다. 예제 체인 `robinhood_mainnet`에서의 컨트랙트 배포 및 이벤트 수신은 [RPC 및 WebSocket 가이드](https://docs.blockvectra.com/en/guides/robinhood-chain/)를 참고하세요. ## 3단계 작업: 온체인 주식 활동 조회 최신 기록된 UTC 일자의 가장 활발한 토큰화 주식을 찾고, 전송 횟수와 보유자 수를 확인합니다. 하나의 API key로 메인넷 주식 토큰 활동 및 보유자 데이터를 조회하여 활동 대시보드를 구성할 수 있습니다. 이는 주식 호가가 아닌 온체인 활동 지표입니다. ### 1. API key 없이 최신 블록 조회 ```bash 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 페이지를 엽니다](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-stocks-task). 키를 생성하고 대화상자에 표시된 시크릿을 저장하세요. 동일한 키로 `robinhood_mainnet`의 JSON-RPC와 Data API를 모두 이용할 수 있습니다. 브라우저 없이 HTTP를 사용하는 AI Agent의 경우, [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/en/guides/programmatic-signup/?ref=docs-stocks-task)에 따라 이더리움 지갑 서명으로 가입하고 키를 생성하세요. 사용자에게 채팅창에 키를 붙여넣도록 요청하지 마세요. ### 3. 발급받은 키로 주식 활동 조회 아래의 `replace-with-your-key`를 저장해 둔 키로 교체한 후 서버 또는 로컬 터미널에서 명령을 실행하세요. `day`를 생략하면 가장 최근에 기록된 일자가 선택되며, `limit=5`는 전송 활동 내림차순으로 정렬된 최대 5개의 주식을 반환합니다. ```bash 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[].day` | 일별 지표의 UTC 날짜. | | `data[].token` | 쿼리에서 반환된 주식 토큰 컨트랙트 주소. | | `data[].symbol` | 토큰 심볼. | | `data[].transfers` | 해당 일자의 온체인 전송 횟수. | | `data[].holder_count` | 총 보유자 주소 수. | | `meta.as_of_block` | 일별 지표 스냅샷의 블록 높이가 아닌 현재 인덱싱된 헤드 블록. | | `meta.refreshed_at` | 스냅샷 갱신 시간; 이 값이 `null`이면 데이터를 최신이 아닌 것으로 취급하세요. | `data` 배열이 비어 있으면 활동 기록이 없음을 의미합니다. 결과에서 특정 주식을 자세히 확인하려면 아래 설명된 대로 해당 `token` 값을 사용하여 `GET /robinhood_mainnet/stocks/{token}`을 호출하세요. ## 토큰화 주식 데이터셋 소개 BlockVectra Data API는 토큰화 주식에 대한 일별 온체인 지표와 메타데이터를 제공합니다. 이 데이터셋은 일별 전송, 발행, 소각, 순공급량 변화, 보유자 분포, 탈중앙화 거래소(DEX) 거래 지표를 집계하여 개발자가 토큰화 주식의 공개 온체인 활동을 추적할 수 있도록 지원합니다. 이 데이터셋을 지원하는 체인 목록은 [지원 체인](https://docs.blockvectra.com/en/chains/) 페이지를 참조하세요. * **기본 URL**: `https://api.blockvectra.com/v1/data` — `GET /chains`를 제외한 모든 Data API 경로는 체인 식별자로 시작합니다 (예: `https://api.blockvectra.com/v1/data/{chain}/…`). * **체인 예시**: `robinhood_mainnet` (경로 파라미터 예시로 사용됨. 이 데이터셋을 제공하는 전체 체인은 [지원 체인](https://docs.blockvectra.com/en/chains/) 참조). * **인증**: `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](https://github.com/blockvectra/robinhood-stock-tokens) **cURL** ```bash curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" ``` **TypeScript** ```ts const res = await fetch( "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10", { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! }, }, ); const body = await res.json(); console.log(body); ``` **Python** ```python import os import requests res = requests.get( "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10", headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}, ) print(res.json()) ``` ### 응답 구조 응답 구조는 `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** ```bash curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks/0x1111111111111111111111111111111111111111" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" ``` **TypeScript** ```ts const token = "0x1111111111111111111111111111111111111111"; const res = await fetch( `https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks/${token}`, { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! }, }, ); const body = await res.json(); console.log(body); ``` **Python** ```python import os import requests token = "0x1111111111111111111111111111111111111111" res = requests.get( f"https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks/{token}", headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}, ) print(res.json()) ``` ### 응답 구조 응답 구조는 `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) 리더보드와 단일 토큰 과거 일별 항목 모두 다음 핵심 필드를 포함합니다: | 필드 | 타입 | 설명 | | ------------------------ | -------------------- | ------------------------------------------------------------------- | | `day` | `string` (date) | `YYYY-MM-DD` 형식의 UTC 집계 날짜. | | `token` | `string` (address) | 토큰 컨트랙트 주소 (리더보드 `StockDaily`에만 존재), `0x` 접두사가 붙은 40자리 소문자 16진수 문자. | | `symbol` | `string` | 토큰 심볼 (예: `"EXMPL"`). | | `name` | `string` | 토큰 표시 이름. 일치하는 이름 메타데이터가 없는 경우 빈 문자열 `""`. | | `transfers` | `integer` (int64) | 해당 UTC 일자의 총 온체인 전송 횟수. | | `unique_senders` | `integer` (int64) | 해당 일자에 전송을 시작한 고유 송신자 주소 수. | | `unique_receivers` | `integer` (int64) | 해당 일자에 전송을 받은 고유 수신자 주소 수. | | `mint_raw_amount` | `string` (decimal) | 해당 일자에 발행된 총 원시 토큰 수량. | | `burn_raw_amount` | `string` (decimal) | 해당 일자에 소각된 총 원시 토큰 수량. | | `net_supply_change` | `string` (decimal) | 해당 일자의 순공급량 변화 (부호 있는 10진수 문자열, 음수일 수 있음). | | `holder_count` | `integer` (int64) | 총 보유자 주소 수. | | `top10_holder_share_bps` | `integer` | 상위 10개 보유자의 베이시스 포인트 기준 지분 (0–10000, 1 bps = 0.01%). | | `dex_swap_count` | `integer` (int64) | 해당 일자에 이 토큰이 포함된 DEX 스왑 횟수. | | `dex_raw_volume` | `string` (decimal) | 해당 일자의 총 DEX 원시 거래량. | | `refreshed_at` | `string` (timestamp) | 이 일별 레코드가 마지막으로 갱신된 ISO-8601 UTC 타임스탬프. | ### 토큰 메타데이터 필드 (StockToken) 단일 토큰을 쿼리할 때 외부 `data` 객체는 컨트랙트 메타데이터와 최근 일별 지표를 포함합니다: | 필드 | 타입 | 설명 | | ----------------- | ---------------------------- | --------------------------------------------------------- | | `address` | `string` (address) | 토큰 컨트랙트 주소. | | `symbol` | `string` | 토큰 심볼. | | `name` | `string` | 전체 토큰 이름. | | `decimals` | `integer` 또는 `null` | 토큰 데시멀 (0–255), 또는 제공되지 않는 경우 `null`. | | `created_block` | `integer` (int64) | 토큰 컨트랙트가 생성된 블록 번호. | | `created_tx_hash` | `string` (hash) | 컨트랙트 생성 트랜잭션 해시, `0x` 접두사가 붙은 64자리 소문자 16진수 문자. | | `factory` | `string` (address) | 팩토리 컨트랙트 주소. | | `creator` | `string` (address) 또는 `null` | 생성자 주소, 또는 제공되지 않는 경우 `null`. | | `mint_address` | `string` (address) 또는 `null` | 발행 주소, 또는 제공되지 않는 경우 `null`. | | `burn_address` | `string` (address) 또는 `null` | 소각 주소, 또는 제공되지 않는 경우 `null`. | | `daily` | `array` | 최근 일별 지표(`StockDailyMetric`) 배열, 최대 30일, 날짜 내림차순(최신순) 정렬. | | `refreshed_at` | `string` (timestamp) | 토큰 메타데이터가 마지막으로 갱신된 ISO-8601 UTC 타임스탬프. | ### 인코딩 규칙 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}`을 호출하는 시나리오를 활성 메서드 가중치에 따라 평가한 것입니다: - **호출당 메서드 가중치:** `data.stock`을 1회 호출할 때마다 15 CU (정가 100만 회당 $1.50)를 소모합니다. - **매일 50개 토큰 지표 갱신**(토큰당 `GET /{chain}/stocks/{token}` 1회 호출, 일일 50회 호출): 일일 소모량은 750 CU입니다. 30일 주기에 걸쳐 총 1,500회 호출되어 22,500 CU를 소모하며, 무료 할당량(30,000,000 CU)의 약 <0.1%입니다. 무료 할당량을 초과하거나 유료 플랜을 이용하는 경우 정가 기준 총 사용 요금은 월 약 <$0.01입니다. ## 시작하기 및 업그레이드 무료 할당량은 개발, 테스트 및 가벼운 워크로드에 이상적입니다. 트래픽이 확장되어 더 높은 동시성이나 더 많은 연산 단위가 필요한 경우 콘솔 [결제 페이지](https://console.blockvectra.com/billing/)에서 온체인 충전을 진행하세요. 온체인에서 확인되고 적립되면 계정 전반의 초당 호출 수 제한이 해제됩니다. 각 키는 [JSON-RPC 문서](https://docs.blockvectra.com/en/api/json-rpc/#method-policy)에 설명된 대로 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를 생성하세요.