21X Integration Guide

A reference for partners connecting to 21X.

1. Introduction

21X is a multi-chain regulated exchange. Secondary-market trading is executed on a smart-contract orderbook, with each trading pair pinned to a specific blockchain. Two chains are exposed in the proof-of-concept (POC) environment:

• Polygon Amoy — EVM orderbook contract, ERC-20 token approvals, EVM transactions.

• Stellar Testnet — Soroban orderbook contract, Soroban token approvals, Soroban contract invocations.

The 21X REST API (Market View) is the single source for trading-pair discovery across both chains. It returns the target chain, the orderbook and token contract addresses, the scaling factors used to encode orders, the trading status, and public market data.

Order placement and cancellation are not REST operations. Both chains require the trading wallet to sign and submit a blockchain transaction directly to the active orderbook contract. REST is used for discovery and market visibility only.

2. Getting started

Before integrating, complete the following:

1. Confirm which chains and trading pairs your integration will cover. Each pair is bound to either Polygon Amoy or Stellar Testnet; you must support the chain associated with each pair you trade.

2. Prepare a scripting language of your choice (Python, TypeScript, Java, Go).

3. Prepare a REST API client such as Postman to test market-data calls and inspect responses.

4. For Polygon: prepare an EVM wallet on Polygon Amoy with POL test gas, and an EVM library such as ethers.js, web3.js, viem, or web3.py.

5. For Stellar: install the Stellar CLI or a Soroban-capable SDK, and prepare a funded testnet account.

6. Coordinate with 21X to obtain whitelist/client authorization on the target orderbooks and beneficiary or trustline authorization on the relevant tokens.

Production note. Production REST URLs, contract addresses, custody and signing requirements, and authentication and onboarding details must be obtained from 21X before go-live. Do not hardcode POC contract addresses in production systems.

3. How to connect

21X exposes two integration surfaces relevant to this guide:

1. REST API. Provides access to structured market data, including instrument metadata, contract addresses, scales, public orderbook snapshots, price levels, reference prices, and trade information.

2. Smart contract interface. Used for direct on-chain interactions, particularly for executing secondary-market orders and cancellations.

The high-level integration flow is the same for both chains:

Discover the pair via REST
  -> read chain, contract addresses, scales, limits, status, and fees
  -> prepare wallet/account and permissions on the target chain
  -> fund native fees and trading-token balances
  -> approve the orderbook to transfer or lock the relevant tokens
  -> encode the order using the target chain's expected format
  -> simulate or dry-run the transaction
  -> submit the blockchain transaction
  -> monitor events, balances, REST market data, and order history
  -> cancel pending orders when needed

3.1 REST environment

POC REST base URL
https://ex.str2.poc.21x.eu/api/v1/

Primary pair discovery
GET https://ex.str2.poc.21x.eu/api/v1/tradingpairs

3.2 Polygon Amoy environment

Network:           Polygon Amoy testnet
Chain ID:          80002
Native gas token:  POL / MATIC test token
RPC URL:           https://rpc-amoy.polygon.technology
POC pair:          USMO / 21XUSDQ

3.3 Stellar Testnet environment

Network:             Stellar Testnet
Network passphrase:  Test SDF Network ; September 2015
RPC URL:             https://soroban-testnet.stellar.org
POC pair:            XAMA1 / XUSDT

4. Market View (REST)

Use the REST API to discover active instruments, target chains, orderbook contracts, token contracts, scales, limits, fees, market status, and public orderbook state. The blockChain field on each pair determines whether the order is executed on Polygon or Stellar.

4.1 Discovering pairs

curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs" | jq .

The response is an object, not a top-level array:

{
  "items": [ /* one entry per active trading pair */ ],
  "total_count": <integer>
}

Iterate over .items[] in every example below. A snippet that treats the response as a top-level array (jq '.[]') will return nothing.

4.2 Trading pair fields

Field	Purpose
id	REST trading pair identifier.
blockChain	Target execution chain, for example POLYGON_AMOY or STELLAR_TESTNET.
baseTokenData.symbol	Base asset display symbol.
quoteTokenSymbol	Quote asset display symbol.
smartContractOrderBook	Blockchain address of the orderbook contract. Orders must be sent to this address.
smartContractBase	Blockchain address of the base (financial instrument) token contract.
smartContractQuote	Blockchain address of the quote (e-money) token contract.
baseTokenInternalScale	Scale used for base quantity in order encoding.
quoteTokenInternalScale	Scale used for quote price in order encoding.
baseTokenNativeScale	Native scale used for base token balances and transfers.
quoteTokenNativeScale	Native scale used for quote token balances and transfers.
minimumOrderValue / maximumOrderValue	Pre-trade order value limits.
makerCommission / takerCommission	Commission parameters.
staticReferencePrice	Reference price used by market controls.
staticThreshold / dynamicThreshold	Volatility-management thresholds.
priceCollarFactor	Pre-trade control parameter.
tradingStatus	Current trading status. Submit orders only when the market is open or in continuous trading.
orderBookVersion	Version of the deployed orderbook contract.

4.3 Selecting the right pair

The POC environment exposes several active pairs across both chains, including pairs whose symbols differ by a single prefix (for example AMA1/XUSDT and XAMA1/XUSDT are both Stellar Testnet pairs). Match all four of blockChain, baseTokenData.symbol, quoteTokenSymbol, and ideally the explicit id when filtering. Do not rely on a partial symbol match alone.

# Filter by chain + exact symbols + id (recommended)
curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs" | jq '
  .items[]
  | select(.id == "57472b2c-4215-4cdf-935e-63226ebd004b")
  | select(.blockChain == "POLYGON_AMOY")
  | select(.baseTokenData.symbol == "USMO")
  | select(.quoteTokenSymbol == "21XUSDQ")
'

Read this before hardcoding. Symbols are not unique across pairs. Always select by id for the trading flow you are building, and treat the addresses returned alongside the id as the source of truth for that environment.

4.4 Public market endpoints

PAIR_ID="<TRADING_PAIR_ID>"

curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID" | jq .
curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID/orderbook?limit=5" | jq .
curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID/pricelevels?limit=5" | jq .
curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID/tradeinfo" | jq .

The tradeinfo endpoint returns last price, reference price, trade volume, and trading status.

4.5 POC pairs

