Developer docs

Read the API in one page.

Introduction & envelope

Every dataset seekingdata serves is browsable from /catalog, for example crypto spot reference_price from binance, entityBTC-USD. Every data response, regardless of what it covers, is wrapped in the same three-part envelope:

{
  "data": "the requested payload: shape depends on the metric (scalar / object / series)",
  "meta": {
    "as_of": "2026-07-09T12:00:00.600Z",
    "venues": [
      "binance",
      "coinbase"
    ],
    "staleness_ms": 100,
    "confidence": 0.98
  },
  "provenance": {
    "sources": [
      {
        "venue": "binance",
        "ts": "2026-07-09T12:00:00.100Z"
      }
    ],
    "method": "outlier-trimmed cross-venue median"
  }
}

data: the payload itself; shape depends on the metric's value_shape (scalar, object, or series).
meta: as_of, venues, staleness_ms, a computed confidence (0 to 1); series responses add has_more, next_cursor, truncated, returned.
provenance: exact sources, timestamps, and the derivation method behind the number.

Authentication

Sign up is self-serve: create an account with Google or GitHub from/signup and you're in, no invite required. New accounts start on the free plan. Navigation endpoints (catalog browsing) are public; data calls require an API key sent as either:

Authorization: Bearer $SEEKINGDATA_KEY

# or
X-API-Key: $SEEKINGDATA_KEY

Keys are long, prefixed random strings, shown once at creation (from /account), and are stored server-side as a salted hash. Losing one means regenerating, not recovering. The $SEEKINGDATA_KEY in the examples on this page stands in for your own free-tier key: create one in a minute at signup, no card required. The catalog and navigation endpoints below need no key at all.

Navigation endpoints

Public, no key required. These describe the catalog; they never return market data.

GET /v1/categoriesAll top-level categories.

GET /v1/categories/:catOne category's detail.

GET /v1/categories/:cat/productsA category's products.

GET /v1/categories/:cat/products/:prodOne product's detail, including its metrics.

GET /v1/categories/:cat/products/:prod/metricsA product's metrics.

GET /v1/categories/:cat/products/:prod/sourcesA product's sources.

GET /v1/categories/:cat/products/:prod/entitiesA product's entities (if statically enumerable).

GET /v1/catalogThe whole tree in one call: what this site renders from.

GET /v1/sourcesThe full source registry.

The data endpoint

One shape for every metric:

GET /v1/data/{category}/{product}/{metric}?entity=&source=&fields=&format=table&cursor=&max_response_tokens=

entity selects the instrument (e.g. BTC-USD); sourcefilters to one venue (omit for the combined/cross-venue value, where the metric supports one). A request for a planned metric returns 404 witherror_category: "not_yet_available", never a silent empty body.

Worked examples, one per live metric:

crypto/spot/reference_pricefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/reference_price?entity=BTC-USD"

crypto/spot/change_24hfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/change_24h?entity=BTC-USD"

crypto/spot/range_24hfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/range_24h?entity=BTC-USD"

crypto/spot/vwap_24hfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/vwap_24h?entity=BTC-USD"

crypto/spot/realized_volatility_24hfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/realized_volatility_24h?entity=BTC-USD"

crypto/spot/trade_count_24hfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/trade_count_24h?entity=BTC-USD"

crypto/spot/ohlcvfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/ohlcv?entity=BTC-USD"

crypto/spot/tradesbasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/spot/trades?entity=BTC-USD"

crypto/options/chainpro+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/options/chain?entity=BTC"

crypto/options/implied_vol_indexpro+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/options/implied_vol_index?entity=BTC"

crypto/options/put_call_oi_ratiopro+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/options/put_call_oi_ratio?entity=BTC"

crypto/futures/fundingultra+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/futures/funding?entity=BTC-USD"

crypto/futures/mark_priceultra+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/futures/mark_price?entity=BTC-USD"

crypto/futures/basisultra+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/futures/basis?entity=BTC-USD"

crypto/etf_flows/net_flowfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/etf_flows/net_flow?entity=IBIT"

crypto/etf_flows/cumulative_net_flowfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/etf_flows/cumulative_net_flow?entity=IBIT"

crypto/etf_flows/flow_by_etffree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/etf_flows/flow_by_etf?entity=IBIT"

crypto/network/market_capfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/network/market_cap?entity="

crypto/network/hashratefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/network/hashrate?entity="

crypto/network/difficultyfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/network/difficulty?entity="

