Trusset Protocol - Infrastructure for Asset Tokenization

POST

orderbooks

external-securities

api

order-books

curl -X POST "https://api.trusset.org/orderbooks/external-securities/api/order-books" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Helvetia Growth Fund",
    "symbol": "HELG",
    "underlyingIdentifier": "CH0012032048",
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "tickSize": "10000",
    "minOrderSize": "1000000",
    "makerFeeBps": 0,
    "takerFeeBps": 10,
    "allowSharedLiquidity": true
  }'

const payload = {
  tokenAddress,
  quoteTokenAddress,
  name: 'Helvetia Growth Fund',
  symbol: 'HELG',
  underlyingIdentifier: 'CH0012032048',
  settlementOperator: await operator.getAddress(),
  tickSize: '10000',
  minOrderSize: '1000000'
};

let res = await fetch(
  'https://api.trusset.org/orderbooks/external-securities/api/order-books',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
let body = await res.json();

if (!body.success && body.error.code === 'CUSTODY_SETUP_REQUIRED') {
  const custodySetupTxs: 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();
    custodySetupTxs[step.key] = tx.hash;
  }
  res = await fetch(
    'https://api.trusset.org/orderbooks/external-securities/api/order-books',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ ...payload, custodySetupTxs })
    }
  );
  body = await res.json();
}

{
  "success": true,
  "data": {
    "id": "clx_ob_extsec_001",
    "instanceId": "inst_abc123",
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Helvetia Growth Fund",
    "symbol": "HELG",
    "status": "ACTIVE",
    "tokenType": "EXTERNAL_SECURITY",
    "settlementMode": "ON_CHAIN",
    "custodyContract": "0x489aee4ae9546081d55848f157e03192e826988c",
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "underlyingIdentifier": "CH0012032048",
    "baseDecimals": 18,
    "quoteDecimals": 6,
    "minOrderSize": "1000000",
    "maxOrderSize": null,
    "tickSize": "10000",
    "makerFeeBps": 0,
    "takerFeeBps": 10,
    "mmMakerRebateBps": null,
    "allowImport": false,
    "allowSharedLiquidity": true,
    "tradingMode": "CONTINUOUS",
    "priceRefEnabled": false,
    "priceRefMode": "MANUAL",
    "priceRefEnforcement": "EVERY_TRADE",
    "priceRefSpreadBps": null,
    "createdAt": "2025-06-15T12:00:00.000Z"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "CUSTODY_SETUP_REQUIRED",
    "message": "This external securities order book needs 3 on-chain 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": "0x489aee4ae9546081d55848f157e03192e826988c",
      "confirmWith": { "field": "custodySetupTxs", "keyedBy": "key" },
      "steps": [
        {
          "key": "agentRole",
          "to": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
          "data": "0x...",
          "functionName": "addAgent",
          "description": "Grant the T-REX agent role on 0x51f2... to the custody contract 0x489a...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        },
        {
          "key": "quoteAsset",
          "to": "0x489aee4ae9546081d55848f157e03192e826988c",
          "data": "0x...",
          "functionName": "setQuoteAsset",
          "description": "Authorize 0x98ad... as a settlement asset for 0x51f2...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        },
        {
          "key": "operator",
          "to": "0x489aee4ae9546081d55848f157e03192e826988c",
          "data": "0x...",
          "functionName": "setOperator",
          "description": "Authorize 0x5ad8... as a settlement operator for 0x51f2...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        }
      ]
    }
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "ISIN_MISMATCH",
    "message": "This security is already registered on the custody contract under \"CH0012032048\". Use that identifier, or ask the token issuer to update it on chain."
  }
}

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 the four on-chain prerequisites hold. See Custody setup. 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 ERC-3643 security token. Must be imported into your instance and readable on chain.

string

required

Settlement asset the security is quoted in. Must be authorized for this security on the custody contract, which is one of the four 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 the fourth setup step. 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

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.

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.

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 or EXTERNAL_FEED.

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.

string

JSON path to the price, or the ticker symbol in STOCK_FEED mode.

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.

Show child attributes

string

Hash of addAgent or addController on the security token.

string

Hash of registerSecurity on the custody contract.

string

Hash of setQuoteAsset on the custody contract.

string

Hash of setOperator on the custody contract.

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

Show child attributes

string

Order book ID. Use this as orderBookId everywhere else.

string

Owning instance.

string

Security token, lower-cased.

string

Settlement asset, lower-cased.

string

Display name.

string

Display symbol.

string

ACTIVE on creation.

string

EXTERNAL_SECURITY.

string

ON_CHAIN.

string

Custody contract the book settles through.

string

Wallet authorized to sign settlements, lower-cased.

string

Instrument identifier as recorded on chain.

integer

Security token decimals read from chain.

integer

Settlement asset decimals read from chain.

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

Whether the book pools depth.

string

CONTINUOUS.

boolean

Whether the band is enforced.

string

Reference source.

string

Refresh interval.

integer

Band half-width, or null.

string

ISO 8601 timestamp.

curl -X POST "https://api.trusset.org/orderbooks/external-securities/api/order-books" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Helvetia Growth Fund",
    "symbol": "HELG",
    "underlyingIdentifier": "CH0012032048",
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "tickSize": "10000",
    "minOrderSize": "1000000",
    "makerFeeBps": 0,
    "takerFeeBps": 10,
    "allowSharedLiquidity": true
  }'

const payload = {
  tokenAddress,
  quoteTokenAddress,
  name: 'Helvetia Growth Fund',
  symbol: 'HELG',
  underlyingIdentifier: 'CH0012032048',
  settlementOperator: await operator.getAddress(),
  tickSize: '10000',
  minOrderSize: '1000000'
};

let res = await fetch(
  'https://api.trusset.org/orderbooks/external-securities/api/order-books',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
let body = await res.json();

if (!body.success && body.error.code === 'CUSTODY_SETUP_REQUIRED') {
  const custodySetupTxs: 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();
    custodySetupTxs[step.key] = tx.hash;
  }
  res = await fetch(
    'https://api.trusset.org/orderbooks/external-securities/api/order-books',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ ...payload, custodySetupTxs })
    }
  );
  body = await res.json();
}

