Orders
Submit Order
Place an order on a commodity order book
POST
/
orderbooks
/
commodities
/
api
/
orders
curl -X POST "https://api.trusset.org/orderbooks/commodities/api/orders" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"orderBookId": "clx_ob_comm_001",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"side": "BUY",
"orderType": "LIMIT",
"price": "2412550000",
"quantity": "1000000",
"timeInForce": "GTC"
}'
const res = await fetch(
'https://api.trusset.org/orderbooks/commodities/api/orders',
{
method: 'POST',
headers: {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
orderBookId,
userAddress: await wallet.getAddress(),
side: 'BUY',
orderType: 'LIMIT',
price: '2412550000',
quantity: '1000000'
})
}
);
const body = await res.json();
if (!body.success) console.error(body.error.code, body.error.message);
{
"success": false,
"data": null,
"error": {
"code": "ONCHAIN_SETTLEMENT_UNAVAILABLE",
"message": "This order book uses ON_CHAIN settlement, which requires server-side signing that was removed. Switch the order book to OFF_CHAIN settlement (PATCH the order book with settlementMode OFF_CHAIN once no orders or locks are live) and use the off-chain order API."
}
}
{
"success": true,
"data": {
"order": {
"orderId": "f2a9c7d1-40e6-4b83-95c0-7d18a3e6b204",
"orderBookId": "clx_ob_comm_001",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"side": "BUY",
"orderType": "LIMIT",
"price": "2412550000",
"quantity": "1000000",
"filledQuantity": "0",
"remainingQuantity": "1000000",
"status": "OPEN",
"timeInForce": "GTC",
"createdAt": "2025-06-15T12:00:00.000Z"
},
"trades": [],
"filledQuantity": "0",
"remainingQuantity": "1000000",
"status": "OPEN",
"stpTriggered": false,
"cancelReason": null
}
}
Submits an order to a commodity book. Supports limit and market orders with configurable time in force.
The endpoint is documented here because the book-level checks in front of that refusal are real, and because this is the request shape the venue will accept when an operator-signed lock path returns.
When execution returns, the order-level refusals will be those the other venues already raise:
Order entry is not currently available on this venue. Locking a balance in
CommodityCustody needs a signature from the custody settlement operator, and Trusset holds no key to produce one, so this endpoint answers 409 ONCHAIN_SETTLEMENT_UNAVAILABLE on every commodity book. The refusal happens before any lock row is written, so nothing is stranded and no partial state is left behind.Wallet-signed on-chain execution exists today only on External Securities Trading, where the trader’s own EIP-712 signature authorizes the movement and no operator key is needed.Body Parameters
string
required
Target order book. Must be a book your instance owns or has imported.
string
required
Wallet placing the order.
string
required
BUY or SELL.string
required
LIMIT or MARKET. A LIMIT order requires price.string
Limit price in order book units, as a digit-only string. Required for
LIMIT, ignored for MARKET.string
required
Base quantity in order book units, as a digit-only string. Must sit between the book’s
minOrderSize and maxOrderSize.string
default:"GTC"
GTC rests until filled or cancelled. IOC fills what it can immediately and cancels the rest. FOK must fill entirely or is cancelled.string
Optional signature over
message, verified against userAddress. Up to 256 characters.string
The signed payload. Only checked when
signature is also present. Up to 512 characters.Response Fields
This is the shape the endpoint returns once execution is available. It answers201.
object
Show child attributes
Show child attributes
object
The order record, including
orderId, status, filledQuantity and remainingQuantity.array
Trades produced by this submission.
string
Quantity filled, in order book units.
string
Quantity still resting.
string
OPEN, PARTIALLY_FILLED, FILLED or CANCELLED.boolean
Whether self-trade prevention acted on this submission.
string
Why the order was cancelled, or
null.curl -X POST "https://api.trusset.org/orderbooks/commodities/api/orders" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"orderBookId": "clx_ob_comm_001",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"side": "BUY",
"orderType": "LIMIT",
"price": "2412550000",
"quantity": "1000000",
"timeInForce": "GTC"
}'
const res = await fetch(
'https://api.trusset.org/orderbooks/commodities/api/orders',
{
method: 'POST',
headers: {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
orderBookId,
userAddress: await wallet.getAddress(),
side: 'BUY',
orderType: 'LIMIT',
price: '2412550000',
quantity: '1000000'
})
}
);
const body = await res.json();
if (!body.success) console.error(body.error.code, body.error.message);
{
"success": false,
"data": null,
"error": {
"code": "ONCHAIN_SETTLEMENT_UNAVAILABLE",
"message": "This order book uses ON_CHAIN settlement, which requires server-side signing that was removed. Switch the order book to OFF_CHAIN settlement (PATCH the order book with settlementMode OFF_CHAIN once no orders or locks are live) and use the off-chain order API."
}
}
{
"success": true,
"data": {
"order": {
"orderId": "f2a9c7d1-40e6-4b83-95c0-7d18a3e6b204",
"orderBookId": "clx_ob_comm_001",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"side": "BUY",
"orderType": "LIMIT",
"price": "2412550000",
"quantity": "1000000",
"filledQuantity": "0",
"remainingQuantity": "1000000",
"status": "OPEN",
"timeInForce": "GTC",
"createdAt": "2025-06-15T12:00:00.000Z"
},
"trades": [],
"filledQuantity": "0",
"remainingQuantity": "1000000",
"status": "OPEN",
"stpTriggered": false,
"cancelReason": null
}
}
Error Codes
These are the refusals the endpoint can currently return. The checks that price, size and balance an order are behind the settlement refusal, so they are not reachable today.| Code | HTTP | Cause |
|---|---|---|
VALIDATION_ERROR | 400 | A field failed schema validation |
ORDER_BOOK_INACTIVE | 400 | The book is PAUSED or CLOSED |
ORDER_BOOK_NOT_FOUND | 404 | The book does not exist, or is not reachable from your instance |
ONCHAIN_SETTLEMENT_UNAVAILABLE | 409 | On-chain custody settlement has no wallet in the loop to sign the balance lock |
SERVICE_NOT_ENABLED | 403 | The Trading service is not enabled on this instance |
ORDER_TOO_SMALL, ORDER_TOO_LARGE, PRICE_REQUIRED, INVALID_QUANTITY, INVALID_PRICE, PRICE_OUTSIDE_BAND, INSUFFICIENT_CUSTODY_BALANCE, NO_CUSTODY_CONTRACT, NO_LIQUIDITY, INVALID_SIGNATURE, BASE_TOKEN_NOT_SUPPORTED, QUOTE_TOKEN_NOT_SUPPORTED, PRICE_REF_STALE and PRICE_REF_UNAVAILABLE.⌘I
curl -X POST "https://api.trusset.org/orderbooks/commodities/api/orders" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"orderBookId": "clx_ob_comm_001",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"side": "BUY",
"orderType": "LIMIT",
"price": "2412550000",
"quantity": "1000000",
"timeInForce": "GTC"
}'
const res = await fetch(
'https://api.trusset.org/orderbooks/commodities/api/orders',
{
method: 'POST',
headers: {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
orderBookId,
userAddress: await wallet.getAddress(),
side: 'BUY',
orderType: 'LIMIT',
price: '2412550000',
quantity: '1000000'
})
}
);
const body = await res.json();
if (!body.success) console.error(body.error.code, body.error.message);
{
"success": false,
"data": null,
"error": {
"code": "ONCHAIN_SETTLEMENT_UNAVAILABLE",
"message": "This order book uses ON_CHAIN settlement, which requires server-side signing that was removed. Switch the order book to OFF_CHAIN settlement (PATCH the order book with settlementMode OFF_CHAIN once no orders or locks are live) and use the off-chain order API."
}
}
{
"success": true,
"data": {
"order": {
"orderId": "f2a9c7d1-40e6-4b83-95c0-7d18a3e6b204",
"orderBookId": "clx_ob_comm_001",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"side": "BUY",
"orderType": "LIMIT",
"price": "2412550000",
"quantity": "1000000",
"filledQuantity": "0",
"remainingQuantity": "1000000",
"status": "OPEN",
"timeInForce": "GTC",
"createdAt": "2025-06-15T12:00:00.000Z"
},
"trades": [],
"filledQuantity": "0",
"remainingQuantity": "1000000",
"status": "OPEN",
"stpTriggered": false,
"cancelReason": null
}
}