Search instruments

GET/instruments

Returns the instruments you can run on, filtered by text and category, each with the coverage your plan can reach. Call it to turn what a person typed into a symbol a run accepts.

Scope	Heavy call	Long poll	CLI
`scripts:read`	No	No	`chartnaut instruments`

Guidance

Every endpoint that takes an instrument accepts the canonical symbol, such as HYPERLIQUID:BTC, or the short one, such as BTC, in any letter case. Store the canonical symbol: runs and events report instruments by it, and a short symbol can match more than one instrument.
Check coverage.start before you pick a window. A run window that ends before it is refused with out_of_coverage, and one that starts before it is moved forward.
Check order_flow before running a footprint, delta or other volume-tape script. Where it is false, those scripts have no tape to read.
With q, the best cursor plus limit matches are picked first and category filters those, so a page with both can come back shorter than limit while more matches exist. To list a whole category, leave q out.
This endpoint returns metadata only, never candles or tape.

Query parameters

Name	Type	Required	Default	Description
`q`	string	No	None	Matches symbol, short symbol, name and search aliases, best match first. Without it, every instrument comes back in catalogue order
`category`	string	No	None	A market category, such as `crypto`, `fx`, `index` or `commodities`. An unknown value returns an empty page
`limit`	integer	No	50	Most 500
`cursor`	string	No	None	From the previous page's `next_cursor`

Response

200 with a page whose data is an array of Instrument.

Status codes

Status	Code	Meaning
`200`	-	A page of instruments. `data` is `[]` when nothing matches
`500`	`internal`	The instrument catalogue could not be read. Retry

Example request

curl "https://api.chartnaut.com/v1/instruments?q=eth&category=crypto&limit=1" \
  -H "Authorization: Bearer cn_live_XXXX"

Example response

200 OK

{
  "data": [
    {
      "symbol": "HYPERLIQUID:ETH",
      "short": "ETH",
      "name": "Ethereum Perpetual (Hyperliquid)",
      "category": "crypto",
      "tick_size": 0.1,
      "contract_multiplier": 1,
      "order_flow": true,
      "coverage": {
        "start": "2025-03-22T10:50:00Z",
        "end": "2026-09-26T09:41:00Z"
      }
    }
  ],
  "next_cursor": "1"
}

500 Internal Server Error

{
  "error": {
    "code": "internal",
    "message": "Internal error. Retry; if it persists contact [email protected]."
  }
}

From the CLI

chartnaut instruments eth --category crypto --limit 1

The CLI prints one row per instrument with its coverage dates; --json prints this response. Command reference