Trade a stock

Buying and selling follow the same four steps; only the contract address and the amount field differ. Orders are fill or kill: they execute in full at the priced level or better, or not at all.

GET  /stocks/realtime-price                  → price + signedPrice
POST /stocks/{on-ramp|off-ramp}/{contract}…  → transaction to sign
     the investor's wallet signs it            no Securitize call
POST /stocks/execute-signed-transaction      → transactionHash

	Buy	Sell
`side` on the price	`on-ramp`	`off-ramp`
Prepare path	`/stocks/on-ramp/{buy contract address}/prepare-execute-transaction`	`/stocks/off-ramp/{sell contract address}/prepare-execute-transaction`
Amount field	`liquidityAmount`: USDC to spend	`assetAmount`: stock tokens to sell
`minOutputAmount`	Fewest stock tokens accepted	Least USDC accepted

The examples use $BASE for the base URL and a stock token with 9 decimals. Your Securitize contact gives you each stock’s contract addresses, tokenId and decimals (Amounts and assets).

1. Get a real-time price

curl "$BASE/stocks/realtime-price?investorId=6b31c0e9a4f2d17e85c3b904&symbol=AAPL&side=on-ramp&amount=1000000000" \
  -H "x-api-key: $STOCKS_API_KEY"

{
  "symbol": "AAPL/USD",
  "bestBid": "231.220000000000000000",
  "bestAsk": "231.250000000000000000",
  "lastPrice": "231.240000000000000000",
  "marketStatus": "OPEN",
  "reason": null,
  "validFrom": "2026-10-16T14:17:40.118Z",
  "validUntil": "2026-10-16T14:17:42.118Z",
  "signedPrice": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzeW1ib2wiOiJBQVBML1VTRCJ9.c2lnbmF0dXJl"
}

Show it on the order ticket and the confirmation screen, with its venues (Prices and market data).
Fetch it on a fixed cadence while the ticket is open, not on every keystroke: each investor can make one call a second and sixty an hour, and the same again to prepare and to submit.
Two expiries, two jobs. validUntil is how long the quote itself is current, about 2 seconds: refresh what you show by then. signedPrice is what the order is checked against: it expires about 20 seconds after it is issued, and the order is priced at the quote it signed. Prepare the order within those 20 seconds.
marketStatus UNAVAILABLE means no trading now. CLOSED is pre-market or post-market and can be traded. See Market status.

2. Prepare the order

A buy: spend 1,000 USDC at a best offer of 231.25, accepting 0.5% slippage, so at least 4.3027 tokens (how to work that out).

curl -X POST "$BASE/stocks/on-ramp/BuyCtr7nQ2vXcR8yLmB3hW9sJdE6aK1uNqG5tYpC2rVx/prepare-execute-transaction" \
  -H "x-api-key: $STOCKS_API_KEY" -H "content-type: application/json" -d '{
  "investorId": "6b31c0e9a4f2d17e85c3b904",
  "signedPrice": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzeW1ib2wiOiJBQVBML1VTRCJ9.c2lnbmF0dXJl",
  "slippageBps": "50",
  "liquidityAmount": "1000000000",
  "minOutputAmount": "4302702702"
}'

A sell sends assetAmount instead of liquidityAmount, to the stock’s sell contract address.

{
  "unsignedTransaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "additionalData": { "anchorPrice": "231250000000000000000", "operator": "Gp3ratorRoutr9sXcR8yLmB3hW9sJdE6aK1uNqG5tYpC" }
}

The transaction is built for the investor’s linked wallet, with the signed price and the swap already in it, and Securitize’s signature on it. Securitize pays its network fee. If this is the investor’s first trade in the stock, it also whitelists their wallet for it. Things that commonly go wrong:

EXPIRED_PRICE: the signed price expired, or the market moved since the quote. Fetch a new price, show it, and prepare again.
minOutputAmount is the investor’s protection, and the bound enforced on chain: below it, the trade reverts and nothing moves. See below.
INVALID_AMOUNT: an amount is not positive, has more decimals than the token allows, or the order’s value is outside the per-order limits.
MAX_POSITION: a buy would take the investor’s position in the stock over its limit.
Use the right contract address. A stock has one for buying and one for selling; the wrong one answers SYMBOL_NOT_FOUND.