Chain	Pair	Trading pair id	Orderbook
POLYGON_AMOY	USMO / 21XUSDQ	57472b2c-4215-4cdf-935e-63226ebd004b	0x3e9d9dC85C5De625942483dfa16d20B049254117
STELLAR_TESTNET	XAMA1 / XUSDT	50a1b1ec-b46a-459e-9359-57412351e45f	CCGMSRH63Z7SAQVRH3O4VHOXMLWJZ2MOYWHWMQF7RKUJCBUYWWBQ35RQ

Always discover the active addresses through the REST API for the target environment. The values above are POC defaults and are subject to change.

4.6 REST authentication

Public market endpoints — /tradingpairs, /tradingpairs/{id}, /orderbook, /pricelevels, /tradeinfo — do not require authentication. Participant-scoped endpoints for wallet, order, and trade history require a bearer token issued by 21X to your sandbox account; calls without it return HTTP 401. Request credentials when you request your sandbox.

Authenticated history endpoints are out of scope for this guide. Until your integration uses them, treat the on-chain events emitted by the orderbook contract (see §6.8 and §7.10) as the source of truth for order state.

5. Order model

5.1 Buy and sell

• Buy order. The participant buys the base asset and pays the quote asset. The orderbook may pre-fund or transfer the quote token.

• Sell order. The participant sells the base asset and receives the quote asset. The orderbook may lock or transfer the base token, depending on configuration.

When the side value appears in events or struct fields, it uses the same enum on both chains:

Value	Side
1	Buy
2	Sell

5.2 Limit vs market

Value	Type	Behaviour
0	Limit	The order has a specified price. Any unmatched remainder may rest on the book, depending on the execution condition.
1	Market	The order executes immediately against available liquidity and does not rest on the book.

5.3 Execution conditions

Value	Name	Behaviour	Typical use
0	Standard	Match where possible; any unmatched limit remainder rests on the book.	Normal limit orders.
1	Immediate or Cancel (IOC)	Match what is immediately available; cancel any unfilled remainder.	Take available liquidity only.
2	Book or Cancel (BOC)	Rest on the book only if the order would not immediately match. Reject if it would cross.	Post-only / maker-only orders.
3	Fill or Kill (FOK)	Execute the full quantity immediately or reject the entire order. No partial fill.	All-or-nothing immediate execution.

An IOC or FOK order submitted against an empty or non-crossing book is rejected. The transaction itself succeeds and emits an OrderRejected event with a quantity_not_executed equal to the original quantity.

5.4 Validity constraints

Value	Name	Meaning
0	Good For Day (GFD)	Default validity for limit orders.
1	Good Till Date (GTD)	Valid for the number of days specified in the lifetime field.

Rules for lifetime:

• Expressed in days. Valid range is 0 to 90.

• lifetime = 0 is accepted and behaves as the venue default.

• lifetime > 90 is invalid and should be rejected by client-side validation before submission.

• The field is only meaningful for limit orders that set validityConstraints = 1 (GTD).

5.5 Scaling

Orders are encoded with integer values derived from the internal scales returned by REST. Convert human values to scaled integers before encoding:

quantityRaw = humanBaseQuantity * baseTokenInternalScale
priceRaw    = humanQuotePrice   * quoteTokenInternalScale

Use decimal-safe arithmetic. Do not use binary floating point. Examples:

USMO / 21XUSDQ on Polygon Amoy
  baseTokenInternalScale  = 1000
  quoteTokenInternalScale = 100
  1.000 USMO @ 100.00 21XUSDQ
    quantityRaw = 1.000 * 1000 = 1000
    priceRaw    = 100.00 * 100 = 10000

XAMA1 / XUSDT on Stellar Testnet
  baseTokenInternalScale  = 10,000,000
  quoteTokenInternalScale = 10,000,000
  100 XAMA1 @ 1.05 XUSDT
    quantityRaw = 100 * 10,000,000  = 1,000,000,000
    priceRaw    = 1.05 * 10,000,000 = 10,500,000

5.6 Order lifecycle

1. Pending orders may lock or transfer the relevant token into the orderbook, depending on the pair configuration.

2. Some pairs do not pre-fund the base token, the quote token, or both. In those configurations, no token is transferred when the order becomes pending.

3. Matching orders settle base and quote token movements on chain. If a pending order is not pre-funded and the required balance is no longer available at matching time, the pending order is cancelled.

4. Cancellation removes the order from the book. Any tokens that were locked or transferred are returned according to the pair configuration.

5. Order ids are emitted by the orderbook in OrderReceived, NewBuyOrder, and NewSellOrder events. Persist them for cancellation and reconciliation.

6. Polygon Amoy execution

Polygon execution uses an EVM orderbook contract. Trading wallets must be whitelisted by 21X for buy, sell, and cancel; restricted tokens additionally require beneficiary status on the receiving wallet.

6.1 USMO / 21XUSDQ pair

Field	Value
Trading pair id	57472b2c-4215-4cdf-935e-63226ebd004b
Blockchain	POLYGON_AMOY
Orderbook	0x3e9d9dC85C5De625942483dfa16d20B049254117
Base token	0x26e1C59fD903aD3Fe6CB4c786E364b79683E0A75
Base token contract symbol	BMAT02 (REST/display symbol: USMO)
Base token decimals	3
Quote token	0xb04969523f8c1C3A81bBF07d73d32F772A0afd6f
Quote token symbol	21XUSDQ
Quote token decimals	6
Base internal / native scale	1000 / 1000
Quote internal / native scale	100 / 1000000
Minimum order value	90
Maximum order value	10000000.00
Static reference price	100.00
Maker / taker commission	10 / 10
Orderbook version	1.0.0

6.2 Prerequisites

Requirement	What it controls	Failure mode
21X whitelist	Whether the wallet is allowed to buy, sell, or cancel on the orderbook.	OrderBook_NotAllowedToBuy / OrderBook_NotAllowedToSell
Token beneficiary status	Whether the wallet can receive a restricted token.	Receiver must be a beneficiary
ERC-20 allowance	Whether the orderbook can transfer or lock tokens from the wallet.	ERC20InsufficientAllowance
Token balance	Whether the wallet has sufficient base or quote balance for the order.	ERC20InsufficientBalance or simulation revert
Native gas	POL / MATIC test gas to pay transaction fees.	Transaction will not be mined.

