Trusset Protocol - Infrastructure for Asset Tokenization

POST

orderbooks

stocks

api

order-books

curl -X POST "https://api.trusset.org/orderbooks/stocks/api/order-books" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Nyala Fund I",
    "symbol": "NYF1",
    "tokenType": "STOCK_TOKEN",
    "tickSize": "10000",
    "minOrderSize": "1000000",
    "makerFeeBps": 5,
    "takerFeeBps": 15
  }'

const res = await fetch(
  'https://api.trusset.org/orderbooks/stocks/api/order-books',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tokenAddress: '0xabc7f1093d5e26b804a1c3f78de025916b47c0d3',
      quoteTokenAddress: '0x98ad0ca091552e23c564b41c74282e5343d03e8a',
      name: 'Nyala Fund I',
      symbol: 'NYF1',
      tokenType: 'STOCK_TOKEN',
      tickSize: '10000',
      minOrderSize: '1000000',
      makerFeeBps: 5,
      takerFeeBps: 15
    })
  }
);
const body = await res.json();

if (!body.success && body.error.code === 'CUSTODY_SETUP_REQUIRED') {
  const signed: Record<string, string> = {};
  for (const step of body.error.setup.steps) {
    const tx = await wallet.sendTransaction({ to: step.to, data: step.data });
    await tx.wait();
    signed[step.key] = tx.hash;
  }
  // repeat the same POST with custodySetupTxs: signed
}

{
  "success": true,
  "data": {
    "id": "clx_ob_stock_001",
    "instanceId": "inst_abc123",
    "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Nyala Fund I",
    "symbol": "NYF1",
    "status": "ACTIVE",
    "tokenType": "STOCK_TOKEN",
    "settlementMode": "OFF_CHAIN",
    "custodyContract": null,
    "underlyingIdentifier": null,
    "stockTokenId": null,
    "minOrderSize": "1000000",
    "maxOrderSize": null,
    "tickSize": "10000",
    "makerFeeBps": 5,
    "takerFeeBps": 15,
    "mmMakerRebateBps": null,
    "allowImport": false,
    "allowSharedLiquidity": false,
    "tradingMode": "CONTINUOUS",
    "auctionIntervalSeconds": null,
    "currentAuctionId": null,
    "hybridSwitchSpreadBps": null,
    "auctionRollUnmatched": true,
    "baseDecimals": null,
    "quoteDecimals": null,
    "cfid": null,
    "priceRefEnabled": false,
    "priceRefMode": "MANUAL",
    "priceRefEnforcement": "EVERY_TRADE",
    "priceRefSpreadBps": null,
    "priceRefLastPrice": null,
    "priceRefLastUpdated": null,
    "createdAt": "2025-06-15T12:00:00.000Z"
  },
  "error": null,
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-06-15T12:00:00.000Z",
    "instanceId": "inst_abc123"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "CUSTODY_SETUP_REQUIRED",
    "message": "This on-chain order book needs 2 custody transactions signed before it can be created. Sign the returned transactions with the indicated wallet and submit the request again with their transaction hashes in custodySetupTxs.",
    "setup": {
      "action": "SIGN_TRANSACTIONS",
      "custodyContract": "0x98c33b10823172e62a31d6048773df1054c4f821",
      "confirmWith": { "field": "custodySetupTxs", "keyedBy": "key" },
      "steps": [
        {
          "key": "baseToken",
          "to": "0x98c33b10823172e62a31d6048773df1054c4f821",
          "data": "0x...",
          "functionName": "addSupportedToken",
          "description": "Register 0xabc7... as a supported custody token",
          "requiredSigner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
          "requiredRole": null
        },
        {
          "key": "tokenAuthorization",
          "to": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
          "data": "0x...",
          "functionName": "addAuthorizedContract",
          "description": "Authorize the custody contract on the stock token",
          "requiredSigner": null,
          "requiredRole": "ISSUER_ROLE"
        }
      ]
    }
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "ORDER_BOOK_EXISTS",
    "message": "Order book already exists for this pair"
  }
}

