# 使用 Data API 查詢代幣化股票的每日鏈上指標 > Source: https://docs.blockvectra.com/zh-hant/guides/stocks/ > 資料源自公開鏈上記錄，僅供參考，不構成投資建議。 Robinhood Chain 上的合約部署與事件監聽請參考 [RPC 與 WebSocket 指南](https://docs.blockvectra.com/en/guides/robinhood-chain/)。 ## 三步驟任務：查詢 Robinhood Chain 上的股票活動 找出最新有記錄的 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` 是十六進位的最新區塊編號。此公開 RPC 呼叫無需 key；步驟 3 中的 Data API 查詢需要 key。 ### 2. 為同一條鏈建立 key [登入控制台並開啟 API Keys 頁面](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-stocks-task)。建立 key 並儲存對話方塊中顯示的 secret。同一把 key 可用於 `robinhood_mainnet` 上的 JSON-RPC 與 Data API。 對於透過 HTTP 且不使用瀏覽器的 AI Agent，請參考[程式化註冊指南](https://docs.blockvectra.com/en/guides/programmatic-signup/?ref=docs-stocks-task)，使用以太坊錢包簽名註冊並建立 key；切勿要求使用者將 key 貼入對話中。 ### 3. 使用你的 key 查詢股票活動 將下方的 `replace-with-your-key` 替換為你儲存的 key，然後在伺服器或本機終端機中執行該指令。省略 `day` 預設選擇最新有記錄的日期；`limit=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 日曆日期。省略時，預設為最新有記錄的日期（若未記錄任何活動，則回傳 `200` 且 `data: []`）。若提供但不是有效的 `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 Chain 上的完整入門範本：[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()) ``` ### 回應結構說明 回應結構為 `StockDailyListEnvelope`，包含 `data` 與 `meta`： * `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 個小寫十六進位字元）。無效的地址格式回傳 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()) ``` ### 回應結構說明 回應結構為 `StockTokenEnvelope`，包含 `data` 與 `meta`： * `data`（物件）：一個 `StockToken` 物件，包含代幣合約中繼資料（`address`、`symbol`、`name`、`decimals`、`created_block`、`created_tx_hash`、`factory`、`creator`、`mint_address`、`burn_address`、`refreshed_at`）以及近期每日指標陣列 `daily`。 * `daily`（陣列）：近期每日指標陣列（`StockDailyMetric`），最多 30 天，按日期降序排列（最新在前）。每個每日項目共用與上述排行榜相同的指標結構定義（不含多餘的 `token`、`symbol` 與 `name` 欄位）。 * `meta`（物件）：與排行榜回應一致的鏈中繼資料物件。 ## 關鍵回傳欄位說明 ### 每日指標欄位（StockDaily 與 StockDailyMetric） 排行榜與單一代幣歷史每日項目均包含以下核心欄位： | 欄位 | 類型 | 說明 | | ------------------------ | -------------------- | ------------------------------------------------------- | | `day` | `string` (date) | 格式化為 `YYYY-MM-DD` 的 UTC 彙整日期。 | | `token` | `string` (address) | 代幣合約地址（僅出現在排行榜 `StockDaily` 中），帶 `0x` 前綴的 40 位小寫十六進位字元。 | | `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) | 該日的淨供應量變化（有符號十進位字串，可能為負數）。 | | `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 位小寫十六進位字元。 | | `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 數值，也絕不使用科學記號或十六進位標記。這可防止 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 數值。 * **二進位與十六進位值**：地址為 `0x` 後接 40 個小寫十六進位字元；雜湊為 `0x` 後接 64 個小寫十六進位字元。所有回傳的十六進位值嚴格為全小寫。 * **時間戳與日期**：時間戳（例如 `refreshed_at`）使用 `YYYY-MM-DDTHH:MM:SSZ`（秒級精度的 ISO-8601 UTC）。每日彙整（`day`）使用純日曆日期（`YYYY-MM-DD`）。 ## 用量估算（每天重新整理 50 個代幣） Data API 查詢依據平台方法權重消耗計算單位（CU）。以下估算評估了 50 個代幣每天各呼叫一次 `GET /{chain}/stocks/{token}` 的情境，對照有效的方法權重進行評估： - **單次呼叫計費權重：** 每次呼叫 `data.stock` 消耗 15 CU（標價每百萬次 $1.50）。 - **每天重新整理 50 個代幣指標**（各呼叫一次 `GET /{chain}/stocks/{token}`，每天 50 次呼叫）：單日消耗 750 CU；一個 30 天週期累計呼叫 1,500 次，消耗 22,500 CU，佔免費額度（30,000,000 CU）的 <0.1%。超出免費額度或在付費方案下，全量用量按標價約每月 <$0.01。 ## 開始使用與升級 免費額度非常適合開發、測試與輕量工作負載。當你的流量擴大並需要更高的並行量或更多計算單位時，可在控制台[帳單頁面](https://console.blockvectra.com/billing/)進行鏈上儲值；一旦在鏈上確認並入帳，帳戶整體的每秒呼叫次數上限即被移除。每個 key 仍受 CU 速率與突發限制約束，如 [JSON-RPC 文件](https://docs.blockvectra.com/en/api/json-rpc/#method-policy)所述。任何未使用的免費額度仍會保留在你的額度中，並且仍可使用。有關目前的費率與計費單位，請參閱[定價頁面](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。