For a matched trade, both sides must be authorised to receive the asset they will get on settlement: a buyer must be able to receive the base token, a seller must be able to receive the quote token.

6.3 Reading contract state

Read on-chain configuration and orderbook state with any EVM library. The example below uses ethers.js.

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("https://rpc-amoy.polygon.technology");
const orderbook = "0x3e9d9dC85C5De625942483dfa16d20B049254117";

const orderbookAbi = [
  "function getConfig() view returns (tuple(tuple(tuple(uint128 nonNative,uint128 native) base,tuple(uint128 nonNative,uint128 native) quote) scales,uint64 makerCommission,uint64 takerCommission,uint64 marketMakerCommission,address quoteToken,address baseToken,address whitelist,address commissionWallet,address baseTokenFallbackWallet,address quoteTokenFallbackWallet,uint8 liquidityBand,bytes11 version))",
  "function getOrderBookPhase() view returns (uint8)",
  "function countBuyOrders() view returns (uint256)",
  "function countSellOrders() view returns (uint256)",
  "function bestFiftyOffers() view returns (uint256[],uint256[])",
];

const ob = new ethers.Contract(orderbook, orderbookAbi, provider);
console.log(await ob.getOrderBookPhase()); // 1 = open for trading
console.log(await ob.countBuyOrders());
console.log(await ob.countSellOrders());

The Polygon orderbook returns the phase as a uint8. Value 1 corresponds to the open / continuous trading state, which is exposed by the REST tradingStatus field as CONTINUOUS_TRADING. Submit orders only when the contract phase is 1 and the REST status is CONTINUOUS_TRADING.

6.4 Order encoding

The Polygon orderbook expects a two-field orderData payload:

abi.encode(uint64 quantity, uint64 price)

const orderData = ethers.AbiCoder.defaultAbiCoder().encode(
  ["uint64", "uint64"],
  [quantityRaw, priceRaw]
);

const reportingData = ethers.AbiCoder.defaultAbiCoder().encode(
  ["uint32", "uint32"],
  [0, 0]
);

const crossIdentifier = ethers.AbiCoder.defaultAbiCoder().encode(
  ["uint32"],
  [0]
);

Polygon-only constraint. The Polygon POC orderbook does not accept extended order layouts that include order type, execution condition, validity constraints, or lifetime. Submissions using abi.encode(uint64,uint64,uint8,uint8,uint8), solidityPacked, or single packed words revert with OrderBook_InvalidInputOrderData. Extended layouts are supported on Stellar (see §7.6).

The reportingData and crossIdentifier shapes above match the 21X SDK v1.0.1 conventions.

Default scheme. Use zero-valued placeholders unless 21X has explicitly agreed a participant-specific scheme with you. For Polygon, the sandbox-safe defaults are two zero uint32 words for reportingData and one zero uint32 word for crossIdentifier, as shown above.

crossIdentifier is an optional client correlation field, not an exchange-side sequence number. Do not increment it just because orders are submitted sequentially. Use a non-zero value only when your integration has a defined reconciliation need for it and you are certain how that value will be generated, stored, and interpreted across your systems.

reportingData is a raw reporting and attribution field. Use the zero-placeholder shape for sandbox integrations unless 21X provides a production reporting schema.

6.5 Approving tokens

Approve the orderbook as ERC-20 spender for each token the wallet must transfer. The buy side approves the quote token; the sell side approves the base token.

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("https://rpc-amoy.polygon.technology");
const orderbook = "0x3e9d9dC85C5De625942483dfa16d20B049254117";
const baseAddress  = "0x26e1C59fD903aD3Fe6CB4c786E364b79683E0A75";
const quoteAddress = "0xb04969523f8c1C3A81bBF07d73d32F772A0afd6f";

const erc20Abi = [
  "function approve(address spender,uint256 amount) returns (bool)",
  "function allowance(address owner,address spender) view returns (uint256)",
  "function balanceOf(address owner) view returns (uint256)",
];

// Signers must be configured through local keys or the partner custody stack.
const buyer  = new ethers.Wallet("<BUYER_PRIVATE_KEY>",  provider);
const seller = new ethers.Wallet("<SELLER_PRIVATE_KEY>", provider);

const quote = new ethers.Contract(quoteAddress, erc20Abi, buyer);
const base  = new ethers.Contract(baseAddress,  erc20Abi, seller);

// Buy 1.000 USMO @ 100.00 21XUSDQ requires notional + commission.
// In raw units: 100.00 * 1_000_000 = 100_000_000, plus a 0.1% commission
// margin -> approve 100_100_000.
await quote.approve(orderbook, 100_100_000n);

// Sell 1.000 USMO requires 1.000 base = 1000 raw units.
await base.approve(orderbook, 1000n);

Approve enough quote balance to cover both the order notional and the commission charged by the orderbook. Approving only the notional results in ERC20InsufficientAllowance when the trade settles.

6.6 Submitting orders

Always dry-run with staticCall before broadcasting:

const orderbookAbi = [
  "function newBuyOrder(bytes orderData, bytes reportingData, bytes crossIdentifier)",
  "function newSellOrder(bytes orderData, bytes reportingData, bytes crossIdentifier)",
  "function cancelBuyOrder(uint64 orderId)",
  "function cancelSellOrder(uint64 orderId)",
];

const obAsBuyer  = new ethers.Contract(orderbook, orderbookAbi, buyer);
const obAsSeller = new ethers.Contract(orderbook, orderbookAbi, seller);

await obAsBuyer.newBuyOrder.staticCall(orderData, reportingData, crossIdentifier);
await obAsSeller.newSellOrder.staticCall(orderData, reportingData, crossIdentifier);

const buyTx = await obAsBuyer.newBuyOrder(orderData, reportingData, crossIdentifier);
await buyTx.wait();

const sellTx = await obAsSeller.newSellOrder(orderData, reportingData, crossIdentifier);
await sellTx.wait();

When a buy rests on the book, quote tokens are transferred or locked. When a matching sell arrives, the trade settles and, on full match, the book returns to empty for that order.

6.7 Cancelling orders

Cancellation is signed by the order owner and submitted as an EVM transaction. orderId is read from OrderReceived, NewBuyOrder, or NewSellOrder events emitted when the order was created.

const ob = new ethers.Contract(orderbook, orderbookAbi, wallet);