Creates an order book for one base token quoted in one settlement token (stablecoin). The book is created off-chain by default, which is the mode orders execute in. See Settlement modes. 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; a CLOSED book does not block a new one.

Body Parameters

string

required

Base token contract. Lower-cased before storage.

string

required

Settlement token contract. A well-known USDC address is normalised to your network’s USDC. Must differ from tokenAddress, otherwise INVALID_PAIR.

string

required

Display name, 1 to 64 characters.

string

required

Display symbol, 1 to 16 characters.

string

default:"OFF_CHAIN"

OFF_CHAIN or ON_CHAIN. ON_CHAIN requires custodyContract and a custody contract that already admits both tokens. OFF_CHAIN must not carry a custodyContract, and forces allowImport to false.

string

default:"LIGHT_TOKEN"

STOCK_TOKEN or LIGHT_TOKEN. Set STOCK_TOKEN for a Trusset stock token. The stock reads on this surface are filtered to STOCK_TOKEN, so a book left at the default will not appear in List Order Books.

string

StockCustody address for an on-chain book. Required when settlementMode is ON_CHAIN, refused otherwise.

string

Your Trusset stock token record ID, linking the book to an issuance. Up to 100 characters.

string

Declared ISIN, exactly 12 alphanumeric characters. Only checked on an on-chain STOCK_TOKEN book, where it must equal the ISIN the token reports on chain, otherwise ISIN_MISMATCH. The stored value always comes from the chain, never from this field.

string

default:"0"

Smallest accepted quantity, in order book units.

string

Largest accepted quantity, in order book units. Omit for no ceiling.

string

default:"1"

Price increment, in order book units.

integer

default:"0"

Maker fee in basis points, 0 to 1000.

integer

default:"0"

Taker fee in basis points, 0 to 1000.

integer

Fee applied in place of makerFeeBps when the resting side is a market maker account, −1000 to 1000. A negative value pays the market maker for providing liquidity.

boolean

default:"false"

Publish the book so other instances on the same network can import it. On-chain books only.

string

default:"CONTINUOUS"

CONTINUOUS, PERIODIC_AUCTION or HYBRID. See Trading modes.

integer

Auction batch length, 30 to 3600 seconds.

integer

Spread in basis points that flips a HYBRID book into auctions. 1 to 10000, and required above zero when tradingMode is HYBRID.

boolean

default:"true"

Whether orders left unfilled by an auction roll into the next batch instead of being cancelled.

boolean

default:"false"

Enforce a reference price band on incoming orders.

string

default:"MANUAL"

MANUAL, STOCK_FEED or EXTERNAL_FEED.

string

HTTPS endpoint for EXTERNAL_FEED, up to 2048 characters. Must resolve to a public host.

string

JSON object of request headers for the feed, as a string, up to 4096 characters. Host, Cookie and Authorization are dropped.

string

Dot-separated JSON path to the price in an EXTERNAL_FEED response, or the ticker symbol in STOCK_FEED mode. Up to 256 characters.

string

default:"EVERY_TRADE"

How often the reference is refreshed. One of EVERY_TRADE, 1MIN, 5MIN, 10MIN, 30MIN, 1HOUR, 6HOUR, 12HOUR, 1DAY.

integer

Half-width of the accepted band in basis points, 1 to 10000. Without it no band is enforced.

boolean

default:"false"

Refuse orders when the reference is stale, instead of serving the last known price.

integer

Seconds before a reference counts as stale, 60 to 604800. Defaults to three enforcement intervals, or 300 when enforcement is EVERY_TRADE.

integer

Reference move in basis points that pauses the book, 10 to 10000.

object

Hashes of the custody transactions you signed after a CUSTODY_SETUP_REQUIRED refusal, keyed by the step key. Unknown keys are rejected.

Show child attributes

string

Hash of addSupportedToken for the base token.

string

Hash of addSupportedToken for the quote token.

