This is a preview of the new Trading API. It is available in Sandbox only, where orders are simulated against a fixed order book, and it can change before release.
Endpoints
It uses the same OAuth 2.0 token endpoint and credentials as the Core API, with its own scopes:
trading.prices:read, trading.orders:create and trading.orders:read.
Assets and pairs
An order trades one asset for another. The base asset is the one bought or sold and the quote asset is the one prices are expressed in, so forBTC and USD the base asset is BTC. A quantity is in the base asset and a price is in the quote asset per one unit of the base asset. All amounts are decimal strings.
The assets of an order are the ones of its origin and destination accounts. A pair that cannot be traded is refused with asset_pair_not_supported, and an amount that breaks a bound of the venue is refused with a 409 whose details name the rule and its limit.
Price estimates
A price estimate is the volume-weighted price at which aquantity of the base asset would trade on a side, calculated from the order book. It is nonbinding, and the snapshotAt of the response says when the book was read. If the book cannot cover the quantity, the request fails with the depth that is available.
Orders
An order debits theorigin account and credits the destination account of the same user. The origin holds the base asset on a sell and the quote asset on a buy.
typeismarket, which trades at the price the book offers, orlimit, which trades only at itspriceor better. A limit order needs aprice.timeInForceisfok: the whole quantity trades or nothing does.
Retrying safely
TheclientOrderId is an idempotency key you choose, up to 64 characters. Replaying it with the same payload returns the existing order with a 200, and reusing it with a different payload is refused with a 409. After a 5xx or a timeout, replay the same clientOrderId before sending a new one, or the quantity may be traded twice.
Order lifecycle
Apending order is still being processed, so retrieve it again until it is closed. A closed order is finished, whatever its outcome: read its timeline for it. A filled order has one trade, returned by List order trades. A failed order may have traded, so do not send it again under a new clientOrderId.
Trying it in Sandbox
Sandbox tradesBTC and USD against a fixed order book, and needs a test user with a BTC account and a USD account. Send a new clientOrderId with every order.
These quantities force an outcome the book cannot produce by itself:
To try the reads, every user has six sample orders: List orders returns them, and you can get each one and read its trades.