await ob.cancelBuyOrder(59n);
await ob.cancelSellOrder(62n);

Only the owning wallet can cancel its own order, and only while the order is still resting on the book.

6.8 Events

The Polygon orderbook emits events with client and orderId as indexed parameters. Plain (non-indexed) ABI definitions decode incorrectly: the orderId appears in topics[2], not in the data body, and an ABI without the indexed keyword will silently fail to extract it. Use the definitions below verbatim.

event OrderReceived(
    address indexed client,
    uint64  indexed orderId,
    uint64  quantity,
    uint64  price,
    uint8   side,
    bytes   reportingData,
    uint64  crossIdentifier,
    uint8   orderType,
    uint8   executionCondition
);

event NewBuyOrder (address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId);
event NewSellOrder(address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId);

event CancelOrder(
    address indexed client,
    uint64  indexed orderId,
    uint64  quantity,
    uint64  price,
    uint8   cancellationType, // 0 ByParticipant, 1 ByAdmin, 2 ByContract
    address token,
    address toAddress
);

Topic-0 (event signature) hashes for log filtering:

Event	Topic-0
OrderReceived	0x4ac0c3adc766818e295a0a09fe6df33885dcc7b63043a3f99be52297b68ae0eb
NewBuyOrder	0x98b9ce6d33873528f10e868c50b6c2bf164c03e4731d7efee4e1432c5369d279
NewSellOrder	0x17cb6f48b3b2e7c6dd37bfea8d4ee3dd5a44c3b601424ec885b7adf099b64e5f
CancelOrder	0xac5175c97a30bd4146ee235883daa9602c4c685ef485916ebb4796d4fc868d9a

Lifecycle:

• OrderReceived is emitted when the orderbook accepts the submission for processing. The side field follows the enum in §5.1 (1 = Buy, 2 = Sell).

• NewBuyOrder / NewSellOrder is emitted when the (remaining) order rests on the book. A fully-matched incoming order does not produce these events.

• CancelOrder is emitted when an order is removed; token and toAddress identify the asset returned and the receiving wallet.

• Token Transfer events from the base or quote ERC-20 contract are emitted alongside lifecycle events and reflect the actual balance movements.

6.9 Allowance behaviour

The orderbook pre-funds resting orders by calling transferFrom on the relevant token: a sell-side resting order moves the base token from the wallet into the orderbook, and a buy-side resting order moves the quote token (notional plus commission). ERC-20 allowance is consumed by that transfer.

Cancellation returns the locked token balance to the wallet but does not restore the consumed allowance. After cancellation, re-approve the orderbook before placing another order, or maintain a standing approval that is large enough to absorb expected churn.

7. Stellar Testnet execution

Stellar execution uses a Soroban orderbook contract. Compared to the Polygon flow, Stellar additionally requires trustlines for non-native assets and uses an expiration_ledger on token approvals.

7.1 XAMA1 / XUSDT pair

Field	Value
Trading pair id	50a1b1ec-b46a-459e-9359-57412351e45f
Blockchain	STELLAR_TESTNET
Orderbook	CCGMSRH63Z7SAQVRH3O4VHOXMLWJZ2MOYWHWMQF7RKUJCBUYWWBQ35RQ
Base token	CCAVB4PVYQED74TETVAPWS3MIRSITNKQFVB7Q6WPTSTMJF3WFATTRHO3
Quote token	CBU53REE7UH7DHI2DEZXTRXMTJJS5FODBDMO7M7H6EGVUXEG5ZJSARKK
Base symbol	XAMA1
Quote symbol	XUSDT
Base internal / native scale	10,000,000 / 10,000,000
Quote internal / native scale	10,000,000 / 10,000,000
Minimum order value	20.0000000
Maximum order value	1000000.0000000
Trading status	CONTINUOUS_TRADING
Orderbook version	1.2.0

7.2 Stellar CLI setup

Install the Stellar CLI and confirm the version:

stellar --version

Configure the testnet network:

stellar network add testnet \
  --rpc-url "https://soroban-testnet.stellar.org" \
  --network-passphrase "Test SDF Network ; September 2015"

Import or generate a local signing identity:

# Existing secret key
printf '%s' '<STELLAR_SECRET_KEY>' | stellar keys add my-test-account --secret-key --overwrite


# Or generate and fund a new test account
stellar keys generate my-test-account --network testnet --fund

The local alias (for example my-test-account) is used as the --source-account on every contract invocation.

--source-account vs --user

The orderbook methods take an explicit user: Address parameter. The CLI also takes a --source-account flag for the local signing identity. The two must be reconciled:

• --source-account is the local alias that signs and broadcasts the transaction. The corresponding account pays the network fee.

• --user is the on-chain Stellar address whose action this is. The orderbook resolves the participant against its client registry using this value, and the contract calls require_auth(user).

For a self-trading flow, set --source-account and --user to the same identity; the source signature satisfies require_auth(user) and the orderbook reads the participant's client info for the same address. For a custodial flow where the trading account is signed for by a different submitter, the user must additionally provide a Soroban authorization entry for the call. The participant whitelist applies to --user, not to --source-account.

7.3 Trustlines and authorization

Trustlines and allowances are independent prerequisites:

Requirement	What it does	Why it matters
Trustline	Allows the Stellar account to hold a non-native asset.	Required before the account can receive or hold the asset.
21X authorization	Issuer / whitelist permission for the participant.	Required before the orderbook accepts orders from the account.
Allowance	Permits the orderbook to transfer the participant's token balance up to an approved amount.	Required before the orderbook can lock or pre-fund tokens.

The orderbook participant interface uses a ClientInformation structure for permissioning:

pub struct ClientInformation {
    pub can_buy: bool,
    pub can_cancel: bool,
    pub can_sell: bool,
    pub can_transfer: bool,
    pub client: Address,
    pub id: u64,
    pub is_market_maker: bool,
}

If the participant is not registered or lacks a permission, order placement fails with ClientNotFound, NotAllowedToBuy, NotAllowedToSell, or NotAllowedToCancel.

Create trustlines and check authorization and balances:

USER="<USER_G_ADDRESS>"
ORDERBOOK="<smartContractOrderBook>"
BASE="<smartContractBase>"
QUOTE="<smartContractQuote>"
ALIAS="<LOCAL_SIGNING_ALIAS>"