string

Hash of addAuthorizedContract on the stock token.

Custody setup

An on-chain book only exists once StockCustody admits both tokens and the stock token allow-lists the custody contract. Those calls are role-gated on chain, so this endpoint never signs them. It reads what is outstanding and refuses with 409 CUSTODY_SETUP_REQUIRED, writing no database row and returning the unsigned transactions in error.setup.steps. requiredSigner is read from the contract’s own admin(), so you always know which account must send each step; requiredRole names the role instead where no single address answers. Sign what you can, then repeat the same POST with those hashes in custodySetupTxs. Each hash is receipt-verified before the prerequisite is re-read from the chain, and the fresh read is the authority, so a step signed by a different wallet in another session still counts and re-posting is always safe.

Response Fields

Returns 201 with the created book.

object

Show child attributes

string

Order book ID. Use this as orderBookId everywhere else.

string

Owning instance.

string

Base token, lower-cased.

string

Quote token, lower-cased and normalised.

string

Display name.

string

Display symbol.

string

ACTIVE on creation.

string

STOCK_TOKEN or LIGHT_TOKEN.

string

OFF_CHAIN or ON_CHAIN.

string

Custody contract, or null off-chain.

string

ISIN read from the token on an on-chain stock book, otherwise null.

string

Linked stock token record, or null.

string

Minimum quantity.

string

Maximum quantity, or null.

string

Price increment.

integer

Maker fee in basis points.

integer

Taker fee in basis points.

integer

Market maker fee override, or null.

boolean

Whether other instances may import the book.

boolean

Always false when created through this surface.

string

CONTINUOUS, PERIODIC_AUCTION or HYBRID.

integer

Auction batch length, or null.

string

Live auction, or null.

integer

Hybrid failover threshold, or null.

boolean

Whether unmatched auction orders roll forward.

integer

Base token decimals, recorded for external securities books only. null here.

integer

Quote token decimals, recorded for external securities books only. null here.

string

Commodity fungibility class. null on stock books.

boolean

Whether the band is enforced.

string

Reference source.

string

Refresh interval.

integer

Band half-width, or null.

string

Last recorded reference, or null.

string

ISO 8601 timestamp, or null.

string

ISO 8601 timestamp.

curl -X POST "https://api.trusset.org/orderbooks/stocks/api/order-books" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Nyala Fund I",
    "symbol": "NYF1",
    "tokenType": "STOCK_TOKEN",
    "tickSize": "10000",
    "minOrderSize": "1000000",
    "makerFeeBps": 5,
    "takerFeeBps": 15
  }'

const res = await fetch(
  'https://api.trusset.org/orderbooks/stocks/api/order-books',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tokenAddress: '0xabc7f1093d5e26b804a1c3f78de025916b47c0d3',
      quoteTokenAddress: '0x98ad0ca091552e23c564b41c74282e5343d03e8a',
      name: 'Nyala Fund I',
      symbol: 'NYF1',
      tokenType: 'STOCK_TOKEN',
      tickSize: '10000',
      minOrderSize: '1000000',
      makerFeeBps: 5,
      takerFeeBps: 15
    })
  }
);
const body = await res.json();

if (!body.success && body.error.code === 'CUSTODY_SETUP_REQUIRED') {
  const signed: Record<string, string> = {};
  for (const step of body.error.setup.steps) {
    const tx = await wallet.sendTransaction({ to: step.to, data: step.data });
    await tx.wait();
    signed[step.key] = tx.hash;
  }
  // repeat the same POST with custodySetupTxs: signed
}

