Skip to main content
External securities trading runs an order book over security tokens that were issued somewhere else and imported into your instance: ERC-3643 (T-REX) tokens of any fork, and on generation 2 of the custody contract also ERC-1400 tokens through their ERC-20 layer and plain ERC-20 securities. Generation 2 is not deployed on any network yet, see Contract generations. Orders match off-chain in the same engine as the other venues, and settle on-chain in a single atomic transaction that carries both traders’ signatures. This is the only Trusset venue where an order book settles on chain today, and the reason is the custody model. Nothing is escrowed and nothing is pooled, so no operator key is needed to move a position into custody: the traders themselves authorize every settlement by signing their orders. The sibling venues are Stock Trading for tokens Trusset issued and Commodity Trading for commodity tokens.

Base Path

Six route families sit under that path: Every request authenticates with an instance API key in the X-API-Key header and requires the Trading service on your instance. See Authentication. A book belonging to another instance returns ORDER_BOOK_NOT_FOUND unless you have imported it.

Response envelope

On failure, success is false, data is null, and error carries code and message. Schema failures use VALIDATION_ERROR with error.details listing each offending field. Several refusals carry extra context beside the code: deliveryCode, tokenRestrictionCode, required, available, referencePrice, lowerBound, upperBound, orderHash, reason, remainingBase, accessCode, remedy and field. Those fields are named on the endpoints that raise them.

The custody model

TRexCustody is one contract per network with no owner, no admin and no upgrade path. It holds no balances at all. An ERC-3643 token only accepts a transfer whose recipient is verified in the issuer’s own identity registry. A pooled vault would therefore have to be entered into someone else’s register as a holder. Worse, once tokens sit in one omnibus balance the token sees a single holder, and country limits, holder counts and address freezes stop applying to the actual counterparties. The model here inverts that: The seller stays the registered holder for the whole life of an order, and the buyer is checked against the token’s own compliance layer on every delivery. Both legs are checked by balance change. The buyer must receive exactly the traded quantity and the seller exactly the traded amount of the settlement asset, otherwise the whole settlement reverts. A token that takes a fee on transfer can therefore never settle short of a signed limit. Each security is administered by its own controller, not by Trusset. The security admin recorded at registration is who authorizes settlement asset and venue operator changes, and who can stop all trading in that security at any time. Trusset holds no role on the contract.

Contract generations

The custody contract exists in two generations. Generation 2 adds allowance delivery and the access module, and keeps every generation 1 function and the EIP-712 domain, so a signed order encodes the same on both. custodyGeneration on Get Trade Readiness and generation on Get Order Book Access report which one a book settles through. Today every network that runs external securities trading runs generation 1. Generation 2 is not deployed on any network yet. Until it is, allowance delivery, access gates and securities without an identity registry (ERC-1400, ERC-1404, ERC-7943 and plain ERC-20 tokens) are not available. Read generation on Get Custody Contract before you plan on them. List Security Tokens lists only the tokens the current generation can book. New books are created on the current custody contract of your network. Books on an earlier contract keep trading as before. Requesting allowance delivery or an access gate, or a security without an identity registry, on a generation 1 contract is refused with 409 CUSTODY_UPGRADE_REQUIRED. The message says whether generation 2 is missing on the network or only on that book. On generation 1 the venue still checks every buyer against the security’s own identity registry, the check the contract makes at settlement. A buyer it does not verify is refused at prepare and submit with 403 ACCESS_NOT_ADMITTED and accessCode 9, with the onboarding remedy of the book.

Delivery modes

Each security is registered on the custody contract with one delivery mode. The mode is recorded on chain, and only the security admin can change it. Agent delivery is the reference for ERC-3643 registers. Allowance delivery serves a register provider that will not grant an agent role, and every token without an identity registry, such as an ERC-1400 token used through its ERC-20 layer or a plain ERC-20 security. When you create a book on a security that is not registered yet, the mode defaults to AGENT if the token has an identity registry and to TRANSFER if it has none. An already registered security keeps the mode it was registered with. A seller of an allowance-delivered security approves the custody contract for the security with Approve Security. The tradable balance of such a seller is the lesser of the unfrozen balance and that allowance.

Order lifecycle

1

Prepare

Prepare Order returns the EIP-712 domain, types and order to sign, plus the orderHash. It checks that the venue admits the trader, previews the reservation, and reports the allowance the trader still has to grant.
2