# Trustlines are safe to repeat.
stellar contract invoke --network testnet --id "$BASE" \
  --source-account "$ALIAS" --send=yes -- trust --addr "$USER"
stellar contract invoke --network testnet --id "$QUOTE" \
  --source-account "$ALIAS" --send=yes -- trust --addr "$USER"


# Confirm token authorization and balances.
stellar contract invoke --network testnet --id "$BASE" \
  --source-account "$ALIAS" --send=no -- authorized --id "$USER"
stellar contract invoke --network testnet --id "$QUOTE" \
  --source-account "$ALIAS" --send=no -- authorized --id "$USER"

stellar contract invoke --network testnet --id "$BASE" \
  --source-account "$ALIAS" --send=no -- balance --id "$USER"
stellar contract invoke --network testnet --id "$QUOTE" \
  --source-account "$ALIAS" --send=no -- balance --id "$USER"

7.4 Allowances

Soroban approvals carry an expiration_ledger. Read the latest testnet ledger and pick a future ledger high enough for the intended trading window:

CURRENT_LEDGER="$(stellar ledger latest --network testnet | awk '/Sequence:/ {print $2}')"
EXPIRATION_LEDGER="$((CURRENT_LEDGER + 100000))"
ALLOWANCE="1000000000000"

stellar contract invoke --network testnet --id "$BASE" \
  --source-account "$ALIAS" --send=yes -- approve \
  --from "$USER" --spender "$ORDERBOOK" \
  --amount "$ALLOWANCE" \
  --expiration_ledger "$EXPIRATION_LEDGER"

stellar contract invoke --network testnet --id "$QUOTE" \
  --source-account "$ALIAS" --send=yes -- approve \
  --from "$USER" --spender "$ORDERBOOK" \
  --amount "$ALLOWANCE" \
  --expiration_ledger "$EXPIRATION_LEDGER"

stellar contract invoke --network testnet --id "$BASE" \
  --source-account "$ALIAS" --send=no -- allowance \
  --from "$USER" --spender "$ORDERBOOK"
stellar contract invoke --network testnet --id "$QUOTE" \
  --source-account "$ALIAS" --send=no -- allowance \
  --from "$USER" --spender "$ORDERBOOK"

Approve both the base token (used by sell-side flows) and the quote token (used by buy-side flows). Refresh allowances before they expire or run out.

The CLI returns the allowance as a single numeric amount (for example "10000000000"). The associated expiration_ledger is internal state and is not echoed back; track it locally when you set the allowance.

Pre-fund configuration. Some POC deployments expose a no_prefund_config in get_config. Where the active configuration permits it, a sell order can be accepted without an immediate base-token transfer. Do not rely on this globally — always read get_config and treat the simulation result as authoritative for the current orderbook deployment.

7.5 Inspecting the orderbook

Participant-facing orderbook methods:

fn new_buy_order  (user: Address, order_data: Bytes, cross_identifier: Bytes, reporting_data: Bytes);
fn new_sell_order (user: Address, order_data: Bytes, cross_identifier: Bytes, reporting_data: Bytes);
fn cancel_buy_order  (user: Address, order_id: u64);
fn cancel_sell_order (user: Address, order_id: u64);

View / configuration methods:

fn get_config()           -> OrderBookConfigData;
fn get_order_book_phase() -> OrderBookPhase;     // string enum, e.g. "OpenForTrading"
fn count_buy_orders()     -> u64;
fn count_sell_orders()    -> u64;
fn best_bid_offer()       -> U256;
fn best_fifty_offers()    -> (Vec<U256>, Vec<U256>);

The CLI renders get_order_book_phase as a quoted string (for example "OpenForTrading"), not as the integer used by the Polygon orderbook. Compare against the string symbol when gating order placement.

Inspect the deployed interface, phase, and configuration with the CLI:

stellar contract invoke --network testnet \
  --id "$ORDERBOOK" --source-account "$ALIAS" --send=no -- --help

stellar contract invoke --network testnet \
  --id "$ORDERBOOK" --source-account "$ALIAS" --send=no -- get_order_book_phase

stellar contract invoke --network testnet \
  --id "$ORDERBOOK" --source-account "$ALIAS" --send=no -- get_config

7.6 Order encoding

Although order_data is a Soroban Bytes value, the 21X orderbook expects EVM-style 32-byte padded words. Do not encode as compact u64 || u64 bytes.

Field layout:

Position	Field	Type	Description
1	quantity	uint64 as 32-byte word	Scaled base quantity.
2	price	uint64 as 32-byte word	Scaled quote price.
3	orderType	uint8 as 32-byte word	0 = Limit, 1 = Market.
4	executionCondition	uint8 as 32-byte word	0 = Standard, 1 = IOC, 2 = BOC, 3 = FOK.
5	validityConstraints	uint8 as 32-byte word	0 = GFD, 1 = GTD.
6	lifetime	uint8 as 32-byte word	GTD lifetime in days. Valid range 0–90.

Common encodings

Minimal standard limit order
  word32(quantity) || word32(price)

Explicit standard limit order
  word32(quantity) || word32(price) || word32(0) || word32(0)

Explicit BOC limit order
  word32(quantity) || word32(price) || word32(0) || word32(2)

Explicit IOC limit order
  word32(quantity) || word32(price) || word32(0) || word32(1)

Explicit FOK limit order
  word32(quantity) || word32(price) || word32(0) || word32(3)

Explicit GTD limit order
  word32(quantity) || word32(price) || word32(0) || word32(executionCondition)
   || word32(1) || word32(lifetime_days)

Defaults when fields are omitted: orderType = 0 (Limit), executionCondition = 0 (Standard), validityConstraints = 0 (GFD), lifetime = 0.

Python helper

from decimal import Decimal

def word32(value: int) -> str:
    return int(value).to_bytes(32, "big").hex()

def scale_decimal(value: str, internal_scale: str) -> int:
    return int(Decimal(value) * Decimal(internal_scale))

def encode_order_data(
    quantity: str,
    price: str,
    base_scale: str,
    quote_scale: str,
    order_type: int = 0,
    execution_condition: int = 0,
) -> str:
    quantity_i = scale_decimal(quantity, base_scale)
    price_i    = scale_decimal(price,    quote_scale)
    return "".join([
        word32(quantity_i),
        word32(price_i),
        word32(order_type),
        word32(execution_condition),
    ])