{
  "success": true,
  "data": {
    "id": "clx_ob_extsec_001",
    "instanceId": "inst_abc123",
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Helvetia Growth Fund",
    "symbol": "HELG",
    "status": "ACTIVE",
    "tokenType": "EXTERNAL_SECURITY",
    "settlementMode": "ON_CHAIN",
    "custodyContract": "0x489aee4ae9546081d55848f157e03192e826988c",
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "underlyingIdentifier": "CH0012032048",
    "baseDecimals": 18,
    "quoteDecimals": 6,
    "minOrderSize": "1000000",
    "maxOrderSize": null,
    "tickSize": "10000",
    "makerFeeBps": 0,
    "takerFeeBps": 10,
    "mmMakerRebateBps": null,
    "allowImport": false,
    "allowSharedLiquidity": true,
    "tradingMode": "CONTINUOUS",
    "priceRefEnabled": false,
    "priceRefMode": "MANUAL",
    "priceRefEnforcement": "EVERY_TRADE",
    "priceRefSpreadBps": null,
    "createdAt": "2025-06-15T12:00:00.000Z"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "CUSTODY_SETUP_REQUIRED",
    "message": "This external securities order book needs 3 on-chain 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": "0x489aee4ae9546081d55848f157e03192e826988c",
      "confirmWith": { "field": "custodySetupTxs", "keyedBy": "key" },
      "steps": [
        {
          "key": "agentRole",
          "to": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
          "data": "0x...",
          "functionName": "addAgent",
          "description": "Grant the T-REX agent role on 0x51f2... to the custody contract 0x489a...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        },
        {
          "key": "quoteAsset",
          "to": "0x489aee4ae9546081d55848f157e03192e826988c",
          "data": "0x...",
          "functionName": "setQuoteAsset",
          "description": "Authorize 0x98ad... as a settlement asset for 0x51f2...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        },
        {
          "key": "operator",
          "to": "0x489aee4ae9546081d55848f157e03192e826988c",
          "data": "0x...",
          "functionName": "setOperator",
          "description": "Authorize 0x5ad8... as a settlement operator for 0x51f2...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        }
      ]
    }
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "ISIN_MISMATCH",
    "message": "This security is already registered on the custody contract under \"CH0012032048\". Use that identifier, or ask the token issuer to update it on chain."
  }
}

Error Codes

Code	HTTP	Cause
`VALIDATION_ERROR`	`400`	A field failed schema validation
`INVALID_PAIR`	`400`	Base and quote token are the same
`INVALID_CONFIG`	`400`	`settlementOperator` is missing or malformed, a non-custody address was supplied, or a price reference field is invalid
`TOKEN_NO_ISIN`	`400`	The security is unregistered and no identifier was supplied, or the registered security has no readable identifier
`ISIN_MISMATCH`	`400`	The declared identifier does not match what is registered on chain
`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
`SECURITY_INACTIVE`	`409`	The token issuer has deactivated this security on the custody contract
`INVALID_CUSTODY_CONTRACT`	`400`	The address did not answer as the external securities custody contract
`TOKEN_METADATA_UNAVAILABLE`	`502`	Token decimals could not be read, or are outside the usable range
`CHAIN_UNAVAILABLE`	`502`	The RPC endpoint for your instance did not answer
`CUSTODY_NOT_DEPLOYED`	`503`	No custody contract is deployed on your instance’s network
`SERVICE_NOT_ENABLED`	`403`	The Trading service is not enabled on this instance

curl -X POST "https://api.trusset.org/orderbooks/external-securities/api/order-books" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Helvetia Growth Fund",
    "symbol": "HELG",
    "underlyingIdentifier": "CH0012032048",
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "tickSize": "10000",
    "minOrderSize": "1000000",
    "makerFeeBps": 0,
    "takerFeeBps": 10,
    "allowSharedLiquidity": true
  }'

const payload = {
  tokenAddress,
  quoteTokenAddress,
  name: 'Helvetia Growth Fund',
  symbol: 'HELG',
  underlyingIdentifier: 'CH0012032048',
  settlementOperator: await operator.getAddress(),
  tickSize: '10000',
  minOrderSize: '1000000'
};

let res = await fetch(
  'https://api.trusset.org/orderbooks/external-securities/api/order-books',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
let body = await res.json();

if (!body.success && body.error.code === 'CUSTODY_SETUP_REQUIRED') {
  const custodySetupTxs: 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();
    custodySetupTxs[step.key] = tx.hash;
  }
  res = await fetch(
    'https://api.trusset.org/orderbooks/external-securities/api/order-books',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ ...payload, custodySetupTxs })
    }
  );
  body = await res.json();
}

{
  "success": true,
  "data": {
    "id": "clx_ob_extsec_001",
    "instanceId": "inst_abc123",
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "name": "Helvetia Growth Fund",
    "symbol": "HELG",
    "status": "ACTIVE",
    "tokenType": "EXTERNAL_SECURITY",
    "settlementMode": "ON_CHAIN",
    "custodyContract": "0x489aee4ae9546081d55848f157e03192e826988c",
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "underlyingIdentifier": "CH0012032048",
    "baseDecimals": 18,
    "quoteDecimals": 6,
    "minOrderSize": "1000000",
    "maxOrderSize": null,
    "tickSize": "10000",
    "makerFeeBps": 0,
    "takerFeeBps": 10,
    "mmMakerRebateBps": null,
    "allowImport": false,
    "allowSharedLiquidity": true,
    "tradingMode": "CONTINUOUS",
    "priceRefEnabled": false,
    "priceRefMode": "MANUAL",
    "priceRefEnforcement": "EVERY_TRADE",
    "priceRefSpreadBps": null,
    "createdAt": "2025-06-15T12:00:00.000Z"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "CUSTODY_SETUP_REQUIRED",
    "message": "This external securities order book needs 3 on-chain 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": "0x489aee4ae9546081d55848f157e03192e826988c",
      "confirmWith": { "field": "custodySetupTxs", "keyedBy": "key" },
      "steps": [
        {
          "key": "agentRole",
          "to": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
          "data": "0x...",
          "functionName": "addAgent",
          "description": "Grant the T-REX agent role on 0x51f2... to the custody contract 0x489a...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        },
        {
          "key": "quoteAsset",
          "to": "0x489aee4ae9546081d55848f157e03192e826988c",
          "data": "0x...",
          "functionName": "setQuoteAsset",
          "description": "Authorize 0x98ad... as a settlement asset for 0x51f2...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        },
        {
          "key": "operator",
          "to": "0x489aee4ae9546081d55848f157e03192e826988c",
          "data": "0x...",
          "functionName": "setOperator",
          "description": "Authorize 0x5ad8... as a settlement operator for 0x51f2...",
          "requiredSigner": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
          "requiredRole": null
        }
      ]
    }
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "ISIN_MISMATCH",
    "message": "This security is already registered on the custody contract under \"CH0012032048\". Use that identifier, or ask the token issuer to update it on chain."
  }
}

Overview

MiCA Register

Customers

Stock Tokenization

Stock Trading

External Securities Trading

Commodity Trading

Stock Lending

External Securities Lending

Vaults

Create Order Book

Body Parameters

What is read from the chain

Response Fields

Error Codes

​Body Parameters

​What is read from the chain

​Response Fields

​Error Codes

Body Parameters

What is read from the chain

Response Fields

Error Codes