> ## Documentation Index > Fetch the complete documentation index at: https://v3.docs.derive.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Instrument Names > How spot, perp, and option instruments are named on the Derive v3 API. Every tradeable market on the Derive v3 API is identified by a human-readable `instrument_name` string. The same string is used everywhere an instrument is referenced: order parameters, RFQ legs, ticker and orderbook queries, and real-time subscription channels. Names are **case-sensitive and uppercase**. Each name encodes the market's currency and, for options, its expiry, strike, and type. ## Formats `-` `-PERP` `---` | Type | Format | Example | | ------------- | ---------------------------------- | --------------------- | | Spot | `-` | `ETH-USDC` | | Perpetual | `-PERP` | `ETH-PERP` | | Option (call) | `---C` | `ETH-20240914-2400-C` | | Option (put) | `---P` | `ETH-20240914-2400-P` | ### Spot A spot instrument names its base and quote currency, separated by a hyphen — for example `ETH-USDC`. The quote currency must match the settlement (cash) currency of the market's risk universe. ### Perpetual A perpetual is the currency ticker followed by the literal suffix `-PERP`, for example `BTC-PERP`. ### Option An option name has four segments: The underlying ticker, e.g. `ETH`. The expiry date as an 8-digit `YYYYMMDD`. Options settle at **08:00 UTC** on that date. `20240914` is 14 September 2024. The strike price. Integer strikes have no decimal (`2400`). Fractional strikes use an underscore as the decimal point with trailing zeros trimmed (`2400_5` = 2400.5). Strikes finer than 1e-6 are rejected. `C` for a call, `P` for a put. So `ETH-20240914-2400-C` is an ETH call struck at 2400 expiring 08:00 UTC on 14 September 2024. ## Risk universe suffix An instrument name may carry an optional trailing `-` segment, where the id is an unsigned integer — for example `ETH-USDC-42` or `ETH-PERP-42`. This disambiguates markets on the same currency that belong to different risk universes. For each name shape, exactly one instrument may omit the suffix (assigned first-come, first-served). All others must include it. When present, the id is validated against the instrument's configured risk universe. ## Querying instruments Instrument names are assigned by the exchange, not constructed by clients — the authoritative list comes from the market-data methods. Filter by type using the `instrument_type` enum, whose values are: | `instrument_type` | Market type | | ----------------- | ----------- | | `erc20` | Spot | | `perp` | Perpetual | | `option` | Option | ```typescript TypeScript (SDK) theme={null} import { DeriveClient } from '@derivexyz/derive-ts'; // Public market data needs no wallet, connect, or login. const client = new DeriveClient({ network: 'mainnet' }); const { instruments } = await client.marketData.getInstruments({ instrumentType: 'option', currency: 'ETH', expired: false, }); ``` ```python Python (SDK) theme={null} # Coming soon. ``` ```rust Rust (SDK) theme={null} // Coming soon. ``` ```bash cURL theme={null} curl -X POST https://api.derive.xyz/v3/public/get_all_instruments \ -H "Content-Type: application/json" \ -d '{ "instrument_type": "option", "currency": "ETH", "expired": false }' ``` ```json Request theme={null} { "id": 1, "method": "public/get_all_instruments", "params": { "instrument_type": "option", "currency": "ETH", "expired": false } } ``` ```json Response theme={null} { "id": 1, "result": { "instruments": [ { "instrument_name": "ETH-20240914-2400-C", "instrument_type": "option", "is_active": true } ] } } ``` Use `public/get_all_live_instruments` for only currently tradeable markets, or `public/get_instrument` for the full spec of a single name. See the **API Reference** tab for the complete response shapes. ## Where instrument names are used Once you have a name, use it verbatim wherever an instrument is referenced: * **Order and RFQ parameters** — `instrument_name` on `private/order`, `private/order_quote`, and each RFQ leg. * **Market data** — `public/get_ticker`, `public/get_instrument`, and related lookups. * **Real-time channels** — the name is a path segment, e.g. `orderbook.{instrument_name}.{group}.{depth}`, `ticker_slim.{instrument_name}.{interval}`, and `trades.{instrument_name}`. Trade channels can also filter by `instrument_type` and `currency`. ```typescript TypeScript (SDK) theme={null} import { DeriveClient } from '@derivexyz/derive-ts'; const client = new DeriveClient({ network: 'mainnet', wallet: process.env.PRIVATE_KEY!, }); await client.connect(); await client.login(); // The instrument_name is used verbatim in the signed order. const { order } = await client.orders.place({ subaccountId: 1234, instrumentName: 'ETH-PERP', direction: 'buy', amount: '1.5', limitPrice: '3200', }); ``` ```python Python (SDK) theme={null} # Coming soon. ``` ```rust Rust (SDK) theme={null} // Coming soon. ``` ```bash cURL theme={null} # Body nonce/signature: EIP-712 action signing (see /action-signing). # X-Derive* headers: session auth (see /json-rpc). curl -X POST https://api.derive.xyz/v3/private/order \ -H "Content-Type: application/json" \ -H "X-DeriveWallet: $WALLET_ADDRESS" \ -H "X-DeriveTimestamp: $TS" \ -H "X-DeriveSignature: $SIG" \ -d '{ "subaccount_id": 1234, "instrument_name": "ETH-PERP", "direction": "buy", "amount": "1.5", "limit_price": "3200" }' ``` ```json Request theme={null} { "id": 2, "method": "private/order", "params": { "subaccount_id": 1234, "instrument_name": "ETH-PERP", "direction": "buy", "amount": "1.5", "limit_price": "3200" } } ``` Instrument names are case-sensitive and must be uppercase. A lowercase or malformed name is rejected — see [Error codes](/error-codes). For the list of currencies and settlement assets, see [`public/get_all_currencies`](/trading/managers-and-risk-universes#reading-public-get-all-currencies). ## Related topics - [Trades by instrument](/api-reference/channels/tradesbyinstrument.md) - [Get a single tradeable instrument](/api-reference/market-data/get-a-single-tradeable-instrument.md) - [Get the ticker for one instrument](/api-reference/market-data/get-the-ticker-for-one-instrument.md)