Skip to main content
POST
Creates an order book for one imported security token quoted in one settlement asset. Three properties are fixed by this venue and cannot be overridden: settlement is always on-chain, the token type is always an external security, and the trading mode is always continuous. The book cannot be created until its on-chain prerequisites hold. See Custody setup. New books are created on the current custody contract of your network.
Generation 2 of the custody contract is not deployed on any network yet. Until it is, deliveryMode TRANSFER, access gates and tokens without an identity registry are refused with 409 CUSTODY_UPGRADE_REQUIRED. Read generation on Get Custody Contract first. On generation 1, book an ERC-3643 token and leave deliveryMode and the gates out; access.onboarding still applies to buyers the security’s identity registry refuses.
One instance may hold a single open book per pair. If an ACTIVE or PAUSED book already quotes this pair, the request returns ORDER_BOOK_EXISTS.

Body Parameters

string
required
The security token. Must be imported into your instance and readable on chain. On generation 2 an ERC-3643 token can use either delivery mode, and a token without an identity registry, such as an ERC-1400 or plain ERC-20 security, uses allowance delivery and needs a buyer gate. On generation 1 only an ERC-3643 token with an identity registry can be booked.
string
required
Settlement asset the security is quoted in. Must be authorized for this security on the custody contract, which is one of the setup steps. Must differ from tokenAddress.
string
required
Display name, 1 to 64 characters.
string
required
Display symbol, 1 to 16 characters.
string
required
Wallet that will sign settlement transactions for this book. It must be authorized on the custody contract for this security, which is one of the setup steps. It also signs the accessGates step when you request access gates, because the gates apply to the settlements this wallet sends. Naming a wallet you control is what lets settlements be driven through this API.
string
Instrument identifier, 1 to 31 characters, trimmed and upper-cased. An ISIN, a WKN, or an issuer’s own reference.Required when the security is not yet registered on the custody contract, because registration writes this identifier on chain. Optional afterwards, and if supplied it must match what is already registered, otherwise ISIN_MISMATCH. The stored value always comes from the chain.
string
Custody contract to use. Defaults to the address from Get Custody Contract. Any other address is refused with INVALID_CONFIG.
string
AGENT or TRANSFER. See Delivery modes.For a security that is not registered yet, this is the mode it is registered with. It defaults to AGENT when the token has an identity registry and to TRANSFER when it has none. AGENT on a token without an identity registry is refused with INVALID_CONFIG.For a security that is already registered, the mode on chain applies. A different value is refused with DELIVERY_MODE_MISMATCH.
object
Who may trade on the book. See Access module. buyer and seller gates need custody generation 2; onboarding works on both generations.Each gate is checked before any step is built: it must be a contract and must answer isVerified(address), otherwise ACCESS_GATE_INCOMPATIBLE. A security without an identity registry needs a buyer gate, otherwise BUYER_GATE_REQUIRED. Gates apply per security and settlement operator, so another open book of the same operator on the same security must use the same gates, otherwise ACCESS_GATES_SHARED. When the gates on chain differ from the ones requested, the setup steps include accessGates for the settlement operator to sign. The policy is saved with the book.
object
Where the reference price comes from. See Price feed module. When sent, it sets priceRefMode, priceRefFeedUrl, priceRefFeedPath and priceRefFeedHeaders for you.
string
default:"0"
Smallest accepted quantity, in order book units.
string
Largest accepted quantity, in order book units.
string
default:"1"
Price increment, in order book units. Enforced when an order is submitted: a price that is not a multiple is refused with INVALID_PRICE. Prepare Order does not check it, so a payload can be built at an off-tick price and then rejected on submission.
integer
default:"0"
Maker fee in basis points, 0 to 1000. Recorded on each trade for your own invoicing, never deducted at settlement. See Units and decimals.
integer
default:"0"
Taker fee in basis points, 0 to 1000. Recorded the same way as makerFeeBps.
integer
Fee applied in place of makerFeeBps when the resting side is a market maker account, −1000 to 1000. A negative value records a rebate for the market maker. Like the other fees, it is recorded on the trade and never paid out at settlement.
boolean
default:"false"
Publish the book so other instances on the same network can import it.
boolean
default:"false"
Pool depth with other books quoting the same instrument identifier. See Shared liquidity.
boolean
default:"false"
Enforce a reference price band on incoming orders.
string
default:"MANUAL"
MANUAL, STOCK_FEED, COMMODITY_FEED or EXTERNAL_FEED. Prefer priceFeed, which sets this for you.
string
HTTPS feed endpoint, up to 2048 characters. Must resolve to a public host.
string
Feed request headers as a JSON string, up to 4096 characters. Write-only: reads return "********" in their place.
string
JSON path to the price, the ticker symbol in STOCK_FEED mode, or the metal and unit in COMMODITY_FEED mode, such as XAU:GRAM.
string
default:"EVERY_TRADE"
Refresh interval, from EVERY_TRADE to 1DAY.
integer
Band half-width in basis points, 1 to 10000.
boolean
default:"false"
Refuse orders when the reference is stale.
integer
Staleness window in seconds, 60 to 604800.
integer
Reference move in basis points that pauses the book, 10 to 10000.
object
Hashes of the setup transactions you signed after a CUSTODY_SETUP_REQUIRED refusal, keyed by the step key. Unknown keys are rejected. A setup transaction sent through a Safe, an EIP-7702 account or an ERC-4337 smart account is accepted: the API reads the call the smart account made to the custody contract or the security token from the transaction’s call trace.

What is read from the chain

Both tokens’ decimals are read at creation and recorded on the book, so every later conversion between order book units and on-chain amounts uses the real numbers rather than a default. A token that reports unusable decimals is refused with TOKEN_METADATA_UNAVAILABLE. If the RPC endpoint for your instance does not answer, the request fails with CHAIN_UNAVAILABLE rather than reporting the prerequisites as unmet. No book is created and nothing is changed.

Response Fields

Returns 201 with the created book.
object

Error Codes