Working out `minOutputAmount`

Work it out in whole units from the quote the investor accepted and their slippage, then convert to base units, rounding down. USDC has 6 decimals; the stock token’s come from your Securitize contact.

Order	`minOutputAmount` in whole units	Then, to base units
Buy	`liquidityAmount ÷ 10^6 ÷ bestAsk × (1 − slippageBps ÷ 10,000)` stock tokens	× `10^tokenDecimals`
Sell	`assetAmount ÷ 10^tokenDecimals × bestBid × (1 − slippageBps ÷ 10,000)` USDC	× `10^6`

Example	Whole units	`minOutputAmount`
Buy 1,000 USDC at a best offer of 231.25, 50 bps	1,000 ÷ 231.25 × 0.995 = 4.302702… tokens	`"4302702702"` (9 decimals)
Sell 2 tokens at a best bid of 231.22, 50 bps	2 × 231.22 × 0.995 = 460.1278 USDC	`"460127800"`

Skipping the conversion leaves a buy’s floor 10^(tokenDecimals − 6) times too low (a thousand times for a 9-decimal token), and the slippage protection goes with it. Use decimal arithmetic, never floating point. slippageBps itself is recorded with the order.

3. The investor signs

Relay unsignedTransaction to your frontend and have the investor’s wallet sign it, unchanged. With a Solana wallet, for example:

import { VersionedTransaction } from '@solana/web3.js';

const tx = VersionedTransaction.deserialize(Buffer.from(unsignedTransaction, 'base64'));
const signed = await wallet.signTransaction(tx);           // sign only: never send it from the wallet
const signedTransaction = Buffer.from(signed.serialize()).toString('base64');

Never modify it. It carries a signed price and a validated swap instruction; any change invalidates it on chain and the trade reverts.
Sign, do not send. Securitize broadcasts the transaction: that is what makes it an order executed by Securitize Markets. Use the wallet’s sign-only call, never sign-and-send.
This signature is the order. It is the investor’s acceptance at the price and terms on your confirmation screen, which is why that screen carries the price, the amounts and the best execution acknowledgement.

4. Submit it

Within 120 seconds of the prepare:

curl -X POST "$BASE/stocks/execute-signed-transaction" -H "x-api-key: $STOCKS_API_KEY" -H "content-type: application/json" -d '{
  "investorId": "6b31c0e9a4f2d17e85c3b904",
  "signedTransaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA…",
  "tokenId": "3f7b2c1e-9d4a-4e6b-8a1f-5c2d0e9b7a46"
}'

{ "transactionHash": "4ZkPfQ7nT2vXcR8yLmB3hW9sJdE6aK1uNqG5tYpC2rVxF8bH7jS3mD9wL6eA1zQ4oU5iT2nR8yK3cX7vB1mP" }

The order is firm and broadcast. Follow the transaction on chain by its hash: confirmed means executed and settled; reverted means nothing moved, and the investor places a new order.

Submit each prepared transaction once. A second submission of the same one answers 409 TRADE_IN_PROGRESS, or 400 UNAVAILABLE_MARKET once the first has been taken. Never resubmit to find out what happened: read the chain.
After 120 seconds, the transaction can no longer be submitted (UNAVAILABLE_MARKET). Prepare it again, with a new price.
tokenId must be the stock the order was prepared for.

What happens on chain

The Securitize router program checks Securitize’s signature and the investor’s, that the price has not expired and is still acceptable, and that the fill meets minOutputAmount. It then fills the order against the market maker and moves both assets, in the same transaction. There is no separate clearing or settlement cycle: delivery versus payment, atomically, the same day. If any check fails, the transaction reverts and nothing moves. Three moments, each with its own record:

Moment	What it is
The investor signs	Acceptance of the order, against a price with a hard expiry
Securitize broadcasts	The order becomes firm and routed
The swap confirms on chain	The execution, which drives trade reporting

Get started

Guides

Concepts

Help

API reference

1. Get a real-time price

2. Prepare the order

Working out `minOutputAmount`

3. The investor signs

4. Submit it

What happens on chain

1. Get a real-time price

2. Prepare the order

Working out minOutputAmount

3. The investor signs

4. Submit it

What happens on chain

Working out `minOutputAmount`