{
  "success": true,
  "data": {
    "id": "clx_ob_stock_001",
    "instanceId": "inst_abc123",
    "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Nyala Fund I",
    "symbol": "NYF1",
    "status": "ACTIVE",
    "tokenType": "STOCK_TOKEN",
    "settlementMode": "OFF_CHAIN",
    "custodyContract": null,
    "underlyingIdentifier": null,
    "stockTokenId": null,
    "minOrderSize": "1000000",
    "maxOrderSize": null,
    "tickSize": "10000",
    "makerFeeBps": 5,
    "takerFeeBps": 15,
    "mmMakerRebateBps": null,
    "allowImport": false,
    "allowSharedLiquidity": false,
    "tradingMode": "CONTINUOUS",
    "auctionIntervalSeconds": null,
    "currentAuctionId": null,
    "hybridSwitchSpreadBps": null,
    "auctionRollUnmatched": true,
    "baseDecimals": null,
    "quoteDecimals": null,
    "cfid": null,
    "priceRefEnabled": false,
    "priceRefMode": "MANUAL",
    "priceRefEnforcement": "EVERY_TRADE",
    "priceRefSpreadBps": null,
    "priceRefLastPrice": null,
    "priceRefLastUpdated": null,
    "createdAt": "2025-06-15T12:00:00.000Z"
  },
  "error": null,
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-06-15T12:00:00.000Z",
    "instanceId": "inst_abc123"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "CUSTODY_SETUP_REQUIRED",
    "message": "This on-chain order book needs 2 custody transactions signed before it can be created. Sign the returned transactions with the indicated wallet and submit the request again with their transaction hashes in custodySetupTxs.",
    "setup": {
      "action": "SIGN_TRANSACTIONS",
      "custodyContract": "0x98c33b10823172e62a31d6048773df1054c4f821",
      "confirmWith": { "field": "custodySetupTxs", "keyedBy": "key" },
      "steps": [
        {
          "key": "baseToken",
          "to": "0x98c33b10823172e62a31d6048773df1054c4f821",
          "data": "0x...",
          "functionName": "addSupportedToken",
          "description": "Register 0xabc7... as a supported custody token",
          "requiredSigner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
          "requiredRole": null
        },
        {
          "key": "tokenAuthorization",
          "to": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
          "data": "0x...",
          "functionName": "addAuthorizedContract",
          "description": "Authorize the custody contract on the stock token",
          "requiredSigner": null,
          "requiredRole": "ISSUER_ROLE"
        }
      ]
    }
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "ORDER_BOOK_EXISTS",
    "message": "Order book already exists for this pair"
  }
}

Error Codes

Code	HTTP	Cause
`VALIDATION_ERROR`	`400`	A field failed schema validation. `error.details` names each one
`INVALID_PAIR`	`400`	Base and quote token are the same
`INVALID_CONFIG`	`400`	An off-chain book was given a custody contract, a price reference field is invalid, or `HYBRID` was requested without `hybridSwitchSpreadBps`
`NO_CUSTODY_CONTRACT`	`400`	`settlementMode` is `ON_CHAIN` and `custodyContract` was omitted
`INVALID_CUSTODY_CONTRACT`	`400`	The address does not resolve to a Trusset custody contract on this network
`TOKEN_NO_ISIN`	`400`	The stock token exposes no valid on-chain ISIN
`ISIN_MISMATCH`	`400`	The declared `underlyingIdentifier` does not match the on-chain ISIN
`ORDER_BOOK_EXISTS`	`409`	An `ACTIVE` or `PAUSED` book already quotes this pair
`CUSTODY_SETUP_REQUIRED`	`409`	On-chain prerequisites are outstanding. `error.setup.steps` carries the unsigned transactions
`SERVICE_NOT_ENABLED`	`403`	The Trading service is not enabled on this instance
`BASE_TOKEN_NOT_SUPPORTED`	`503`	The custody contract does not admit the base token and no setup step could be built
`QUOTE_TOKEN_NOT_SUPPORTED`	`503`	The custody contract does not admit the quote token and no setup step could be built

curl -X POST "https://api.trusset.org/orderbooks/stocks/api/order-books" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Nyala Fund I",
    "symbol": "NYF1",
    "tokenType": "STOCK_TOKEN",
    "tickSize": "10000",
    "minOrderSize": "1000000",
    "makerFeeBps": 5,
    "takerFeeBps": 15
  }'

