> ## Documentation Index > Fetch the complete documentation index at: https://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 by default; some markets configure a different settlement time (e.g. 4pm New York time for US-equity underlyings, which follows US daylight saving). The exact timestamp is in the instrument's `option_details.expiry`. `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 (ETH's settlement hour) 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} import asyncio from derive_py import WebSocketClient from derive_py.data_types import AssetType async def main(): client = WebSocketClient.from_env() await client.connect() response = await client.markets.get_all_instruments( instrument_type=AssetType.option, currency="ETH", expired=False, ) for instrument in response.instruments: print(instrument.instrument_name) await client.disconnect() asyncio.run(main()) ``` ```rust Rust (SDK) theme={null} use derive_rs::{ Environment, WsClient, models::{AssetType, GetAllInstrumentsRequest}, }; #[tokio::main] async fn main() -> Result<(), Box> { // Public market data needs no wallet and no login. let client = WsClient::new_public(Environment::Mainnet).await?; let params = GetAllInstrumentsRequest::builder() .instrument_type(AssetType::Option) .currency("ETH".to_string()) .expired(false) .try_into()?; let response = client.rpc().market_data().get_all_instruments(params).await?; for instrument in response.instruments { println!("{}", instrument.instrument_name); } Ok(()) } ``` ```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} import asyncio from decimal import Decimal from derive_py import WebSocketClient from derive_py.data_types import Direction async def main(): client = WebSocketClient.from_env() await client.connect() # The instrument_name is used verbatim in the signed order. response = await client.orders.create( instrument_name="ETH-PERP", direction=Direction.buy, amount=Decimal("1.5"), limit_price=Decimal("3200"), ) print(response.order.instrument_name) await client.disconnect() asyncio.run(main()) ``` ```rust Rust (SDK) theme={null} use bigdecimal::BigDecimal; use derive_rs::{ Environment, WsClient, actions::OrderArgs, models::{Direction, OrderType, TimeInForce}, }; #[tokio::main] async fn main() -> Result<(), Box> { let client = WsClient::new( Environment::Mainnet, Some(std::env::var("DERIVE_PRIVATE_KEY")?), Some(std::env::var("DERIVE_WALLET")?), Some(1234), ) .await?; client.login().await?; // The instrument_name is used verbatim in the signed order. let order = OrderArgs::builder() .instrument_name("ETH-PERP".to_string()) .direction(Direction::Buy) .order_type(OrderType::Limit) .time_in_force(TimeInForce::Gtc) .amount(BigDecimal::from(1)) .limit_price(BigDecimal::from(3200)) .build(); let response = client.orders().place(order).await?; println!("{}", response.order.instrument_name); Ok(()) } ``` ```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_risk_universes`](/trading/managers-and-risk-universes#reading-public-get-risk-universes). ## Related topics - [Trades by instrument](/api-reference/channels/tradesbyinstrument.md) - [public/get_instrument](/api-reference/market-data/publicget_instrument.md) - [private/cancel_by_instrument](/api-reference/orderbook/privatecancel_by_instrument.md)