Skip to main content
A buy purchases shares through Securitize’s broker. As it fills, Securitize mints one CET per share to the wallet registered for your account.
The examples assume an open session (Sandbox and authentication). Signed frames show a shortened signature; build them with the signedFrame helper from that page. Use a fresh externalRef on every run: a reference already used is refused as a duplicate.

1. Place the buy

A buy is a LIMIT order by quantity. Buy 10 shares, paying no more than 150 a share:
Every field is in the API reference. Things that commonly go wrong:
  • Your own cash pays for it. Before the order reaches the broker, quantity × limitPrice plus its fees is held against the available of get_cash_balance_v2. A buy it does not cover answers INVALID_ORDER with your figures, and nothing reaches the broker. Read your available before a large buy.
  • LIMIT and quantity, always. A MARKET buy, including one that leaves orderType out, and a buy by notional answer INVALID_ORDER: neither names the price its cost is held at.
  • externalRef is your idempotency key. Derive it from your own order id and store it before you send. At most 39 characters of letters, digits, ., _ and -; no colon, because the mint memo uses colons as separators.
  • Name the chain when the symbol has more than one. get_symbols lists every chain a symbol can be bought on. With one chain, chainId can be left out. With more than one, send the chainId whose CETs you want minted; without it the order answers INVALID_ORDER and nothing reaches the broker.
  • The broker checks the account too. A buy the broker account as a whole cannot pay for is refused with INVALID_ORDER and the message Insufficient buying power, even when your own cash covers it.
  • Only the symbols tracked for your account can be traded, the ones get_symbols lists. A symbol your account does not trade, mistyped or not, answers INVALID_ORDER; check it against get_symbols. Nothing reaches the broker, so the externalRef stays usable.

2. Read the acknowledgement

Store regulatoryId now. It is the order’s id in regulatory reporting, and the key that ties the order to its trades, mints and burns. tokenAddress is the on-chain address of the CET the order mints, and chainId the chain it is on.

3. Follow it as it fills

Fills arrive pushed, without a request:
  • order_updated: one frame per change to the order, carrying the order as it stands. Read status and leavesQuantity; zero means nothing is left working.
  • trade_updated: one frame per execution. Deduplicate on tradeId.
  • mint_updated: one frame per mint, once the CETs are on chain. See step 4.
Updates are delivered at most once. If the socket was down, read the order back with get_order: see After a disconnect.

4. Reconcile the CETs

CETs are minted in pieces, as the order fills. Each mint covers the shares filled since the previous one: amount = executedQty − previousMintedQty. A 250-share order that fills 100 and then the remaining 150 mints 100 and then 150. Sum amount, never executedQty. Read every mint of the order by its regulatoryId:
Two other ways in:
  • From the order: every get_order answer carries the order’s mints.
  • From a transaction on chain: send its hash as get_mints txHash and you get that mint and the executions it paid for. On Solana the mint’s memo also ends with its traceId, after the final colon, which get_mints takes too.
Each mint is also pushed as mint_updated, with the same shape, once the CETs are on chain. That can be minutes after the fill. Its txHash usually follows within a minute, in a second mint_updated for the same mint. A push is delivered at most once, so get_mints is how you catch up after a gap. Before you treat a mint’s executions as final, check executionsComplete is true. A mint is reported once it is on chain; there is no pending state. Mints and burns explains the memo, the handle and the edge cases.