Where spot runs today: spot is built and in internal testing. It is not open on TestNet or MainNet yet. TestNet and MainNet are next; there is no date yet. The REST and WebSocket contract is the same on each network. Where spot is not open, spot requests are refused with feature_disabled.
Spot exchanges one asset for another. Buying a spot pair increases your base-asset balance and spends its quote asset. A perpetual is a contract position: it has margin, leverage and funding rather than ownership of the spot base asset.
This guide describes the protocol. Availability depends on the venue, the market, your account and the operation’s current capabilities. A documented operation does not mean that spot or token transfers are enabled on every venue.

Start with the market and currency catalogues

A spot symbol is BASE/QUOTE. Discover the symbol and the market’s separate id instead of constructing an instrument identifier. amount is a quantity of base units; price is quote units per base unit. A spot market has spot: true, swap: false, contract: false and margin: false. Its settlement and contract fields are null; spot has no funding rate, mark price or leverage. The following Node.js examples use the method and field names of the v2 API. The request helper is a small HTTP example, not an exchange SDK. Check a client’s has and feature support before using an optional method. The venue-specific iceberg parameter below is params.icebergQty. Save the helper as spot-client.mjs. Choose the REST origin from the platform introduction, and supply your own account, approved symbol and trading quantities. Keep credentials in process memory and out of source files and command output. The same two first flows in Rust, reading the spot markets and placing one limit order with its Idempotency-Key, are in spot-client.rs. It uses the blocking reqwest client and serde_json, like the Rust sample of each reference page.
Each market entry has info.category, the display category a client can filter on: crypto, equities, commodities, fx, indices or memes. It is not the trading session class. The entry also has the venue’s integer scales: info.priceScale (decimal places of price atoms), info.quantityScale (decimal places of quantity atoms), info.tickSizeAtoms (the price step in quote atoms per base unit) and info.lotSizeAtoms (the amount step in base atoms). Read precision and limits.amount, limits.price and limits.cost before submitting an order. The precision fields are step sizes, not counts of decimal places. Use the currency’s actual info.decimals for raw asset atoms; never assume every asset or the quote currency has the same scale. An inactive or halted market is not an invitation to submit orders.

Deposits, available balance and holds

fetchCurrencies reports each currency’s deposit and withdraw capabilities. If either is false, do not attempt that transfer. Buying a token does not require that token to support external deposits. Use the account’s supported funding flow for assets it can accept; a catalogue entry does not create a deposit route. See account funding. fetchBalance returns one complete balance entry per asset, plus the same values in the free, used and total maps. used includes both resting-order locks and withdrawal holds. The two are separate in info.assetBalances:
The v2 amounts and prices are JSON numbers in asset units. Raw *Atoms fields are integer strings. Keep those strings intact and use BigInt for exact atom arithmetic. Do not use Number to reconcile large atom balances. A known zero balance remains a real row; an unavailable projection is not a zero balance. A buy reserves quote funds for the full order and the applicable fee allowance. A sell reserves the full base quantity. An iceberg reserves its full amount, including the part hidden from the public book. Cancellation releases the remaining lock; it does not reverse fills that already occurred.

Read prices, liquidity and fees

Use REST for an initial snapshot or after reconnecting, then consume realtime updates. Do not poll balances, orders or the book in a reconcile loop.
An empty book side, empty trade list or empty candle list is a possible result. Spot candles use series=trade. A null ticker figure means unavailable, not zero. baseVolume is trailing 24-hour base volume.

Before the first trade and between trades

A spot market can be open and have no trade yet. Then the ticker has info.noTradesYet: true and last is null. While the market has a listing price, the ticker also has info.listingPrice, the listing price as decimal text. The listing price is display data set by the venue operator. It is not a trade price and not a mark. After the first trade, info.noTradesYet is false and info.listingPrice is absent. The candle read is computed when you read it. Nothing is stored for an interval with no trade:
  • An interval with no trade after the first trade is a flat candle at the last trade price, with volume 0.
  • Before the first trade, the read answers an empty list. When the market has a listing price, it answers flat candles at that price with volume 0, from the time the market opened. No candle comes before that time.
  • A flat candle has volume 0 and open = high = low = close. A trade candle always has volume above 0. Use the volume to tell the two apart; the OHLCV row has no extra field.
The maker and taker rates are fractions: 0.0001 means one basis point. Spot fees are charged in the quote asset on both sides. The market’s spot rates apply; perpetual account tiers do not replace them. Read the actual fee on your fill. An unknown fee is null, not a zero-fee promise. fetchTradingFee(symbol) can select one entry from the fetchTradingFees result; it needs no separate route.

Place an order

