Conventions
Money as decimal strings, party hints, timestamps, the instrument catalog
Money is a decimal string
Every amount and price on the wire is a ledger Decimal string matching
^\d+(\.\d+)?$ — positive, dot-separated, at most 10 fractional digits.
Never a float. Parse with a decimal/bigint library, not parseFloat, if
you do arithmetic on it.
{ "price": "97300.0", "qty": "5.0", "fee": "121.625" }Parties are hints
Party fields (maker, taker, invitedMakers, …) carry short party
hints — never full Canton party ids. Treat them as opaque identifiers
scoped to the desk. Yours is assigned at registration, derived from the
displayName you sent plus a uniquifying suffix:
{ "maker": "acme-mm-4f2a91" }Time
Timestamps are ISO-8601 UTC strings. validUntil in quote submissions also
accepts a zone offset (RFC 3339), not only the Z suffix — and may be omitted
entirely, in which case the desk defaults it (see Quoting).
The instrument catalog
GET /instruments returns the tradable catalog:
[{ "symbol": "cbtc", "displaySymbol": "cBTC", "decimals": 10 }]RFQs reference instruments by catalog symbol (base, quote). Use
decimals to render amounts; displaySymbol for humans. A holding in an
instrument that has left the catalog carries its raw registry id in both
symbol fields.
GET /desk returns the current default feeBps and the list of known
maker hints. Note the fee that applies to a trade is the one stamped on the
RFQ (rfq.feeBps), not the current desk default.
200 vs 202
Wallet calls (/wallet/incoming/:cid/accept, /wallet/withdraw) answer
202 when the effect waits on your signature and 200 when it does not —
both with the same {actions} body. The maker flow (POST /maker/quotes,
POST /maker/register/complete) always answers 200 with actions
inside. Treat the body as the source of truth — sign whatever actions
contains — and the status difference never matters.
Errors
Error bodies are {error, code?}:
error— human-readable, not a contract: the text may change.code— machine-readable and stable (RETRY_LATER,INSUFFICIENT_FUNDS,WALLET_MAKER_UNSUPPORTED); present only where defined. See Error handling for the full matrix.