Full instrument directory — the table you cache on startup to resolve symbols everywhere else.

Every other endpoint assumes you already know which canonical symbols exist. This is that source of truth. Pull the full list once at app start, cache it, and diff it on the next cold start. Filter by `base`, `kind`, or prefix `search` to keep responses small during interactive exploration.

Query parameters

All query parameters are optional unless marked required.

Response shape

Always wrapped in the standard envelope. Nullable fields are explicitly marked — treat missing numeric data as a real data-source gap, not as an error.

// Wrapped in the standard envelope:
// {
//   data: /* shape below */,
//   meta?: { total?: number; limit?: number; offset?: number; ... }
// }

Array<{
  id: number;
  canonicalSymbol: string;      // "BTCUSDT"
  base: string;                 // "BTC"
  quote: string;                // "USDT"
  kind: "perp" | "spot" | "future" | "option";
  expiry: string | null;        // present on futures/options
  strike: number | null;        // options only
  optionType: "C" | "P" | null; // options only
}>

Example

Copy the curl, replace YOUR_KEY with a real key from your dashboard, and run.

curl -sS "http://localhost:3000/api/v1/symbols?base=BTC&kind=perp&limit=5"

{
  "data": [
    {
      "id": 12,
      "canonicalSymbol": "BTCUSDT",
      "base": "BTC",
      "quote": "USDT",
      "kind": "perp",
      "expiry": null,
      "strike": null,
      "optionType": null
    },
    {
      "id": 14,
      "canonicalSymbol": "BTCUSD_PERP",
      "base": "BTC",
      "quote": "USD",
      "kind": "perp",
      "expiry": null,
      "strike": null,
      "optionType": null
    }
  ],
  "meta": { "total": 2, "limit": 5, "offset": 0 }
}

Notes

• Anonymous-tier friendly — no key required.
• For very large caches, page through with `limit=5000` then `offset=5000,10000,…` until you get a short page back.