Skip to content
StockKitStockKit Docs

Market API

The Market API adds a time dimension to StockKit: OHLC price candles sampled from the chain itself, live per-token market stats, and one-shot price alerts delivered to your webhook. No other API offers candles for tokenized stocks on Robinhood Chain.

Prices come from onchain truth, not a data vendor: every 5 minutes StockKit reads the current price of the deepest Uniswap v3 TOKEN/USDG pool for every listed stock token and records one sample per token. Candles, the 24h change, and alert checks are all built from those samples.

Price history (candles)

Section titled “Price history (candles)”
Terminal window
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 (default), 4h, or 1d
  • limit: max candles, newest window, 1 to 300 (default 100)
  • ticks: how many 5-minute samples the candle aggregates
  • historySince: the first recorded sample for the symbol. History accrues from September 16, 2026; there is no backfill before that date.

Also available pay-per-call at GET /v1/x402/history/:symbol ($0.01), see the x402 API.

Token stats

Section titled “Token stats”

Everything the chain knows about one token in a single call: supply, every TOKEN/USDG pool with its fee tier and TVL, and the onchain DEX price compared with the multiplier-adjusted equity quote.

Terminal window
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"
}

The interesting number is dexPremiumPct: how rich or cheap the token trades onchain relative to the real equity quote. Positive means the token trades at a premium; negative means a discount. change24hPct is null until a day of history has accrued for the symbol.

Price alerts

Section titled “Price alerts”

Register a threshold and an HTTPS webhook; StockKit checks it against the onchain DEX price every 5 minutes and calls you once when it crosses.

Terminal window
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..."
}

Keep the secret: it is the only credential for the alert. Check or cancel with it:

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

When the alert fires, your webhook receives one 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"
}

The request carries your alert secret in the x-stockkit-alert-secret header, so your receiver can verify the call really came from StockKit.

Rules of the road:

  • Alerts are one-shot: they fire once, then stay readable as fired.
  • Alerts expire after 30 days if they never fire.
  • webhookUrl must be public HTTPS. During the beta there is a global cap on active alerts and a per-host cap of 25, so a single receiver cannot crowd everyone else out.
  • Evaluation granularity is 5 minutes, against the DEX price, so a spike that reverts within one sample window will not trigger.

With the SDK

Section titled “With the 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 tools

Section titled “MCP tools”

The MCP server exposes the same data as the get_history and get_stats tools, so Cursor, Claude Code, and any MCP client can chart and compare tokens natively.