Order Books
Update Order Book
Change status, sizing, fees, settlement mode, or price reference on a book you own
PATCH
/
orderbooks
/
stocks
/
api
/
order-books
/
{orderBookId}
curl -X PATCH "https://api.trusset.org/orderbooks/stocks/api/order-books/clx_ob_stock_001" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "PAUSED",
"takerFeeBps": 20,
"priceRefSpreadBps": 150
}'
const res = await fetch(
`https://api.trusset.org/orderbooks/stocks/api/order-books/${orderBookId}`,
{
method: 'PATCH',
headers: {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({ status: 'PAUSED', takerFeeBps: 20, priceRefSpreadBps: 150 })
}
);
const { data } = await res.json();
{
"success": true,
"data": {
"id": "clx_ob_stock_001",
"status": "PAUSED",
"takerFeeBps": 20,
"priceRefSpreadBps": 150,
"updatedAt": "2025-06-15T12:04:00.000Z"
}
}
{
"success": false,
"data": null,
"error": {
"code": "INVALID_CONFIG",
"message": "Cannot change settlementMode while the order book has open orders or active balance locks. Cancel resting orders and release their locks with wallet-signed custody transactions first."
}
}
Applies a partial update to a book your instance owns. Imported books are not updatable here: only the owning instance may change a book’s configuration, and a request against someone else’s book returns
ORDER_BOOK_NOT_FOUND.
Only the fields you send are touched. Everything else keeps its stored value.
Path Parameters
string
required
Order book ID.
Body Parameters
string
ACTIVE, PAUSED or CLOSED. Pausing stops new orders without touching resting ones. Reopening a CLOSED book is refused with ORDER_BOOK_EXISTS if another open book now quotes the same pair.string
Smallest accepted quantity, in order book units.
string
Largest accepted quantity. Send
null to remove the ceiling.string
Price increment, in order book units.
integer
Maker fee in basis points, 0 to 1000.
integer
Taker fee in basis points, 0 to 1000.
integer
Market maker fee override, −1000 to 1000, or
null to remove it.boolean
Publish or unpublish the book for import. Ignored on an off-chain book, which can never be imported.
string
OFF_CHAIN only. Moving a book off-chain clears its custody contract and turns off allowImport. Setting ON_CHAIN returns 409 ONCHAIN_SETTLEMENT_UNAVAILABLE.string
Replace the custody contract on a book that stays on-chain. The new contract must already admit both tokens, otherwise the request returns
CUSTODY_SETUP_REQUIRED with the outstanding steps.object
Hashes of the custody transactions you signed for a contract change, keyed by
baseToken, quoteToken and tokenAuthorization.string
CONTINUOUS, PERIODIC_AUCTION or HYBRID. Switching to CONTINUOUS also clears currentAuctionId. HYBRID requires a hybridSwitchSpreadBps above zero, either sent here or already stored.integer
Auction batch length, 30 to 3600 seconds.
integer
Hybrid failover threshold in basis points, 1 to 10000.
boolean
Whether unmatched auction orders roll into the next batch.
boolean
Turn the reference band on or off. Turning it off also clears the cached reference price.
string
MANUAL, STOCK_FEED or EXTERNAL_FEED.string
HTTPS feed endpoint, or
null. Must resolve to a public host.string
Feed headers as a JSON string, or
null.string
JSON path to the price, or the ticker symbol in
STOCK_FEED mode. null clears it.string
Refresh interval, from
EVERY_TRADE to 1DAY.integer
Band half-width in basis points, 1 to 10000, or
null.boolean
Whether a stale reference stops trading.
integer
Staleness window in seconds, 60 to 604800, or
null.integer
Reference move that pauses the book, 10 to 10000, or
null.Changing settlement mode
A book only moves to off-chain settlement when nothing is in flight on it. The request is refused withINVALID_CONFIG while any order is OPEN, PARTIALLY_FILLED or AUCTION_PENDING, while any balance lock is PENDING or ACTIVE, and while any trade is still settling. Cancel resting orders and release their locks first.
The same conditions guard a custody contract change on a book that stays on-chain.
allowSharedLiquidity is not accepted on this surface. For stock books it is turned on from the Issuer App.Response Fields
Returns the updated book, in the same shape as Get Order Book.curl -X PATCH "https://api.trusset.org/orderbooks/stocks/api/order-books/clx_ob_stock_001" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "PAUSED",
"takerFeeBps": 20,
"priceRefSpreadBps": 150
}'
const res = await fetch(
`https://api.trusset.org/orderbooks/stocks/api/order-books/${orderBookId}`,
{
method: 'PATCH',
headers: {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({ status: 'PAUSED', takerFeeBps: 20, priceRefSpreadBps: 150 })
}
);
const { data } = await res.json();
{
"success": true,
"data": {
"id": "clx_ob_stock_001",
"status": "PAUSED",
"takerFeeBps": 20,
"priceRefSpreadBps": 150,
"updatedAt": "2025-06-15T12:04:00.000Z"
}
}
{
"success": false,
"data": null,
"error": {
"code": "INVALID_CONFIG",
"message": "Cannot change settlementMode while the order book has open orders or active balance locks. Cancel resting orders and release their locks with wallet-signed custody transactions first."
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
VALIDATION_ERROR | 400 | A field failed schema validation |
INVALID_PARAM | 400 | orderBookId is missing or longer than 100 characters |
INVALID_CONFIG | 400 | An invalid trading mode or price reference value, a custody contract removed from an on-chain book, or live orders, locks or settling trades blocking the change |
ORDER_BOOK_NOT_FOUND | 404 | The book does not exist on your instance. Imported books cannot be updated |
ORDER_BOOK_EXISTS | 409 | Reopening a closed book collides with another open book on the same pair |
CUSTODY_SETUP_REQUIRED | 409 | A new custody contract has outstanding prerequisites. error.setup.steps carries the unsigned transactions |
ONCHAIN_SETTLEMENT_UNAVAILABLE | 409 | settlementMode was set to anything other than OFF_CHAIN |
SERVICE_NOT_ENABLED | 403 | The Trading service is not enabled on this instance |
⌘I
curl -X PATCH "https://api.trusset.org/orderbooks/stocks/api/order-books/clx_ob_stock_001" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "PAUSED",
"takerFeeBps": 20,
"priceRefSpreadBps": 150
}'
const res = await fetch(
`https://api.trusset.org/orderbooks/stocks/api/order-books/${orderBookId}`,
{
method: 'PATCH',
headers: {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({ status: 'PAUSED', takerFeeBps: 20, priceRefSpreadBps: 150 })
}
);
const { data } = await res.json();
{
"success": true,
"data": {
"id": "clx_ob_stock_001",
"status": "PAUSED",
"takerFeeBps": 20,
"priceRefSpreadBps": 150,
"updatedAt": "2025-06-15T12:04:00.000Z"
}
}
{
"success": false,
"data": null,
"error": {
"code": "INVALID_CONFIG",
"message": "Cannot change settlementMode while the order book has open orders or active balance locks. Cancel resting orders and release their locks with wallet-signed custody transactions first."
}
}