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.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 isBASE/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.
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:
*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.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 hasinfo.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.
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 usePOST /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 replaceamount 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 withparams.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 withparams.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.
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 classInvalidOrder). 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_crossfirst.
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
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 asNVDAe/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
- The owner creates the account with a passkey session. See account setup for humans.
- The owner approves a trading key for the strategy with the
tradescope, through the browser approval flow. The key reads and trades one account. It can never deposit, withdraw or change the Canton Party. - Send the key as a bearer on every private request. Mint a realtime ticket for the private channels with a verified trader session.
- Deposit a spot base token into the account. No network has a deposit route for
spot tokens yet, also when
fetchCurrenciesshowsdeposit: 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_crossif it would cross.
Steps, scales and limits
- Price step:
market.info.tickSizeAtoms, in quote atoms per base unit. Amount step:market.info.lotSizeAtoms, in base atoms.market.precisiongives the same steps in units. - Scales:
market.info.priceScaleandmarket.info.quantityScaleare 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/tickersandGET /v2/markets/{symbol}/tradesroutes allow 120 requests per 60 seconds for each client. Over a limit, the answer is HTTP 429 withrate_limited; retry the same request with the sameIdempotency-Keyafter the window resets.
Streams for the book and your own orders and fills
Subscribe with the market id (for exampleNVDAe-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.
clientOrderIdis 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 whosewithdraw 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.
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.