crypto/network/tx_countfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/crypto/network/tx_count?entity="

fx/spot/reference_ratefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/fx/spot/reference_rate?entity=EUR-USD"

fx/spot/change_24hfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/fx/spot/change_24h?entity=EUR-USD"

weather/observations/temperaturefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/weather/observations/temperature?entity=nyc"

weather/observations/wind_speedfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/weather/observations/wind_speed?entity=nyc"

weather/observations/precipitationfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/weather/observations/precipitation?entity=nyc"

sports/tennis/match_resultbasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/sports/tennis/match_result?entity=atp"

sports/tennis/live_scorebasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/sports/tennis/live_score?entity=atp"

sports/football/match_resultbasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/sports/football/match_result?entity=eng.1"

sports/football/live_scorebasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/sports/football/live_score?entity=eng.1"

sports/basketball/match_resultbasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/sports/basketball/match_result?entity=nba"

sports/basketball/box_scorebasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/sports/basketball/box_score?entity=nba"

sports/basketball/live_scorebasic+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/sports/basketball/live_score?entity=nba"

absurd_cosmos/space_weather/planetary_kpfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_cosmos/space_weather/planetary_kp?entity="

absurd_cosmos/restless_earth/quakes_last_hourfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_cosmos/restless_earth/quakes_last_hour?entity="

absurd_cosmos/restless_earth/largest_quake_todayfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_cosmos/restless_earth/largest_quake_today?entity="

absurd_cosmos/off_world/humans_in_spacefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_cosmos/off_world/humans_in_space?entity="

absurd_cosmos/solar_cycle/sunspot_numberfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_cosmos/solar_cycle/sunspot_number?entity="

absurd_civic/leviathan_ledger/red_tape_outputfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_civic/leviathan_ledger/red_tape_output?entity="

absurd_civic/city_nervous_system/rat_sightings_todayfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_civic/city_nervous_system/rat_sightings_today?entity="

absurd_economy/treasury/national_debtfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_economy/treasury/national_debt?entity="

absurd_economy/treasury/avg_interest_ratefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_economy/treasury/avg_interest_rate?entity="

absurd_earth/weather/temperaturefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_earth/weather/temperature?entity=nyc"

absurd_earth/tides/water_levelfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/absurd_earth/tides/water_level?entity=the-battery"

stocks/indices/sp500free+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/stocks/indices/sp500?entity="

stocks/indices/nasdaqfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/stocks/indices/nasdaq?entity="

commodities/energy/wti_crudefree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/commodities/energy/wti_crude?entity="

commodities/energy/natural_gasfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/commodities/energy/natural_gas?entity="

commodities/metals/copperfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/commodities/metals/copper?entity="

commodities/metals/goldfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/commodities/metals/gold?entity="

commodities/metals/silverfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/commodities/metals/silver?entity="

macro/money/m2_money_supplyfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/macro/money/m2_money_supply?entity="

macro/money/m2_growth_yoyfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/macro/money/m2_growth_yoy?entity="

macro/prices/cpifree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/macro/prices/cpi?entity="

macro/prices/cpi_inflation_yoyfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/macro/prices/cpi_inflation_yoy?entity="

medical/literature/publication_countfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/medical/literature/publication_count?entity=neoplasms"

medical/guidelines/guideline_downloadsfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/medical/guidelines/guideline_downloads?entity="

medical/radiology/article_countfree+

curl -H "Authorization: Bearer $SEEKINGDATA_KEY" \
  "https://api.seekingdata.dev/v1/data/medical/radiology/article_count?entity=abdomen"

Legacy single-metric routes (price, OHLCV, trades, options: one path segment per metric, no /data/ prefix) still work. They call the exact same resolver as the generic endpoint, so responses never drift.

Plans & limits

Rate limits are per key, per minute, enforced with a token bucket. The effective gate for a metric is max(product.min_tier, metric.min_tier).

Plan	Rate limit	Unlocks
free	10 req/min	spot reference_price, spot ohlcv
basic	60 req/min	+ spot trades
pro	300 req/min	+ options chain
ultra	1200 req/min	+ everything

Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers, so an agent can back off before it gets throttled instead of after.

Pay-per-call for agents (x402)

Every priced data endpoint also speaks x402, the open HTTP-402 payment standard. An AI agent can consume the data with no account and no API key: it pays per call in USDC, settled on-chain by an x402 facilitator. The seller holds no key and never takes custody of funds. API-key and subscription callers bypass x402 entirely and keep their normal plan gating — this path is purely for agents that arrive with no account.

