Skip to main content
A Convertible Entitlement Token (CET) stands for one share of a listed company. The CET Underlying API trades those shares: you buy and sell them over one authenticated WebSocket, and Securitize mints CETs as your buys fill and burns them as your sells fill. These docs are for the engineers building the integration and for the operations people reconciling what it does.

How it works

One socket carries all of it. There is no subscription step: once the session is open, it receives every update for your account. The reads of orders, mints, burns, cash and your redemption balance are also served as signed GET requests, for when you only need to ask: see Reads over HTTP.

The whole picture

  1. Connect to the socket and open a session with a signed hello. get_symbols lists what you can trade, and on which chains.
  2. Buy: place_order with side B. The ack means the order was taken; the fills arrive as order_updated and trade_updated. CETs are minted to your wallet as the order fills, often in more than one mint, and each mint is pushed as mint_updated.
  3. Sell: send the CETs to the redemption wallet, then place_order with side S and a quantity. The CETs are burned as the order fills, and each burn is pushed as burn_updated.
  4. Reconcile: get_order, get_mints and get_burns say what happened, whatever the stream delivered.

Sandbox and authentication

Connect, sign, open a session.

Buy shares and receive CETs

Place a buy and reconcile the CETs minted.

Sell shares and redeem CETs

Return the CETs, place the sell, reconcile the burns.

Track, cancel and reconcile orders

The stream, disconnects, UNKNOWN, cancels and executions.

Cash

Your own cash, its movements, and what a buy is checked against.

Go-live checklist

What to check in sandbox before production.

Before you start

  • An agreement with Securitize. It sets the symbols you can trade and the CET each one maps to, which get_symbols lists with their chains. get_redemption_address answers the redemption wallet of each CET.
  • Two registrations with Securitize: your Ed25519 public key, and the wallet that receives your CETs.
  • Sandbox is where you build and test. See Sandbox and authentication.
  • Production uses the same messages at a production endpoint, arranged with Securitize once your integration passes the go-live checklist.

What makes this API different

  • An ack is not a fill. It says the order was taken. Fills arrive afterwards, pushed.
  • The stream is a convenience, not a record. Updates are delivered at most once and nothing is queued while you are disconnected. After any gap, the reads say where things stand.
  • A sell needs its CETs first. A sell is refused unless CETs you transferred to the redemption wallet, and that are not held by your other sells, cover it (get_redemption_balance). It must be placed by quantity.
  • A buy is paid from your own cash. It is a LIMIT order by quantity, and its cost at the limit, plus fees, is held against your available (get_cash_balance_v2) before it reaches the broker. A buy that cash does not cover is refused.
  • externalRef is your idempotency key. A reference an order already uses is refused, never duplicated, so resending after a timeout is safe. An order Securitize refuses before sending it leaves its reference usable; one the broker refused keeps it for the rest of the day, so send the order again under a new reference.
  • Every amount is a decimal string, in both directions. Compare amounts as decimals, never as strings.

Not available

No quotes or market data: size orders with your own price feed. No push for settlement. No account field: the account is always the session’s. Every message, field and example is in the API reference in the sidebar.