# Example: 100 XAMA1 @ 1.05 XUSDT, Standard limit
order_data = encode_order_data(
    quantity="100",
    price="1.05",
    base_scale="10000000",
    quote_scale="10000000",
)
print(order_data)

Validating order_data

Validate the encoded payload before invoking the orderbook. A two-word payload is exactly 64 bytes (128 hex characters); a four-word explicit standard limit order is exactly 128 bytes (256 hex characters). Manually editing hex strings is a frequent source of malformed payloads — generate the value from decimal inputs instead.

ORDER_DATA="<ORDER_DATA_HEX>"

case "${#ORDER_DATA}" in
  128|256) ;;
  *) echo "Invalid order_data hex length: ${#ORDER_DATA}" >&2; exit 1 ;;
esac

case "$ORDER_DATA" in
  (*[!0-9a-fA-F]*) echo "Invalid order_data: expected hex only" >&2; exit 1 ;;
esac

A one-character truncation is enough to fail Soroban Bytes parsing before simulation. Fail fast on the client.

7.7 cross_identifier and reporting_data

cross_identifier is raw bytes that must decode to a u32. Use exactly 4 bytes of hex; an 8-byte value fails with InvalidInputOrderData (#2004).

00000000  -> 0

Default scheme. Use 00000000. cross_identifier is an optional field used in self-trade scenarios, request additional information from 21X in need.

reporting_data is a raw bytes field for reporting and attribution metadata. Default scheme: use the placeholder value 00 for sandbox integrations; this is accepted by the POC orderbook. Production sandboxes for regulated trading must embed a reporting identifier in this field — request the exact schema from 21X when you request your sandbox, alongside your participant credentials. The sandbox identity already includes the 00 placeholder, so a working integration can be built before the production schema is finalised.

The same defaulting approach applies on Polygon to reportingData and crossIdentifier. Use the zero-placeholder shapes shown in §6.4 unless 21X provides a production reporting or correlation scheme.

7.8 Submitting orders

Always simulate with --send=no before submitting with --send=yes:

stellar contract invoke \
  --network testnet \
  --id "$ORDERBOOK" \
  --source-account "$ALIAS" \
  --send=no \
  -- new_sell_order \
  --user "$USER" \
  --order_data "$ORDER_DATA" \
  --cross_identifier "$CROSS_IDENTIFIER" \
  --reporting_data "$REPORTING_DATA"

Sell example — 100 XAMA1 @ 1.20 XUSDT, Standard limit:

ORDERBOOK="CCGMSRH63Z7SAQVRH3O4VHOXMLWJZ2MOYWHWMQF7RKUJCBUYWWBQ35RQ"
USER="<USER_G_ADDRESS>"
ORDER_DATA="000000000000000000000000000000000000000000000000000000003b9aca000000000000000000000000000000000000000000000000000000000000b71b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
CROSS_IDENTIFIER="00000000"
REPORTING_DATA="00"

stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=yes \
  -- new_sell_order \
  --user "$USER" \
  --order_data "$ORDER_DATA" \
  --cross_identifier "$CROSS_IDENTIFIER" \
  --reporting_data "$REPORTING_DATA"

Buy example — 100 XAMA1 @ 0.80 XUSDT, Standard limit:

ORDER_DATA="000000000000000000000000000000000000000000000000000000003b9aca0000000000000000000000000000000000000000000000000000000000007a120000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
CROSS_IDENTIFIER="00000000"

stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=yes \
  -- new_buy_order \
  --user "$USER" \
  --order_data "$ORDER_DATA" \
  --cross_identifier "$CROSS_IDENTIFIER" \
  --reporting_data "$REPORTING_DATA"

7.9 Cancelling orders

Cancellation is a Soroban call signed by the order owner. Persist order_id from the OrderReceived event when the order is placed.

# Simulate
stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=no \
  -- cancel_sell_order --user "$USER" --order_id "$ORDER_ID"


# Submit
stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=yes \
  -- cancel_sell_order --user "$USER" --order_id "$ORDER_ID"

Use cancel_buy_order for buy-side cancellation. Cancelling a non-existent or already-cancelled order id fails with contract error #8; keep client-side order state idempotent.

7.10 Events and rejections

Soroban events are emitted as a topic vector plus a data vec. The Rust struct in the contract source defines the conceptual fields, but the on-chain emission places the most important participant-facing fields in the topic vector for cheap filtering, and the rest in the data body. Treat the topic vector as the stable source of truth: the order id, in particular, is a topic, not a data field, and parsers that look for a named order_id JSON key in the body will not find it.

Topic vector layout

Event	topic[0]	topic[1]	topic[2]
OrderReceived	symbol "OrderReceived"	address client	u64 order_id
NewBuyOrder	symbol "NewBuyOrder"	address client	—
NewSellOrder	symbol "NewSellOrder"	address client	—
CancelOrder	symbol "CancelOrder"	address client	u64 order_id
OrderRejected	symbol "OrderRejected"	address client	u64 order_id

For NewBuyOrder and NewSellOrder the order_id is the first u64 in the data body (alongside quantity, price, and event_id). Always read it from there for these two events, and from topic[2] for the others.

Sample payloads

// new_sell_order — resting on the book
topics: [{"symbol":"OrderReceived"}, {"address":"<client>"}, {"u64":"<order_id>"}]
data  : vec[ u64 quantity, u64 price, ..contract-specific.. , u128 event_id ]

topics: [{"symbol":"NewSellOrder"}, {"address":"<client>"}]
data  : vec[ u64 order_id, u64 quantity, u64 price, u128 event_id ]

// cancel_sell_order
topics: [{"symbol":"CancelOrder"}, {"address":"<client>"}, {"u64":"<order_id>"}]
data  : vec[ u64 quantity, u64 price, u32 cancellation_type, address token, address to_address, u128 event_id ]

The data-body ordering is contract-specific and may evolve across orderbook versions. Use the topic vector for the order id; use the data body for the trade-level numbers (quantity, price) and only as far as your integration genuinely needs them.

Reference enums

pub enum OrderKind     { Buy = 1, Sell = 2 }
pub enum OrderType     { Limit = 0, Market = 1 }
pub enum CancellationType { ByParticipant = 0, ByAdmin = 1, ByContract = 2 }

pub enum RejectionReasons {
    None = 0,
    SelfTrade = 1,
    MaxMatches = 2,
    CircuitBreakerPriceOutOfMaximumStaticRange  = 3,
    CircuitBreakerPriceOutOfMinimumStaticRange  = 4,
    CircuitBreakerPriceOutOfMaximumDynamicRange = 5,
    CircuitBreakerPriceOutOfMinimumDynamicRange = 6,
    PartialRejected = 7,
    FullyRejected   = 8,
}

Matching events

When an incoming order crosses existing liquidity, the orderbook emits a trade event in addition to (or in place of) the resting-order event. An incoming buy that matches a resting sell emits NewBuyInitiatedTrade. For a full match, the transaction emits OrderReceived, base/quote token transfer events, NewBuyInitiatedTrade, and commission transfer events; no NewBuyOrder is emitted because no remainder rests on the book. For a partial match where the incoming buy is larger than the available sell liquidity, the transaction emits NewBuyInitiatedTrade for the matched quantity and NewBuyOrder for the residual buy.

OrderRejected

The transaction succeeded but matching rules, controls, or execution-condition behaviour rejected the order or its remainder. Read order_id from the topic vector and the rejection details (reason, quantity_not_executed, side, price) from the data body.

7.11 End-to-end CLI script

The script below discovers the active XAMA1/XUSDT pair, creates trustlines, checks balances and authorization, sets allowances, submits a sell order, parses the order id from the CLI's emitted OrderReceived topic vector, cancels it, and prints final order counts. Filtering uses id in addition to symbols and chain to avoid selecting a similarly-named pair.

#!/usr/bin/env bash
set -euo pipefail

API="https://ex.str2.poc.21x.eu/api/v1/tradingpairs"
PAIR_ID="50a1b1ec-b46a-459e-9359-57412351e45f"
ALIAS="my-test-account"
USER="$(stellar keys address "$ALIAS")"
QTY="100"
SELL_PRICE="1.20"
CROSS_IDENTIFIER="00000000"
REPORTING_DATA="00"
ALLOWANCE="1000000000000"

PAIR_JSON="$(curl -s "$API" | jq -r --arg id "$PAIR_ID" '
  .items[]
  | select(.id == $id)
  | select(.blockChain == "STELLAR_TESTNET")
  | select(.baseTokenData.symbol == "XAMA1")
  | select(.quoteTokenSymbol == "XUSDT")
')"

ORDERBOOK="$(jq -r '.smartContractOrderBook' <<<"$PAIR_JSON")"
BASE="$(jq -r '.smartContractBase'      <<<"$PAIR_JSON")"
QUOTE="$(jq -r '.smartContractQuote'    <<<"$PAIR_JSON")"
BASE_SCALE="$(jq  -r '.baseTokenInternalScale'  <<<"$PAIR_JSON")"
QUOTE_SCALE="$(jq -r '.quoteTokenInternalScale' <<<"$PAIR_JSON")"
STATUS="$(jq -r '.tradingStatus' <<<"$PAIR_JSON")"

test "$STATUS" = "CONTINUOUS_TRADING"

word32() {
  python3 - "$1" <<'PY'
import sys
print(int(sys.argv[1]).to_bytes(32, "big").hex(), end="")
PY
}

scale_decimal() {
  python3 - "$1" "$2" <<'PY'
from decimal import Decimal
import sys
print(int(Decimal(sys.argv[1]) * Decimal(sys.argv[2])), end="")
PY
}

encode_order_data() {
  local quantity_i price_i
  quantity_i="$(scale_decimal "$1" "$BASE_SCALE")"
  price_i="$(scale_decimal "$2" "$QUOTE_SCALE")"
  printf '%s%s%s%s' \
    "$(word32 "$quantity_i")" \
    "$(word32 "$price_i")" \
    "$(word32 0)" \
    "$(word32 0)"
}

SELL_ORDER_DATA="$(encode_order_data "$QTY" "$SELL_PRICE")"
[ "${#SELL_ORDER_DATA}" -eq 256 ] || { echo "Invalid order_data length"; exit 1; }

stellar contract invoke --network testnet --id "$BASE" \
  --source-account "$ALIAS" --send=yes -- trust --addr "$USER"
stellar contract invoke --network testnet --id "$QUOTE" \
  --source-account "$ALIAS" --send=yes -- trust --addr "$USER"

CURRENT_LEDGER="$(stellar ledger latest --network testnet | awk '/Sequence:/ {print $2}')"
EXPIRATION_LEDGER="$((CURRENT_LEDGER + 100000))"

stellar contract invoke --network testnet --id "$BASE" \
  --source-account "$ALIAS" --send=yes -- approve \
  --from "$USER" --spender "$ORDERBOOK" \
  --amount "$ALLOWANCE" --expiration_ledger "$EXPIRATION_LEDGER"
stellar contract invoke --network testnet --id "$QUOTE" \
  --source-account "$ALIAS" --send=yes -- approve \
  --from "$USER" --spender "$ORDERBOOK" \
  --amount "$ALLOWANCE" --expiration_ledger "$EXPIRATION_LEDGER"

stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=no -- new_sell_order \
  --user "$USER" \
  --order_data "$SELL_ORDER_DATA" \
  --cross_identifier "$CROSS_IDENTIFIER" \
  --reporting_data "$REPORTING_DATA"

SELL_OUTPUT="$(stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=yes -- new_sell_order \
  --user "$USER" \
  --order_data "$SELL_ORDER_DATA" \
  --cross_identifier "$CROSS_IDENTIFIER" \
  --reporting_data "$REPORTING_DATA" 2>&1)"
printf '%s\n' "$SELL_OUTPUT"


# The Stellar CLI prints the OrderReceived event topic vector inline:

#   Event: [{"symbol":"OrderReceived"},{"address":"<client>"},{"u64":"<order_id>"}] = {...}

# Extract order_id from the third topic, which is the first {"u64":"..."} that follows

# the OrderReceived symbol and the client address.
ORDER_ID="$(SELL_OUTPUT="$SELL_OUTPUT" python3 - <<'PY'
import os, re
text = os.environ["SELL_OUTPUT"]
m = re.search(
    r'\{"symbol":"OrderReceived"\}\s*,\s*\{"address":"[^"]+"\}\s*,\s*\{"u64":"([0-9]+)"\}',
    text,
)
if not m:
    raise SystemExit("Could not parse order id from OrderReceived topic vector")
print(m.group(1))
PY
)"
echo "order_id=$ORDER_ID"

stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=yes -- cancel_sell_order \
  --user "$USER" --order_id "$ORDER_ID"

stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=no -- count_buy_orders
stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=no -- count_sell_orders
stellar contract invoke --network testnet --id "$ORDERBOOK" \
  --source-account "$ALIAS" --send=no -- best_fifty_offers

8. Chain differences

Topic	Polygon Amoy	Stellar Testnet
Signing identity	EVM transaction sender is the trading wallet.	The Soroban call carries an explicit user address; the transaction is signed by the source account.
Order entry	newBuyOrder(bytes,bytes,bytes) / newSellOrder(bytes,bytes,bytes).	new_buy_order(user, order_data, cross_identifier, reporting_data) / new_sell_order(...).
Order data encoding	abi.encode(uint64 quantity, uint64 price).	32-byte padded words inside Soroban Bytes.
Order options	Two-field encoding only on the POC orderbook. Extended layouts revert.	Standard, IOC, BOC, FOK, GFD, GTD via the explicit field layout.
Token authorization	Restricted token receivers must be 21X beneficiaries.	Trustline + token authorization; participant authorization on the orderbook.
Allowance	ERC-20 allowance, no expiration.	Soroban allowance with expiration_ledger.
Allowance behaviour	Consumed when a resting order is posted (orderbook calls transferFrom); cancellation returns the token balance but does not restore the consumed allowance.	Pair-dependent. On the active POC pair the orderbook does not pre-fund and the allowance is unchanged. Read get_config to confirm pre-funding behaviour and refresh allowances before expiry or when consumed.
Phase return type	uint8 (open = 1).	String enum (open = "OpenForTrading").
Order id surface	Indexed event topic (topics[2]) on every lifecycle event.	Topic vector (topic[2]) for OrderReceived, CancelOrder, OrderRejected; data body for NewBuyOrder / NewSellOrder.
Native fees	POL / MATIC.	XLM.
Simulation	eth_call / ethers staticCall.	Stellar CLI / SDK with --send=no.