The handshake is three steps over standard HTTP headers:

Request the endpoint with no key. It answers 402 Payment Required.
The 402 carries a PAYMENT-REQUIRED header (base64 PaymentRequired), mirrored in the JSON body: the amount, asset, network, and resource.
Sign a USDC payment and retry with a PAYMENT-SIGNATURE header (base64 PaymentPayload). On success you get 200 OK with a PAYMENT-RESPONSE receipt header and the normal envelope.

The 402 challenge (also base64-encoded in the PAYMENT-REQUIRED header):

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "maxAmountRequired": "10000",
      "resource": "/v1/data/crypto/spot/reference_price?entity=BTC-USD",
      "description": "crypto/spot/reference_price · latest read"
    }
  ],
  "extensions": {
    "bazaar": {
      "info": {
        "input": {
          "entity": "BTC-USD"
        },
        "output": "seekingdata envelope: { data, meta, provenance }",
        "example": "/v1/data/crypto/spot/reference_price?entity=BTC-USD"
      }
    }
  }
}

Trigger the challenge yourself — a keyless request to any priced endpoint returns it:

curl -i "https://api.seekingdata.dev/v1/data/crypto/spot/reference_price?entity=BTC-USD"

Read	Price (USDC)	Atomic (6-dec)
Latest / stat read	$0.01	`10000`
Time-series read (`?series=true`)	$0.02	`20000`

Network & asset. Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), asset USDC (mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v), 6-decimal atomic units.

Auto-discovery. GET /.well-known/x402 is a machine-crawlable manifest of every priced endpoint. Each 402 also carries a Bazaar extension (extensions.bazaar.info) with the input/output schema and an example, so an agent can understand a dataset before paying for it.

Discovery is free. /health, /v1/catalog,/openapi.json, /llms.txt, and /v1/billing/pricesare never priced, so an agent can browse and price the catalog before it decides to pay.

Errors

Failures come back as application/problem+json (RFC 9457): an agent can branch on error_category in code, not by parsing prose.

401 unauthorized: missing or invalid key

{
  "type": "https://seekingdata.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid API key."
}

Agent reaction: stop and prompt for a key. Retrying won't help.

403 tier_forbidden: key valid, plan too low

{
  "type": "https://seekingdata.dev/errors/tier-forbidden",
  "title": "Tier forbidden",
  "status": 403,
  "detail": "crypto/options/chain requires the pro plan or higher.",
  "error_category": "tier_forbidden"
}

Agent reaction: surface the upgrade path (/account) instead of retrying.

429 rate_limit: over the plan's requests/min

{
  "type": "https://seekingdata.dev/errors/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "10 requests/min exceeded for the free plan.",
  "error_category": "rate_limit",
  "retryable": true,
  "retry_after": 42
}

Agent reaction: back off for retry_after seconds, then retry. retryable: true makes this safe to automate.

A request for a planned metric returns 404 with error_category: "not_yet_available", distinct from a routing 404, so an agent knows the path is right and the data just isn't collected yet.

Pagination & fields

Series-shaped metrics (candles, trades) support:

Param	Effect
`fields`	Comma-separated allowlist: trims the response to just the columns you need.
`format=table`	Columnar `{columns, rows}` instead of an array of objects, smaller on the wire for wide series.
`cursor`	Opaque pagination cursor from `meta.next_cursor`.
`max_response_tokens`	Truncates to whole rows (never mid-object) and sets `meta.truncated` + a one-line `meta.hint`.

MCP

The same catalog and envelope are exposed as typed MCP tools:

claude mcp add seekingdata --env SEEKINGDATA_API_KEY=<key> -- npx -y @seekingdata/mcp

browse_catalog and get_metric are the generic navigation and data escape hatches; reference_price, ohlcv,recent_trades, and option_chain are crypto conveniences that call get_metric internally. Missing, invalid, or under-tier keys come back as typed, actionable MCP errors, not a stack trace.

Machine-readable

GET /openapi.jsonOpenAPI 3.1 contract, generated from the live catalog + resolver registry: includes the auth scheme and 401/403/429 response shapes.

GET /llms.txtA plain-text orientation doc for LLMs that land on the API without an MCP connection.

GET /.well-known/seekingdata.jsonThis site's agent descriptor: catalog summary, MCP install command, contact.