Sign

The trader signs the typed data in their own wallet. Nothing is sent to Trusset but the resulting signature. EOA signatures and EIP-1271 smart contract wallets are both accepted.
3

Submit

Submit Order verifies the signature, checks that the venue admits the trader, checks the order is still live on chain, reserves the balance, and matches. If it fills, a settlement is staged and its calldata comes back in the same response.
4

Settle

The venue operator signs and broadcasts that transaction. The contract verifies both orders’ signatures itself, so the operator can only execute a trade both sides actually signed, at or better than each side’s limit.
5

Confirm

Confirm Settlement verifies the mined receipt before writing anything, checking status, target, function and every argument, then consumes the reservations.
Only limit orders can be signed, since a market order carries no price for a signature to bind. Sweeping the book is done with a limit price and timeInForce: IOC.

Reservations

There is no on-chain lock. A resting order reserves the trader’s balance off-chain, and every balance the venue reports is net of those reservations. available is what a new order can draw on: the unfrozen security balance for a sell (the lesser of that balance and the security allowance for an allowance-delivered security), or the lesser of balance and allowance for the settlement asset on a buy, minus everything already reserved. A reservation is reduced by the settled amount when a settlement confirms, and released on cancellation. A background sweeper expires it once the signed order passes its on-chain deadline. Because the chain cannot see a reservation, Get Custody Balance answers with the same net figure the order gate uses rather than the raw chain number. Publishing the raw number would overstate inventory by exactly the trader’s own resting quotes and then refuse their next order.

Signed order liveness

A signature is a bearer authorization the chain can retire without telling the venue. A trader can cancel it, raise their nonce floor, or consume it in another settlement. The venue therefore re-reads liveness at three points rather than only when a settlement is built. On submit, for the incoming order. A signature already cancelled, nonce-invalidated or filled on chain is refused with ORDER_NOT_LIVE. A signature already resting on the book is refused with DUPLICATE_ORDER. One signature authorizes one quantity once, so sign a fresh salt to rest again. The duplicate check is serialized on the order hash, so two simultaneous submissions of the same signature cannot both pass. Before matching, for the resting orders the incoming order can actually reach. The maker’s signature is the one that goes stale while it rests, because Cancel Orders On Chain lets a trader invalidate it without the venue. Orders the chain has retired are cancelled and their reservations released before a trade can be booked against them. Where the venue has an access gate on the makers’ side, a resting order whose wallet the gate no longer admits is cancelled the same way, with cancelReason ACCESS_REVOKED. Only the depth the order can consume is re-read, so the chain cost tracks the fill rather than the book size. At settlement build, where a permanently doomed settlement is marked FAILED and unwound as it is diagnosed, reversing the trade and releasing both reservations rather than stranding them.

Units and decimals

Prices and quantities on the API are order book units: integers in a fixed-point representation with 6 decimal places, sent as digit-only strings. 1000000 is one whole unit. Each book records the real decimals of both its tokens, read from the chain at creation, and converts between order book units and on-chain amounts with those. A quantity that does not convert to a whole number of indivisible token units is refused rather than silently rounded, and the message states the step size. A 0-decimal whole-share register therefore requires quantities in whole multiples of 1000000 order book units. Fees are integers in basis points, capped at 1000. Each trade records makerFee and takerFee as base quantity, quantity × feeBps / 10000 in order book units, for the venue’s own invoicing. Settlement does not deduct them: the custody contract moves the gross amounts, so the buyer receives the full quantity and the seller the full amount of the settlement asset.

Custody setup

A book cannot be created until its on-chain prerequisites hold. Each is role-gated on the token, the security’s own admin or the settlement operator, so Trusset never signs them. Create Order Book resolves what is outstanding from live chain reads and refuses with 409 CUSTODY_SETUP_REQUIRED, returning the unsigned transactions. Sign what you can, then repeat the same request with those hashes in custodySetupTxs. Each hash is receipt-verified before the prerequisite is re-read from the chain, and the fresh read, not the hash, is the authority. Partial progress is durable, a step signed by a different wallet in another session still counts, and re-posting is always the correct recovery. Get Trade Readiness reports the same prerequisites for a book that already exists.

Delivery checks