All four categories use POST /v2/order. Use a credential allowed to trade this account, a unique Idempotency-Key for each logical command, and retain its body and key if the outcome becomes unknown. Do not generate a new key merely because a response was lost. Account, invitation, market and agent admission still apply. Choose positive amount, price and icebergQty values that satisfy the market’s steps and limits. These examples intentionally contain no universal trading size or price. A limit price used for a resting example must not cross the current book.

Market

A market order specifies base quantity, including a market buy. Do not replace amount with quote cost or send params.notional for spot. The venue bounds the execution price from available liquidity and the market’s configured band. The unfilled remainder is canceled; there is no guarantee of a full fill.

Limit Maker / post-only

Limit Maker is a limit order with params.postOnly: true, not a new type value. If it would trade immediately, it is refused with post_only_would_cross (OrderImmediatelyFillable). timeInForce: "PO" is also a post-only request; it cannot be combined with postOnly: false. Reads normalize a limit order to timeInForce: "GTC" and preserve postOnly: true.

Iceberg

An iceberg is a limit order with params.icebergQty in base units. Its visible quantity must satisfy the lot size and be no greater than amount. Only the visible slice reaches the public book. The owner can read info.icebergQty and the full reserve. Do not combine iceberg with market, IOC or post-only orders.
Spot does not accept leverage, reduce-only, TP/SL or a quote-notional command. Refusals such as insufficient_balance, market_order_unavailable, invalid_iceberg_quantity and iceberg_not_supported are outcomes to handle, not evidence that an order executed. A disabled spot capability can return feature_disabled; disabled spot entries may be absent from list responses.

Self trade

One account never trades with itself. The rule:
  • The key is the account. Two different accounts trade with each other, also when one owner holds both.
  • An incoming order that would match a resting order of the same account is refused whole with self_trade_prevented (error class InvalidOrder). Nothing of it executes.
  • The resting order stays as it is. It is not canceled or reduced.
  • The check covers only the part of the book that the incoming order would fill. An own order deeper than that does not block fills against other accounts.
  • A post-only order skips this check. If it would cross any order, it is refused with post_only_would_cross first.

Repeated requests and Idempotency-Key

Every order command needs an Idempotency-Key header. The venue scopes the key to your account. If a response is lost or times out, the API does not send the command again for you. Send the same request with the same key; you get the recorded outcome. Do not make a new key because a response was lost. Without a clientOrderId, the venue derives the order id from the key, so a key must also be one that no other account sends. Give each order a clientOrderId that no other order has, for example a random UUID. The clientOrderId is not scoped to your account: if another account already used the same value, your order is refused with duplicate_order_id. This is a known limit.

Read, cancel and reconcile an order

To place up to 32 limit orders in one call, use createOrders (POST /v2/orders). Each entry is an order request; timeInForce may be GTC or PO. The answer has one result per entry, in the same order. An accepted entry stays placed when another entry is refused. To cancel up to 24 orders of one symbol, use cancelOrders (POST /v2/orders/cancel). To cancel every open order of one symbol, use cancelAllOrders (POST /v2/orders/cancel-all); there is no form for all symbols. If more than 500 orders are open on that symbol, it refuses with command_rejected (error class InvalidOrder) before it cancels any; cancel them by id. Each answer row is canceled, refused on its own (for example OrderNotFound for an order that filled), or not attempted. Accepted cancellations stay. The history route includes order states; use status to select the states your client needs. REST owner fills are Trade objects. Their required type is null when the fill did not record an order kind; do not infer it from price or liquidity.

Follow realtime updates

Realtime uses the market’s id, while the REST paths above use its symbol. Public market channels can be consumed without private account access. To include private channels, obtain a short-lived ticket with a verified trader session; do not assume a trading API key can mint one. Authenticate with { op: "auth", ticket } and wait for auth_ok before private subscriptions. Refresh an expiring ticket through the supported session flow rather than reusing a consumed ticket. Save the bounded stream example beside the request helper. It sends one correctly scoped subscribe request per selected channel and asserts actual data frames. An acknowledgement or a timeout does not count as a verified update. Run each channel while the corresponding market or account activity occurs; idle channels may produce no new frame.
account.fills carries the raw fill contract, not a REST Trade object: tradeId, orderId, accountId, marketId, role, feeRole, feePaidAtoms, side, priceAtoms, sizeAtoms and counterpartyOrderId. Its tradeId matches REST Trade.id. A spot account.orders payload is the REST Order, including info.lockedAtoms and the owner’s iceberg quantity. Preserve those distinctions. Per-asset balance frames coexist with the collateral cash-delta format. Apply an asset frame as an absolute asset row; do not add its total as a delta. Keep the existing cash-delta handling for payloads with changeAtoms. Scope cursors by channel and account or market. Persist delivered sequences, resume with fromSequence, and honor sequence_gap or resync_required before applying more updates. A refused subscription leaves other subscriptions open.

