Get an instrument

GET/instruments/{symbol}

Returns one instrument, with the coverage your plan can reach on it. Call it to check a symbol and its coverage before you start a run.

Scope	Heavy call	Long poll	CLI
`scripts:read`	No	No	None

Guidance

URL-encode the colon in a canonical symbol: HYPERLIQUID%3ABTC. A short symbol such as BTC needs no encoding.
A short symbol that matches several instruments answers 404 unknown_instrument, and the message lists the canonical symbols to choose from. Retry with one of them.
Use coverage.start as the earliest from for Create a run. Starting a window on it avoids out_of_coverage.
Runs and events resolve instrument with the same lookup, so a symbol that resolves here resolves there too. There a miss answers 400 unknown_instrument instead of 404.

Path parameters

Name	Type	Description
`symbol`	string	Canonical or short symbol, URL-encoded: `HYPERLIQUID%3ABTC` or `BTC`

Response

200 with an Instrument.

Status codes

Status	Code	Meaning
`200`	-	The instrument
`404`	`unknown_instrument`	No runnable instrument has that symbol, or a short symbol matches several. The message lists the canonical symbols to choose from

Example request

curl https://api.chartnaut.com/v1/instruments/HYPERLIQUID%3ABTC \
  -H "Authorization: Bearer cn_live_XXXX"

Example response

200 OK

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

404 Not Found

{
  "error": {
    "code": "unknown_instrument",
    "message": "no instrument \"BTCUSDT\"; search with GET /instruments?q="
  }
}

From the CLI

The CLI has no command that reads one instrument; chartnaut instruments BTC finds it through Search instruments instead.