Trusset Protocol - Infrastructure for Asset Tokenization

POST

orderbooks

stocks

api

orders

curl -X POST "https://api.trusset.org/orderbooks/stocks/api/orders" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2025-06-15-0001" \
  -d '{
    "orderBookId": "clx_ob_stock_002",
    "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "side": "BUY",
    "orderType": "LIMIT",
    "price": "182350000",
    "quantity": "5000000",
    "timeInForce": "GTC",
    "postOnly": true
  }'

const res = await fetch(
  'https://api.trusset.org/orderbooks/stocks/api/orders',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      orderBookId,
      userAddress: await wallet.getAddress(),
      side: 'BUY',
      orderType: 'LIMIT',
      price: '182350000',
      quantity: '5000000',
      timeInForce: 'GTC'
    })
  }
);
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": false,
  "data": null,
  "error": {
    "code": "WRONG_SETTLEMENT_MODE",
    "message": "Use off-chain API for off-chain orderbooks"
  }
}

{
  "success": true,
  "data": {
    "order": {
      "orderId": "b7c1e0d4-6f2a-4f1e-9d33-5c8a1f0b2e77",
      "orderBookId": "clx_ob_stock_002",
      "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
      "side": "BUY",
      "orderType": "LIMIT",
      "price": "182350000",
      "quantity": "5000000",
      "filledQuantity": "0",
      "remainingQuantity": "5000000",
      "status": "OPEN",
      "timeInForce": "GTC",
      "postOnly": true,
      "selfTradePreventionMode": "NONE",
      "createdAt": "2025-06-15T12:00:00.000Z"
    },
    "trades": [],
    "filledQuantity": "0",
    "remainingQuantity": "5000000",
    "status": "OPEN",
    "stpTriggered": false,
    "cancelReason": null
  }
}

Submits an order to an on-chain stock book. Orders on off-chain books go to Submit Off-Chain Order instead, and this endpoint refuses them with WRONG_SETTLEMENT_MODE.

On-chain execution is not currently available for stock books. Locking a balance in StockCustody needs a signature from the custody settlement operator, and Trusset holds no key to produce one, so this endpoint answers 409 ONCHAIN_SETTLEMENT_UNAVAILABLE for every stock book. The refusal happens before any lock row is written, so nothing is stranded.Move the book to off-chain settlement with Update Order Book and trade it there, or use External Securities Trading, where the trader’s own EIP-712 signature authorizes the movement and no operator key is needed.

The endpoint is documented here because the book-level checks in front of that refusal are real, and because the request shape is the one the venue will accept when an operator-signed lock path returns.

Idempotency

Accepts an optional Idempotency-Key header. A repeat with the same key and body replays the original response with Idempotent-Replay: true; the same key with a different body returns 409 IDEMPOTENCY_MISMATCH. See Idempotency.

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.

boolean

default:"false"

Reject the order rather than let it take. Checked against the whole eligible peer set, so a post-only order that would cross a pooled book is refused with POST_ONLY_WOULD_CROSS.

string

default:"NONE"

What happens when this order would match the same trading account. NONE allows it, CANCEL_TAKER drops the incoming order, CANCEL_MAKER drops the resting one, CANCEL_BOTH drops both. An unrecognised value falls back to NONE.

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 answers 201.

object

Show child attributes

object

The order record, including orderId, status, filledQuantity and remainingQuantity.

array

Trades produced by this submission. Empty when the order rested without matching.

string

Quantity filled, in order book units.

string

Quantity still resting, in order book units.

string

OPEN, PARTIALLY_FILLED, FILLED, CANCELLED or AUCTION_PENDING.

boolean

Whether self-trade prevention acted on this submission.

string

Why the order was cancelled, or null.

string

Auction the order was routed into, on a book running batches.

string

When that auction clears.

curl -X POST "https://api.trusset.org/orderbooks/stocks/api/orders" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2025-06-15-0001" \
  -d '{
    "orderBookId": "clx_ob_stock_002",
    "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "side": "BUY",
    "orderType": "LIMIT",
    "price": "182350000",
    "quantity": "5000000",
    "timeInForce": "GTC",
    "postOnly": true
  }'