A forced transfer deliberately bypasses the token’s compliance modules, which is what the agent role is for, so the venue runs the checks itself before using it. Under allowance delivery the token enforces its own rules, and the same checks run first so a refusal names its cause. The custody contract exposes the logic as a view, and the venue calls it before a sell order is allowed to rest. A refusal comes back as DELIVERY_NOT_ALLOWED with the numeric deliveryCode. Where the token reports its own ERC-1404 reason, the message carries it and tokenRestrictionCode names the token’s code.
Codes 6 and 9 are not checked when a sell order rests, because both describe the buyer and no buyer is known yet. They are enforced at settlement, against the actual counterparty.

Access module

The access module lets the operator of a book decide who may trade on it. It works like the identity gates of the lending markets. A book can carry a buyer gate and a seller gate. Each gate is a contract that answers isVerified(address). You name it in one of three ways: The gates are enforced on chain. The settlement operator sets them for itself on the custody contract with setAccessGates, which is one more step in the setup flow, and the contract checks both parties against them on every settlement that operator sends. They apply per security and settlement operator, so two books of one operator on the same security share them. A gate that cannot be read refuses rather than admits. The venue checks the same gates when an order is prepared and submitted, so a wallet that is not admitted gets 403 ACCESS_NOT_ADMITTED before anything rests. A security without an identity registry can only be bought by a wallet a buyer gate admits, so such a book requires a buyer gate. Gates need generation 2. On generation 1 the one check is the security’s identity registry, and onboarding applies to the buyers it refuses. onboarding decides what a refused wallet is told, through the remedy object on the refusal: Access is configured with access on Create Order Book and Update Order Book, and read with Get Order Book Access.

Price feed module

The reference price band reads its price through one interface, priceFeed, with four sources: Stock and commodity prices are converted into the settlement currency of the book when one quotes in USD and the other settles in EUR, at the ECB reference rate. A stock quoted in another currency cannot be converted, and reading it fails with FEED_CURRENCY_UNSUPPORTED. A custom feed is never converted: its price is used as it quotes, so point it at a feed that quotes in the settlement currency of the book. A preview reports its currency as null. Preview Price Feed reads a feed once so you can check it before you save it.

Shared liquidity

Two books quoting the same security can pool their depth. Eligibility is an exact match on the instrument identifier recorded on the custody contract. The token address, the settlement asset, the custody contract and the network must match too, both sides must be ACTIVE with allowSharedLiquidity set, and both must name the same access gates, so a pooled trade never pairs a wallet one venue admits with a venue that refuses it. Same-token identity is what keeps a cross-venue fill atomically settleable: both sides of a pooled trade settle in one transaction on one contract. The identifier is free-form, up to 31 characters: an ISIN, a WKN or an issuer’s own reference. The only rule is that venues quoting the same instrument agree on the same string. Settlement authority stays with the book’s owner. An instance trading on an imported book receives the settlement reference rather than a transaction it is not authorized to send. An importer does not see the owner’s price feed configuration, and sees only the orders its own instance submitted. On the trade tape, a side another instance submitted reads with its address and order ID set to null unless you own the book that side traded on.

Trading modes

External securities books run continuously. PERIODIC_AUCTION and HYBRID are rejected at creation and on update, so tradingMode is always CONTINUOUS and the auction endpoints have no counterpart on this venue.

Idempotency

Mutating endpoints accept an Idempotency-Key header of 8 to 200 characters from A-Za-z0-9_-:.. A repeat with the same key and body replays the original status and body with Idempotent-Replay: true; the same key with a different body returns 409 IDEMPOTENCY_MISMATCH. Keys are scoped to your instance and the specific endpoint, and expire after 24 hours. Submit Order, Update Order Book and Confirm Settlement accept it. None of them require it.

Rate limits

Every request made with an instance API key counts against a ceiling of 200 requests per minute for that key. Writes carry a second, tighter limit on top of it: Exceeding a limit returns 429 with code RATE_LIMIT_EXCEEDED and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. See Rate Limits.

Credits

Requests on this surface also draw on your instance’s monthly API credit allowance. Every response carries X-Credits-Limit, X-Credits-Remaining and X-Credits-Reset, plus an X-Request-Id you can quote in support requests. When the allowance is exhausted the request is refused with 402 and code CREDIT_LIMIT_EXCEEDED, and metadata carries creditsLimit, creditsRemaining and resetsAt. Credits consumed by a request that fails with a 5xx are refunded automatically.