Spot in the v2 API

The v2 API follows the unified shape of the CCXT library (the same method names, fields and error classes), so a client written for that shape needs little work. Spot has no endpoints of its own. It uses the same v2 operations as perpetuals, with a spot symbol such as NVDAe/USDCx. A perpetual symbol has a settlement suffix, such as BTC/USDCx:USDCx. Each reference page of these operations starts with one sentence that says if the operation works for spot. Spot is built and in internal testing; it is not open on TestNet or MainNet yet.

For market makers

This section collects what a market maker needs to prepare its infrastructure for spot. It states what the venue does today. It promises nothing that is not built.

Addresses and where spot runs

Spot uses the same REST, OpenAPI document, WebSocket and MCP addresses as the rest of the venue. The Base URLs of the introduction list them. Spot is built and in internal testing. There is no date for TestNet or MainNet yet. Until spot opens on a network, spot requests there are refused with HTTP 503 feature_disabled. The perpetual API of that network does not change.

Account and API key

  1. The owner creates the account with a passkey session. See account setup for humans.
  2. The owner approves a trading key for the strategy with the trade scope, through the browser approval flow. The key reads and trades one account. It can never deposit, withdraw or change the Canton Party.
  3. Send the key as a bearer on every private request. Mint a realtime ticket for the private channels with a verified trader session.
Not possible today for an outside market maker:
  • Deposit a spot base token into the account. No network has a deposit route for spot tokens yet, also when fetchCurrencies shows deposit: true. The quote asset arrives through the account’s normal funding flow.
  • Withdraw a spot token. The token withdrawal route is not served yet.

Orders

Every order command takes an Idempotency-Key header. The rules are in Repeated requests above. Self trade, in four lines:
  • One account never trades with itself. Two accounts trade, also of one owner.
  • The incoming order is refused whole with self_trade_prevented.
  • The resting order stays as it is.
  • A post-only order skips the check; it gets post_only_would_cross if it would cross.
So if one strategy quotes both sides from one account, its own orders never match. Use separate accounts if two strategies must be able to trade with each other.

Steps, scales and limits

  • Price step: market.info.tickSizeAtoms, in quote atoms per base unit. Amount step: market.info.lotSizeAtoms, in base atoms. market.precision gives the same steps in units.
  • Scales: market.info.priceScale and market.info.quantityScale are the decimal places of the venue’s integer price and quantity atoms for that market.
  • Market order price band: each spot market bounds a market order’s price to a band set for that market. A limit order is not bounded by this band.
  • Rate limits: 600 authenticated requests per 60 seconds for each API key or signed-in user, by default. A venue can set another value, never above 6,000. The public GET /v2/tickers and GET /v2/markets/{symbol}/trades routes allow 120 requests per 60 seconds for each client. Over a limit, the answer is HTTP 429 with rate_limited; retry the same request with the same Idempotency-Key after the window resets.

Streams for the book and your own orders and fills

Subscribe with the market id (for example NVDAe-USDCx-SPOT), not the symbol. market.book is public. account.orders and account.fills need an authenticated session (auth_ok first). Persist each channel’s sequence and resume with fromSequence; honor sequence_gap and resync_required. Example frames. The payloads come from the published contract fixtures. The identifiers, the account and the sequence numbers are examples. environment names the network: staging is TestNet and production is MainNet. Spot is not open on TestNet yet. The frames show the shape only.

Known limits today

  • Spot is in internal testing. It is not open on TestNet or MainNet yet.
  • No deposit of a spot base token and no token withdrawal, on any network.
  • There is no trade correction: the venue does not correct or cancel a fill after it is published.
  • clientOrderId is not scoped to the account. Use a value no other order has.

Withdraw a token only when supported

Spot token withdrawal is not available yet. This section describes the flow for a currency whose withdraw capability is true. Check the currency’s withdraw capability first. Token withdrawal uses the existing withdrawal API, not an invented spot-v2 transfer endpoint. A trading credential is not an owner signature. A funding-capable credential may initiate only the steps allowed by the reference; owner signing still occurs in the browser. Never export a passkey to an example script.
A request acknowledgement is not a completed payout. A hold removes available funds and appears as heldAtoms; a confirmed debit reduces the total and consumes the hold. submitted means processing continues. Only the public paid status means payout reached the owner’s wallet. If a receiver must accept a transfer, completion remains pending until the required evidence exists. Do not release a hold merely because a local timer expired or resubmit a pending withdrawal. Use account.withdrawals for updates and the balance channel for asset changes. The REST reference and withdrawal stream describe the owner authorization and confirmation steps. Their signatures and capability refusals remain in force; this guide provides no automatic signing or completion shortcut.