const res = await fetch(
  'https://api.trusset.org/orderbooks/stocks/api/order-books',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tokenAddress: '0xabc7f1093d5e26b804a1c3f78de025916b47c0d3',
      quoteTokenAddress: '0x98ad0ca091552e23c564b41c74282e5343d03e8a',
      name: 'Nyala Fund I',
      symbol: 'NYF1',
      tokenType: 'STOCK_TOKEN',
      tickSize: '10000',
      minOrderSize: '1000000',
      makerFeeBps: 5,
      takerFeeBps: 15
    })
  }
);
const body = await res.json();

if (!body.success && body.error.code === 'CUSTODY_SETUP_REQUIRED') {
  const signed: Record<string, string> = {};
  for (const step of body.error.setup.steps) {
    const tx = await wallet.sendTransaction({ to: step.to, data: step.data });
    await tx.wait();
    signed[step.key] = tx.hash;
  }
  // repeat the same POST with custodySetupTxs: signed
}

{
  "success": true,
  "data": {
    "id": "clx_ob_stock_001",
    "instanceId": "inst_abc123",
    "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Nyala Fund I",
    "symbol": "NYF1",
    "status": "ACTIVE",
    "tokenType": "STOCK_TOKEN",
    "settlementMode": "OFF_CHAIN",
    "custodyContract": null,
    "underlyingIdentifier": null,
    "stockTokenId": null,
    "minOrderSize": "1000000",
    "maxOrderSize": null,
    "tickSize": "10000",
    "makerFeeBps": 5,
    "takerFeeBps": 15,
    "mmMakerRebateBps": null,
    "allowImport": false,
    "allowSharedLiquidity": false,
    "tradingMode": "CONTINUOUS",
    "auctionIntervalSeconds": null,
    "currentAuctionId": null,
    "hybridSwitchSpreadBps": null,
    "auctionRollUnmatched": true,
    "baseDecimals": null,
    "quoteDecimals": null,
    "cfid": null,
    "priceRefEnabled": false,
    "priceRefMode": "MANUAL",
    "priceRefEnforcement": "EVERY_TRADE",
    "priceRefSpreadBps": null,
    "priceRefLastPrice": null,
    "priceRefLastUpdated": null,
    "createdAt": "2025-06-15T12:00:00.000Z"
  },
  "error": null,
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-06-15T12:00:00.000Z",
    "instanceId": "inst_abc123"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "CUSTODY_SETUP_REQUIRED",
    "message": "This on-chain order book needs 2 custody transactions signed before it can be created. Sign the returned transactions with the indicated wallet and submit the request again with their transaction hashes in custodySetupTxs.",
    "setup": {
      "action": "SIGN_TRANSACTIONS",
      "custodyContract": "0x98c33b10823172e62a31d6048773df1054c4f821",
      "confirmWith": { "field": "custodySetupTxs", "keyedBy": "key" },
      "steps": [
        {
          "key": "baseToken",
          "to": "0x98c33b10823172e62a31d6048773df1054c4f821",
          "data": "0x...",
          "functionName": "addSupportedToken",
          "description": "Register 0xabc7... as a supported custody token",
          "requiredSigner": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
          "requiredRole": null
        },
        {
          "key": "tokenAuthorization",
          "to": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
          "data": "0x...",
          "functionName": "addAuthorizedContract",
          "description": "Authorize the custody contract on the stock token",
          "requiredSigner": null,
          "requiredRole": "ISSUER_ROLE"
        }
      ]
    }
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "ORDER_BOOK_EXISTS",
    "message": "Order book already exists for this pair"
  }
}

Overview

MiCA Register

Customers

Tokenization

Trading

Lending

Asset Register

Vaults

Create Order Book

Body Parameters

Custody setup

Response Fields

Error Codes

​Body Parameters

​Custody setup

​Response Fields

​Error Codes

Body Parameters

Custody setup

Response Fields

Error Codes