9. Troubleshooting

9.1 Permissions and authorization

Error	Chain	Cause	Action
OrderBook_NotAllowedToBuy / OrderBook_NotAllowedToSell	Both	Wallet is not whitelisted for the side being placed.	Complete 21X whitelist / client setup.
Receiver must be a beneficiary	Polygon	Wallet cannot receive a restricted token.	Enable beneficiary status for the wallet and token.
ClientNotFound (#6)	Stellar	Account not registered with the orderbook's client registry.	Confirm onboarding with 21X; confirm the correct user address and orderbook id.
NotAllowedToBuy (#4) / NotAllowedToSell (#5) / NotAllowedToCancel (#7)	Stellar	Participant exists but lacks the relevant permission.	Confirm client permissions with 21X.
Unauthorized (#4001)	Stellar	Method requires an elevated role (for example, detailed order inspection).	Use emitted events and authenticated REST history endpoints.

9.2 Encoding and input validation

Error	Chain	Cause	Action
OrderBook_InvalidInputOrderData	Polygon	Wrong EVM orderData layout.	Use abi.encode(["uint64","uint64"], [quantityRaw, priceRaw]).
InvalidInputOrderData (#2004)	Stellar	Compact bytes encoding, or a cross_identifier that is not 4 bytes.	Use 32-byte words for order_data; use exactly 4 bytes for cross_identifier.
CLI rejects order_data as not parseable to Bytes	Stellar	Odd number of hex characters or wrong length.	Generate the value from decimal inputs; validate length is 128 or 256 hex characters.
order_id reads as 0 or undefined after submit	Polygon	ABI declared without indexed on client / orderId; the value lives in topics[2], not the data body.	Use the indexed ABI definitions in §6.8 verbatim.
Order id parser returns nothing	Stellar	Parser searched the event data body for an order_id JSON field; the value is in topic[2].	Read the third element of the topic vector — see §7.10.

9.3 Balances and allowances

Error	Chain	Cause	Action
ERC20InsufficientAllowance	Polygon	Missing or consumed ERC-20 approval.	Approve the orderbook again or maintain a larger standing approval.
Allowance unexpectedly insufficient after cancel	Polygon	Allowance is consumed on order placement; cancellation does not restore it.	Re-approve before placing another order.
Buy order locks more quote than notional	Polygon	Commission / pre-fund margin requirement.	Approve enough quote balance for notional plus commission.
Error(Contract, #10) — resulting balance not in allowed range	Stellar	Insufficient quote balance for value plus commission.	Top up the quote balance; an allowance does not replace a balance.
Error(Contract, #13) — trustline entry is missing	Stellar	Token trustline missing.	Create the trustline and retry.

9.4 Pre-trade controls and matching rejections

Stellar pre-trade and volatility-management codes:

PreTradeControlPriceAboveMaxRange         = 1018
PreTradeControlPriceBelowMinRange         = 1019
PreTradeControlOrderValueAboveMaxRange    = 1020
PreTradeControlOrderVolumeAboveMaxRange   = 1021
PreTradeControlOrderValueBelowMinRange    = 1022
PreTradeControlOrderVolumeBelowMinRange   = 1023
VolatilityManagementPriceOutOfMaximumStaticRange  = 1025
VolatilityManagementPriceOutOfMinimumStaticRange  = 1026
VolatilityManagementPriceOutOfMaximumDynamicRange = 1027
VolatilityManagementPriceOutOfMinimumDynamicRange = 1028

Use REST pair data and get_config to inspect thresholds, limits, static reference price, liquidity band, and the price collar factor before submitting. An OrderRejected event indicates that the transaction itself succeeded but the order was rejected by matching rules, controls, or execution-condition behaviour; check reason, quantity_not_executed, side, price, and pre-submission book state.

Boundary behaviour. Orders at the exact minimumOrderValue may be rejected by pre-trade controls (for example, PreTradeControlOrderValueBelowMinRange). Use values comfortably above the minimum unless intentionally testing boundary rejection.

9.5 REST endpoint authentication

Authenticated wallet, order, and trade history endpoints require a bearer token. Calls without authentication return HTTP 401. Use the public market-data endpoints for unauthenticated discovery, or obtain API credentials from 21X for participant-scoped history.