const res = await fetch(
  'https://api.trusset.org/orderbooks/stocks/api/orders',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      orderBookId,
      userAddress: await wallet.getAddress(),
      side: 'BUY',
      orderType: 'LIMIT',
      price: '182350000',
      quantity: '5000000',
      timeInForce: 'GTC'
    })
  }
);
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": false,
  "data": null,
  "error": {
    "code": "WRONG_SETTLEMENT_MODE",
    "message": "Use off-chain API for off-chain orderbooks"
  }
}

{
  "success": true,
  "data": {
    "order": {
      "orderId": "b7c1e0d4-6f2a-4f1e-9d33-5c8a1f0b2e77",
      "orderBookId": "clx_ob_stock_002",
      "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
      "side": "BUY",
      "orderType": "LIMIT",
      "price": "182350000",
      "quantity": "5000000",
      "filledQuantity": "0",
      "remainingQuantity": "5000000",
      "status": "OPEN",
      "timeInForce": "GTC",
      "postOnly": true,
      "selfTradePreventionMode": "NONE",
      "createdAt": "2025-06-15T12:00:00.000Z"
    },
    "trades": [],
    "filledQuantity": "0",
    "remainingQuantity": "5000000",
    "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
`IDEMPOTENCY_KEY_REQUIRED`	`400`	The `Idempotency-Key` header was sent but is not 8 to 200 characters of `A-Za-z0-9_-:.`
`ORDER_BOOK_INACTIVE`	`400`	The book is `PAUSED` or `CLOSED`
`WRONG_SETTLEMENT_MODE`	`400`	The book settles off-chain. Use Submit Off-Chain Order
`ORDER_BOOK_NOT_FOUND`	`404`	The book does not exist, or is not reachable from your instance
`IDEMPOTENCY_MISMATCH`	`409`	The key was used before with a different body
`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

When execution returns, the order-level refusals will be those the other venues already raise: ORDER_TOO_SMALL, ORDER_TOO_LARGE, PRICE_REQUIRED, INVALID_QUANTITY, INVALID_PRICE, PRICE_OUTSIDE_BAND, INSUFFICIENT_CUSTODY_BALANCE, POST_ONLY_WOULD_CROSS, MM_CONFIG_VIOLATION, NO_LIQUIDITY, INVALID_SIGNATURE, PRICE_REF_STALE and PRICE_REF_UNAVAILABLE.

curl -X POST "https://api.trusset.org/orderbooks/stocks/api/orders" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2025-06-15-0001" \
  -d '{
    "orderBookId": "clx_ob_stock_002",
    "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "side": "BUY",
    "orderType": "LIMIT",
    "price": "182350000",
    "quantity": "5000000",
    "timeInForce": "GTC",
    "postOnly": true
  }'

const res = await fetch(
  'https://api.trusset.org/orderbooks/stocks/api/orders',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      orderBookId,
      userAddress: await wallet.getAddress(),
      side: 'BUY',
      orderType: 'LIMIT',
      price: '182350000',
      quantity: '5000000',
      timeInForce: 'GTC'
    })
  }
);
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": false,
  "data": null,
  "error": {
    "code": "WRONG_SETTLEMENT_MODE",
    "message": "Use off-chain API for off-chain orderbooks"
  }
}

{
  "success": true,
  "data": {
    "order": {
      "orderId": "b7c1e0d4-6f2a-4f1e-9d33-5c8a1f0b2e77",
      "orderBookId": "clx_ob_stock_002",
      "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
      "side": "BUY",
      "orderType": "LIMIT",
      "price": "182350000",
      "quantity": "5000000",
      "filledQuantity": "0",
      "remainingQuantity": "5000000",
      "status": "OPEN",
      "timeInForce": "GTC",
      "postOnly": true,
      "selfTradePreventionMode": "NONE",
      "createdAt": "2025-06-15T12:00:00.000Z"
    },
    "trades": [],
    "filledQuantity": "0",
    "remainingQuantity": "5000000",
    "status": "OPEN",
    "stpTriggered": false,
    "cancelReason": null
  }
}

Overview

MiCA Register

Customers

Tokenization

Trading

Lending

Operators

Asset Register

Vaults

Seller Financing

Submit Order

Idempotency

Body Parameters

Response Fields

Error Codes

​Idempotency

​Body Parameters

​Response Fields

​Error Codes

Idempotency

Body Parameters

Response Fields

Error Codes