Market API

Market API 为 StockKit 增加了时间维度：直接从链上采样的 OHLC 价格 K 线、单代币实时市场统计，以及推送到你 Webhook 的一次性价格提醒。目前还没有其他 API 为 Robinhood Chain 上的代币化股票提供 K 线数据。

价格来自链上事实，而不是数据供应商：StockKit 每 5 分钟读取每个已上线股票代币最深的 Uniswap v3 TOKEN/USDG 池的当前价格，并为每个代币记录一个样本。K 线、 24 小时涨跌幅和提醒判断都基于这些样本。

价格历史（K 线）

curl "https://api.stockkit.dev/v1/history/NVDA?interval=1h&limit=24"

{
  "symbol": "NVDA",
  "interval": "1h",
  "source": "uniswap-v3 TOKEN/USDG pool price, sampled every 5 minutes",
  "historySince": "2026-09-16T09:05:00.000Z",
  "candles": [
    {
      "t": "2026-09-16T09:00:00.000Z",
      "open": 176.412031,
      "high": 176.998702,
      "low": 176.114319,
      "close": 176.83019,
      "ticks": 11
    }
  ]
}

interval：5m、15m、1h（默认）、4h 或 1d
limit：最多返回的 K 线数量，取最新窗口，1 到 300（默认 100）
ticks：这根 K 线聚合了多少个 5 分钟样本
historySince：该代币第一条记录的时间。历史数据从 2026 年 9 月 16 日开始累积，之前没有回填数据。

同样支持按次付费调用：GET /v1/x402/history/:symbol（$0.01），参见 x402 API。

代币统计

一次调用返回链上关于某个代币的全部信息：供应量、每个 TOKEN/USDG 池的费率档位和 TVL，以及链上 DEX 价格与乘数调整后股票报价的对比。

curl https://api.stockkit.dev/v1/stats/NVDA

{
  "symbol": "NVDA",
  "name": "NVIDIA • Robinhood Token",
  "tokenAddress": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
  "chainId": 4663,
  "supply": { "totalTokens": "68204.51", "valueUsd": "12063228.11" },
  "price": {
    "dexUsd": "176.830190",
    "equityTokenUsd": "176.905000",
    "underlyingMidUsd": "176.905000",
    "multiplier": "1.000000000000000000",
    "dexPremiumPct": "-0.042",
    "change24hPct": "1.31",
  },
  "pools": [
    {
      "pool": "0x...",
      "feeTier": 500,
      "price": "176.830190",
      "usdgLiquidity": "412083.12",
      "tokenLiquidity": "2214.71",
      "tvlUsd": "803731.55"
    }
  ],
  "asOf": "2026-09-16T10:15:00.000Z"
}

最有意思的数字是 dexPremiumPct：代币在链上相对真实股票报价的溢价或折价。正数表示溢价，负数表示折价。change24hPct 在该代币累积满一天历史数据之前为 null。

价格提醒

注册一个阈值和一个 HTTPS Webhook；StockKit 每 5 分钟用链上 DEX 价格检查一次，价格穿越阈值时调用你一次。

curl -X POST https://api.stockkit.dev/v1/alerts \
  -H 'content-type: application/json' \
  -d '{
    "symbol": "NVDA",
    "condition": "above",
    "price": 180,
    "webhookUrl": "https://example.com/hooks/stockkit"
  }'

{
  "id": "0f2c7a8e-...",
  "symbol": "NVDA",
  "condition": "above",
  "price": 180,
  "status": "active",
  "expiresAt": "2026-10-16T10:15:00.000Z",
  "secret": "f3b1..."
}

请保存好 secret：它是这条提醒唯一的凭证。用它查询或取消：

curl "https://api.stockkit.dev/v1/alerts/ALERT_ID?secret=SECRET"
curl -X DELETE "https://api.stockkit.dev/v1/alerts/ALERT_ID?secret=SECRET"

提醒触发时，你的 Webhook 会收到一次 POST：

{
  "type": "price_alert",
  "id": "0f2c7a8e-...",
  "symbol": "NVDA",
  "condition": "above",
  "threshold": 180,
  "price": 180.412031,
  "source": "uniswap-v3 TOKEN/USDG",
  "firedAt": "2026-09-17T14:35:00.000Z"
}

请求头 x-stockkit-alert-secret 携带你的提醒密钥，接收端可以据此验证调用确实来自 StockKit。

规则说明：

提醒是一次性的：触发一次后状态变为 fired，仍可查询。
从未触发的提醒会在 30 天后过期。
webhookUrl 必须是公网 HTTPS 地址。测试期间有活跃提醒总量上限，且每个主机名最多 25 条，避免单个接收方挤占其他人。
判断粒度为 5 分钟，基于 DEX 价格，因此在一个采样窗口内回落的瞬时波动不会触发。

使用 SDK

import { StockKit } from "@stockkit/sdk"

const stockkit = new StockKit()

const { candles } = await stockkit.history.get("NVDA", { interval: "1h", limit: 24 })

const stats = await stockkit.stats.get("NVDA")
console.log(stats.price.dexPremiumPct) // DEX price vs the equity quote, percent

const alert = await stockkit.alerts.create({
  ticker: "NVDA",
  condition: "above",
  price: 250,
  webhookUrl: "https://example.com/hooks/stockkit",
})

// The secret is only returned on create; it reads and deletes the alert
await stockkit.alerts.get(alert.id, alert.secret)
await stockkit.alerts.delete(alert.id, alert.secret)

MCP 工具

MCP 服务器以 get_history 和 get_stats 工具暴露同样的数据，Cursor、Claude Code 及任何 MCP 客户端都可以原生绘图和比较代币。