Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

  7. Verify the discovered orderBookVersion and load the matching canonical contract ABI. This guide supports EVM orderbook 1.2.0 and Stellar orderbook 1.2.0; fail closed on an unsupported version.

  8. Record the exact versions of every tool and SDK your integration is validated against (Stellar CLI, ethers.js, web3 library, language runtime) and pin them in your build. CLI output formats and SDK APIs change between versions; an integration validated against one version is not automatically valid against another. The JavaScript examples in this guide use the ethers v6 API (ethers.JsonRpcProvider, AbiCoder.defaultAbiCoder()); they do not run unmodified on ethers v5.

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:

3.1 REST environment

3.2 Polygon Amoy environment

3.3 Stellar Testnet environment

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.

Units in REST responses. All prices, order values, and reference prices in REST responses are human-readable decimal strings - for example "100.00", "10000000.00" - not scaled integers. Scale factors themselves are returned as strings (for example "1000"). Scaled integers appear only in on-chain order encoding (§5.5) and in on-chain events. Do not apply the internal scales to REST values.

4.1 Discovering pairs

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

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.

baseTokenData.isin / baseTokenData.dti

Instrument identifiers (ISIN, Digital Token Identifier) of the base asset.

quoteTokenSymbol

Quote asset display symbol.

quoteTokenEquivalentCurrency

Fiat currency the quote token represents, for example USD.

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 / marketMakerCommission

Commission parameters. Read per pair - rates differ between pairs and between maker and taker (see §6.5).

tickSizeMode

Tick-size regime applied by pre-trade controls, for example REGULATORY or GRANULAR. See §5.5.

maximumMatches

Maximum number of matches a single incoming order may generate (see MaxMatches rejection, §7.10).

liquidityBand

Liquidity band used by tick-size and volatility controls.

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.

statusChangeReason

Reason for the last trading-status change, for example START_OF_TRADING_DAY.

orderBookVersion

Version of the deployed orderbook contract.

Trading statuses

tradingStatus follows the venue's trading phase lifecycle. The full status set:

Lifecycle status
Meaning

Created

Pair and orderbook deployed but inactive; activated manually by the venue.

Out of Trading

Active pair outside trading hours.

Continuous Trading

Market open; the only status in which orders are accepted.

Automatic Trading Halt

Volatility-triggered halt; resumes automatically (see trading hours below).

Manual Trading Halt

Halt initiated via the venue's Service Portal (regulatory, technical, capacity, …).

Disabled

Pair deactivated.

Permanently Deleted

Terminal state; the pair is offboarded.

REST renders statuses in upper snake case such as CONTINUOUS_TRADING; expect the same convention for the others (for example OUT_OF_TRADING). Pairs in Created, Disabled, or Permanently Deleted states are hidden from the venue's trading front end; the REST list contains one entry per active pair. Gate order submission on CONTINUOUS_TRADING exactly and treat every other value as not-open.

statusChangeReason reports why the status last changed, from a fixed list: Start of Trading Day, Manual Market Open, End of Trading Day, Manual Market Close, Regulator/Participant/Venue/Capacity Initiated Halt, Volatility Halt, Technical Halt, Trading Pair Activated/Deactivated/Offboarded, Trading Pair Creation, Automatic Resume. (REST renders these in upper snake case as well - START_OF_TRADING_DAY is confirmed live.)

Trading hours and halts

  • Trading days open at 08:00 CET and close at 17:00 CET, observing German daylight-saving time. Pairs do not open on non-working days (weekends, holidays, and venue-defined dates).

  • At opening time, pairs in Out of Trading or Automatic Trading Halt move to Continuous Trading and the daily halt counter resets. At closing time, pairs move to Out of Trading and the static reference price is set to the last execution price.

  • Automatic (volatility) trading halts resume automatically: roughly 5-6 minutes after the first halt of the day and 15-16 minutes after the second, provided the halt occurred more than 30 minutes before close. The tradingHaltCounter field in tradeinfo counts that day's automatic halts.

  • About 5 minutes after closing time, expired orders are cleared - see §5.4 for how this surfaces on chain.

4.3 Selecting the right pair

There are two ways to resolve a pair, depending on what you already know.

If the trading pair id is known, call the single-resource endpoint directly. There is no need to list every pair and filter client-side just to find an id you already have:

If you are discovering by attributes, list the pairs and filter by blockChain, baseTokenData.symbol, and quoteTokenSymbol - but do not filter by id (you do not have one yet):

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). When discovering by attributes, match all three of blockChain, baseTokenData.symbol, and quoteTokenSymbol. Do not rely on a partial symbol match alone.

Read this before hardcoding. Symbols are not unique across pairs. Once you have resolved a pair, drive the trading flow by its id, and treat the addresses returned alongside the id as the source of truth for that environment.

4.4 Public market endpoints

Sample responses

orderbook and pricelevels share the same envelope: the pair id plus a buy array and a sell array. An empty book returns empty arrays (this is the normal state of a quiet POC pair, not an error):

The entries inside buy / sell carry price and quantity as human-readable decimal strings, consistent with the units rule at the top of §4. Inspect a live populated response for the exact per-entry field names before writing your parser - place a resting order on your own sandbox pair if every public book is empty.

tradeinfo returns last price, reference price, 24-hour change and volume, and trading status:

All prices here are human decimals ("100.00"), not scaled integers. tradingHaltCounter counts the day's automatic trading halts and resets at market open (see §4.2); statusChangeReason follows the enum in §4.2.

4.5 Pagination and rate limits

The collection response carries a total_count field, which implies the endpoint is designed to page. As of this writing, however, the POC /tradingpairs endpoint ignores limit and offset query parameters and always returns every active pair in a single page (verified against the live POC: ?limit=1 still returns all items). The limit parameter is honoured on the orderbook and pricelevels endpoints, where it bounds the number of levels returned per side.

Code defensively against this changing:

  • After fetching /tradingpairs, compare .items | length against .total_count. If they differ, the endpoint has started paging - implement the paging parameters before trusting the list to be complete.

  • Do not build logic that depends on receiving all pairs in one response.

Rate limits for the POC REST API are not published. Apply standard client-side discipline: cache pair metadata rather than re-fetching it on every order, throttle polling loops, and back off exponentially on HTTP 429 or 5xx responses. Confirm production rate limits with 21X before go-live.

4.6 POC pairs

Chain
Pair
Trading pair id
Orderbook

POLYGON_AMOY

USMO / 21XUSDQ

Discover through REST

Discover through REST

STELLAR_TESTNET

XAMA1 / XUSDT

Discover through REST

Discover through REST

These are examples, not stable identifiers. Trading pair ids, orderbook addresses, and token contract addresses can change at any time. Deploying or restoring an orderbook can produce a new trading pair id and new contract addresses; token contract addresses change less often, but can also change. Always discover the active values through the REST API for the target environment immediately before trading, and never hardcode the values above into a production system.

4.7 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. On-chain events emitted by the orderbook contract (§6.8 and §7.10) are the primary on-chain observation mechanism for order-state changes, but interpreting them correctly requires the ABI/interface matching the discovered contract version, complete event ingestion, deduplication, and chain-finality handling. Reconcile those events with transaction receipts, balances, and authenticated venue order/trade history when available; do not treat an isolated or unconfirmed event as sufficient evidence of final 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.

Market order execution. Market orders are treated as Immediate or Cancel (IOC) by default: any quantity that cannot be filled immediately is cancelled. If Fill or Kill (FOK) is selected, the market order must execute in full immediately or be rejected.

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.

Default condition for market orders; 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 a Good For Day order.

  • 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).

How expiry is surfaced. A GFD or GTD order that reaches its expiry is removed by the venue, not by the participant. Expired orders are cleared by an off-chain venue process about 5 minutes after the 17:00 CET close on trading days (§4.2). On chain this appears as a contract-initiated cancellation: a CancelOrder event with cancellationType = 2 (ByContract), returning any pre-funded tokens per the pair configuration. The same ByContract cancellation type is used when a non-pre-funded order fails its balance/allowance check at matching time (§8.1). Reconciliation logic must therefore treat CancelOrder events it did not initiate as a normal terminal state, not as an anomaly - and must not assume every cancellation maps to one of its own cancel*Order transactions.

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:

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

Exactness, rounding, and tick sizes

The scaling formulas above only produce valid encodings when the product is an exact integer. A price of 1.234 against a quote internal scale of 100 yields 123.4, which cannot be encoded. Client-side validation must reject such inputs rather than silently round or truncate them: a silently rounded price is a different order from the one the user asked for, and a truncated quantity changes the order value checked by pre-trade controls.

The internal scale defines the finest representable increment, but the venue may enforce a coarser tick size on top of it: each pair carries a tickSizeMode (REGULATORY or GRANULAR in the POC) and a liquidityBand, which together determine the price increments pre-trade controls accept. An exactly-scaled price can therefore still be rejected for being off-tick. Request the tick-size table for your pairs from 21X, validate against it client-side, and treat a pre-trade price rejection (§9.4) as the venue-side enforcement of the same rule.

Internal vs native scales

A pair carries two scale systems and they are not interchangeable:

  • Internal scales (baseTokenInternalScale, quoteTokenInternalScale) encode quantityRaw and priceRaw inside orderData. They appear in orderbook events.

  • Native scales (baseTokenNativeScale, quoteTokenNativeScale) denominate actual token balances, transfers, approvals, and Transfer events.

On some pairs they coincide (XAMA1/XUSDT: both 10,000,000). On others they do not - on USMO/21XUSDQ the quote internal scale is 100 but the quote native scale is 1,000,000, a factor of 10⁴ apart. A priceRaw of 10000 therefore has no direct relationship to the 100,000,000 raw units that move when the trade settles. Use internal scales only for order encoding, native scales for everything that touches balances - including the approval amounts computed in §6.5.

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.

Matching follows price-time priority: buys are considered from highest price to lowest, sells from lowest price to highest, and orders at the same price are processed FIFO. Market orders match immediately and never become resting orders; any unmatched remainder is rejected.

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
Required value

Trading pair id

Read id from REST

Blockchain

POLYGON_AMOY

Base / quote symbols

USMO / 21XUSDQ

Orderbook

Read smartContractOrderBook from REST

Base / quote tokens

Read smartContractBase / smartContractQuote from REST

Internal and native scales

Read all four scale fields from REST

Limits, controls, and commissions

Read the active pair values from REST and getConfig()

Orderbook version

1.2.0

Discover immediately before trading. The EVM v1.2 orderbook is non-upgradeable after initialization. Functional changes require a new deployment and controlled migration, which changes the orderbook address and normally the trading pair id. Treat REST discovery as the source of truth and reject an EVM pair whose orderBookVersion is not the version your integration supports.

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.

The read API also exposes bestBidOffer, bestFiftyOffers, the static reference price, and the current pre-trade and volatility-management configuration. Use the canonical compiled v1.2 ABI for their exact return structures rather than maintaining handwritten fragments. Treat detailed per-order inspection as a privileged operation: participant reconciliation should use lifecycle events and authenticated history endpoints rather than depend on getOrderDetails access.

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.

Other phase values. The orderbook contract has four phases, which map onto the venue trading statuses (§4.2): Open for Trading (= Continuous Trading), Closed for Trading (= Out of Trading and the inactive statuses), Manual Halt, and Automatic Halt. 1 (Open for Trading) is the only numeric value documented for the POC; gate on phase === 1 exactly and treat any other value as not-open rather than guessing its numeric meaning.

6.4 Order encoding

The EVM v1.2 orderbook accepts between two and six standard ABI slots. Optional fields must be appended in order; they cannot be skipped.

Position
Field
ABI type
Required

1

quantity

uint64

Yes

2

price

uint64

Yes

3

orderType

uint8

No

4

executionCondition

uint8

No

5

validityConstraints

uint8

No

6

lifetime

uint8

No

Accepted encoded lengths are exactly 64, 96, 128, 160, or 192 bytes. Use abi.encode, not solidityPacked or manually concatenated compact integers.

Defaulting depends on the number of supplied slots:

Slots
Behaviour

2

Limit, Standard, GFD, lifetime 0

3

Parse orderType; default to IOC for Market and Standard for Limit

4

Parse and validate the execution condition

5

Parse the validity constraint

6

Parse lifetime; require Limit + GTD

Client-side validation must enforce these contract rules:

  • quantity must be greater than zero.

  • A Limit order must have price > 0; a Market order may use price = 0.

  • Market orders permit only IOC or FOK and cannot be GTD.

  • A supplied lifetime requires a Limit + GTD order and must be between 0 and 90 days.

Examples:

crossIdentifier is a separate raw bytes argument. It must be either empty (0x, interpreted as zero) or exactly four big-endian bytes. Do not use abi.encode(["uint32"], [0]), which produces a 32-byte value.

crossIdentifier is an optional client correlation field, not an exchange-side sequence number. Use a non-zero value only when your integration has a defined reconciliation scheme. reportingData is also a separate opaque bytes argument and is emitted with lifecycle events; use only the participant-specific reporting format agreed with 21X. Do not carry forward an encoding convention from an older SDK without validating it against the current SDK and deployed v1.2 ABI.

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.

Computing the required amounts

The sell side is simple: the orderbook pulls the scaled base quantity in native units.

The buy side must cover the order notional plus commission, both in native quote units - not in the internal units used by priceRaw:

In the POC configuration the commission values returned by REST (makerCommission, takerCommission) are expressed in basis points (1 bp = 0.01%), so commissionRate = commission / 10000 and the POC value 10 means 0.10%. Confirm the unit and the venue's rounding rules with 21X before go-live - this guide derives the unit from the POC configuration, and a wrong unit makes every approval wrong.

Worked example - buy 1.000 USMO @ 100.00 21XUSDQ (quote native scale 1,000,000, taker commission 10 bp):

Two practical rules:

  • Do not derive the approval from priceRaw. priceRaw uses the quote internal scale (100 on this pair); transfers use the native scale (1,000,000). On USMO/21XUSDQ they differ by 10⁴ - see §5.5. Compute the approval from human values and the native scale.

  • Size for the worst-case commission. Which rate applies depends on how the order executes: the portion that matches immediately pays the taker rate (the buyer's wallet is debited rounded(P × Q) × (1 + takerCommission)), while a remainder that rests on the book is pre-funded at the maker rate (limitPrice × Q × (1 + makerCommission)). A single order can do both, and rates can differ on the same pair (a live POC pair charges maker 10 / taker 30) - so use max(makerCommission, takerCommission) when sizing approvals. Wallets designated as market makers pay marketMakerCommission in both roles instead.

Two settlement details worth knowing (they explain "unexpected" transfer amounts during reconciliation): a pre-funded resting buy that executes below its limit is reimbursed the difference (limit − executionPrice) × Q × (1 + makerCommission) from the orderbook, and the venue generally aims to round settlement amounts in the participant's favour. That outcome cannot be guaranteed for every participant in every settlement, so integrations must reconcile the actual token transfers rather than infer them from an assumed rounding direction.

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.

Do not hardcode the commission. The commission applied at settlement comes from the trading pair / orderbook configuration (makerCommission / takerCommission, exposed via REST and getConfig), not from a fixed constant. Any numeric commission shown in this guide is an example only. Read the live rate for the pair when computing the amount to approve - a stale or wrong rate leaves the approval too low (causing ERC20InsufficientAllowance at settlement) or unnecessarily high.

6.6 Submitting orders

Always dry-run with staticCall before broadcasting:

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.

Nonce management for sequential orders. EVM transactions from one wallet execute in strict nonce order. The simple pattern above (await tx.wait() between submissions) is safe but serial. If you submit several orders from the same wallet without waiting, assign nonces explicitly (provider.getTransactionCount(address, "pending") as the starting point) and remember that one stuck underpriced transaction blocks every transaction behind it - replacing it requires re-sending the same nonce with a higher gas price. For higher throughput, prefer separate wallets per strategy over deep nonce pipelines.

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.

Only the owning wallet can cancel its own order, and only while the order is still resting on the book. If the order has already been partially matched, cancellation removes only its unfilled resting remainder; quantities already executed are unaffected. Participant cancellation is permitted while the orderbook is open or halted, but not after it has moved to a closed phase. A wallet must also retain its canCancel whitelist permission.

6.8 Events

Event declarations, indexed parameters, and data layouts are part of the EVM v1.2 ABI. Load the canonical compiled ABI supplied by 21X and use its Interface.parseLog result; do not reconstruct event declarations from an older orderbook or assume an order id occupies a fixed topic position without checking that ABI.

The v1.2 topic-0 hashes are:

Event
Topic-0

OrderRejected

0xfcd67a70002bb36185e01e77ee187a2706e52b209633586cf1b69f48f4ac9e76

OrderReceived

0xef879ba5489cfede1af80093037c6f791adf833eeaf2906ba0246c2b8471bdb6

NewBuyOrder

0x8b5f9c7ac27d14b4e56f3c87b39a77847c558bc660e652707b3d0b23596014ac

NewSellOrder

0x76637075c686328c46606fceeeb7b12e992fcaef62b8ffc59a52f9a66a387bc1

NewBuyInitiatedTrade

0xc229a3724c975962a62cc8314ab9661c634d2470934872a0ccaa326db36d245a

NewSellInitiatedTrade

0x129eff071abb78edc82828874c6f83f62039874da53a1db79f26d99f796d8d8a

CancelOrder

0x6a8723de0691c41ddcbfef9ff9b48fdea2bf4203c1cc65d84a0a7ef89563ccae

Use these hashes for coarse log filtering and the canonical ABI for decoding. Keeping the ABI artifact with the integration source ensures that event declarations and topics advance together.

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).

  • OrderRejected is emitted when submission processing succeeds on chain but matching rules, market controls, or the requested execution condition reject the order or its remainder. Decode the rejection reason and unexecuted quantity from the v1.2 ABI.

  • NewBuyInitiatedTrade / NewSellInitiatedTrade is emitted when an incoming order matches resting liquidity, for the matched quantity. A fully-matched incoming order emits OrderReceived, the trade-initiated event, and the base/quote token Transfer and commission events, but no NewBuyOrder / NewSellOrder - nothing rests on the book.

  • NewBuyOrder / NewSellOrder is emitted when the (remaining) order rests on the book. A partial match emits the trade-initiated event for the matched quantity and NewBuyOrder / NewSellOrder for the residual that rests.

  • 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.

Execution price vs limit price. The matching engine uses single-price execution: however many resting orders an incoming order matches, the entire execution happens at one price. That price is the last execution price, clamped into the range the participating orders' limits allow - for an incoming buy, between the highest collected sell limit (lower bound) and the incoming buy's own limit (upper bound); mirrored for an incoming sell. The venue picks the price that moves the market as little as possible, so the fill price is frequently neither side's limit price (an incoming buy at 101 against a resting sell at 99 executes at the last execution price if it lies between 99 and 101). Never assume your limit price is the fill price. Reconcile actual execution economics against the token Transfer amounts in the same transaction: the venue computes the rounded order value rounded(P × Q) plus commission and generally aims to round in the participant's favour, but that direction is not guaranteed for every participant in every settlement.

Monitoring events in production

The examples in this guide read events from the transaction receipt of the participant's own submission. That covers self-initiated actions only. Resting orders also change state through other parties' transactions - a fill arrives in the counterparty's transaction, an expiry in a venue transaction - so a production integration must watch the orderbook contract itself:

  • Polling: eth_getLogs over bounded block ranges with address = orderbook and the v1.2 event topic-0 values above. Decode with the canonical ABI, then filter for the participant address and order ids. Add an indexed participant topic filter only if the canonical ABI confirms its position. Persist the last processed block number and resume from it.

  • Streaming: a WebSocket subscription (contract.on(...) over a WebSocketProvider) for low latency, always backed by an eth_getLogs catch-up on reconnect - subscriptions drop silently.

  • Reorg safety: Polygon Amoy can reorganise recent blocks. Treat events as tentative until a confirmation depth your risk tolerance accepts, and key your event store by (transactionHash, logIndex) so replayed logs deduplicate.

6.9 Allowance behaviour

EVM v1.2 supports pre-funded and no-prefund configurations. Read getConfig() for the active deployment and treat staticCall as the authoritative preflight check; do not infer funding behavior from the chain.

In pre-funded mode, the orderbook calls transferFrom when an order rests: a sell moves base tokens and a buy moves quote tokens plus the applicable commission. The ERC-20 allowance is consumed. Cancellation returns locked tokens but does not restore that allowance, so re-approve or maintain sufficient standing approval for expected churn.

In no-prefund mode, an order may rest without moving tokens. Balance and allowance must still be available when matching occurs. If they are insufficient, the order may be cancelled by the contract while matching continues with other eligible liquidity. See §8.1.

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

1000000000.0000000

Maker / taker commission

10 / 30

Trading status

CONTINUOUS_TRADING

Orderbook version

1.2.0

These are examples, not stable identifiers. The trading pair id and the orderbook, base, and quote contract addresses above can change at any time - a redeployed orderbook produces a new trading pair id and new contract addresses. Discover the active values through the REST API (§4.3) immediately before trading; do not hardcode them.

7.2 Stellar CLI setup

Install the Stellar CLI and confirm the version:

Pin the CLI version. Record the exact CLI version your integration is validated against and pin it in your tooling. The CLI's human-readable output (ledger headers, event rendering, simulation summaries) is not a stable interface and changes between releases - anything that parses CLI output (§7.4, §7.10) is sensitive to upgrades. Re-validate output parsing whenever you bump the CLI.

Configure the testnet network:

Import or generate a local signing identity:

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:

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:

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:

The awk '/Sequence:/' extraction above parses the CLI's human-readable output, which is not a stable interface (see §7.2). If your CLI version offers a JSON output mode for ledger queries, prefer it; in SDK-based integrations, read the latest ledger from the Soroban RPC (getLatestLedger) instead of shelling out to the CLI.

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. Whether an order is pre-funded at placement or only at matching is determined by the orderbook's pre-funding configuration (no_prefund_config in get_config), not by the chain. Where the active configuration permits it, a sell order can be accepted without an immediate base-token transfer. Do not rely on any single behaviour globally - always read get_config and treat the simulation result as authoritative for the current orderbook deployment. See §8.1 for the full set of pre-funding options.

7.5 Inspecting the orderbook

Participant-facing orderbook methods:

View / configuration methods:

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. The contract phase model is the same four-state machine as on Polygon (§6.3): Open for Trading, Closed for Trading, Manual Halt, Automatic Halt. "OpenForTrading" is the only string rendering confirmed for the POC; treat any other value as not-open.

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

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

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

The contract accepts payloads containing two through six complete 32-byte words; omitted trailing fields take the defaults above. If a sixth lifetime word is present, validityConstraints must be 1 (GTD). Do not explicitly encode a sixth lifetime word for GFD, even when the value is zero.

Python helper

This helper intentionally emits four words for a non-GTD order and six for GTD. The contract also accepts the shorter defaulted forms described above. scale_decimal rejects values that do not scale to an exact integer (§5.5).

Validating order_data

Validate the encoded payload before invoking the orderbook. Valid payloads contain two through six complete 32-byte words: 128, 192, 256, 320, or 384 hex characters. Manually editing hex strings is a frequent source of malformed payloads - generate the value from decimal inputs instead.

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. It may be empty (interpreted as zero) or exactly 4 bytes of big-endian hex; any other length fails with InvalidInputOrderData (#2004).

Default scheme. Use 00000000 when an explicit zero value is preferable. cross_identifier is an optional field used in self-trade scenarios; request additional information from 21X when defining a non-zero scheme.

reporting_data is a raw bytes field for reporting and attribution metadata. As on Polygon (§6.4), the 21X backend interprets and attempts to match the two lowest 32-bit values within it, while all remaining bits are free for participant-defined use and need not be zero - an optional place to carry your own internal reference (for example a correlation id or GUID). Default scheme: use the placeholder value 00 for sandbox integrations; this is accepted by the POC orderbook. The sandbox identity already includes the 00 placeholder, so a working integration can be built before any participant-specific reporting scheme 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:

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

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

Sequence numbers and retries. Each Stellar transaction consumes the source account's sequence number, so transactions from one source account are strictly serialised - submit one at a time and wait for the result before the next, or use distinct source accounts (channel accounts) for parallel submission. If the RPC responds with TRY_AGAIN_LATER or tryAgainLater, the transaction was not accepted: rebuild it against the current sequence number and resubmit with backoff. A transaction also carries an expiry (time bounds / max ledger); once that passes without inclusion, it can never be applied, which makes "expired" a safe signal that the order was not placed.

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.

Use cancel_buy_order for buy-side cancellation. Participant cancellation requires the order owner, can_cancel permission, and an orderbook phase that is open or halted; it is not available after the market moves to a closed phase. Cancelling a non-existent or already-cancelled order id fails with NoSuchOrderId (#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. For the v1.2 interface, treat the topic vector as the canonical field location: 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

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

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.

Execution price vs limit price. The same single-price execution model as on Polygon applies (§6.8): the whole match executes at one price - the last execution price clamped into the range allowed by the participating orders' limits - so the fill price is frequently neither side's limit. Reconcile fills against the token transfer events in the same transaction rather than assuming the incoming limit price.

Monitoring events in production

Parsing the CLI's printed event output is suitable for sandbox experiments only. A production integration should consume events from the Soroban RPC getEvents endpoint instead: filter by the orderbook contract id and, because client is topic[1] on every lifecycle event, by your own address as a topic filter. getEvents is paginated and covers a bounded retention window of recent ledgers - poll it on a schedule well inside that window, persist the last processed ledger/cursor, and resume from it. As on Polygon, fills and venue-initiated cancellations of your resting orders arrive in transactions you did not submit, so receipt-watching alone is not sufficient.

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.

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 with two through six 32-byte slots.

Two through six 32-byte big-endian words inside Soroban Bytes.

Order options

Standard, IOC, BOC, FOK, GFD, GTD via the explicit field layout.

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.

Phase return type

uint8 (open = 1).

String enum (open = "OpenForTrading").

Order id surface

Decode with the canonical EVM v1.2 ABI; do not assume a topic position.

Topic vector (topic[2]) for OrderReceived, CancelOrder, OrderRejected; data body for NewBuyOrder / NewSellOrder.

Transaction ordering

Per-wallet nonces; parallel submission requires explicit nonce management (§6.6).

Per-source-account sequence numbers; parallel submission requires channel accounts (§7.8).

Event monitoring

eth_getLogs / WebSocket subscription using the v1.2 ABI and topics (§6.8).

Soroban RPC getEvents, filter by contract id and client topic (§7.10).

Native fees

POL / MATIC.

XLM.

Simulation

eth_call / ethers staticCall.

Stellar CLI / SDK with --send=no.

8.1 Pre-funding and allowance behaviour

Allowance behaviour is configuration-dependent, not chain-dependent. Whether the orderbook locks/transfers tokens when an order is placed ("pre-funded") or only when it matches ("no-prefund") is a property of the specific orderbook deployment. Stellar can behave exactly like Polygon - and vice versa - depending on how the orderbook was compiled and initialised. Always read getConfig / get_config for the pair you are trading and treat the simulation result as authoritative, rather than assuming a per-chain rule.

Behaviour by mode:

  • Pre-funded. The relevant token is locked or transferred into the orderbook when the order is posted - via transferFrom on Polygon, or via the Soroban allowance on Stellar. A sell-side resting order moves the base token; a buy-side resting order moves the quote token (notional plus commission). The allowance is consumed at placement, and cancellation returns the token balance but does not restore the consumed allowance (re-approve before placing again - see §6.9).

  • No-prefund. No token moves when the order rests; settlement transfers occur directly between the trading wallets at matching time. During matching, the orderbook checks each collected non-pre-funded order's wallet for sufficient balance and allowance - cumulatively, counting all orders collected from the same wallet in that match. An order that fails the check is cancelled on chain with cancellation type ByContract and matching continues with the next eligible order (see §5.6). On Stellar the allowance must remain valid for the order's lifetime - refresh it before its expiration_ledger.

Both EVM v1.2 and Stellar v1.2 support configuration-dependent funding behavior. Confirm the active mode through getConfig / get_config for the discovered orderbook and re-check it after any contract redeployment.

9. Troubleshooting

9.1 Permissions and authorization

EVM v1.2 uses ABI custom errors; the selector is the first four bytes of revert data.

EVM error
Selector
Cause / action

OrderBook_InvalidClient()

0xae3d18fd

Wallet is not a valid registered client. Confirm onboarding and the discovered orderbook address.

OrderBook_NotAllowedToBuy()

0x00c9360e

Client lacks buy permission. Ask 21X to update its whitelist record.

OrderBook_NotAllowedToSell()

0x25b56fb0

Client lacks sell permission. Ask 21X to update its whitelist record.

OrderBook_NotAllowedToCancel()

0x52ad6da4

Client lacks cancel permission. Confirm canCancel before retrying.

OrderBook_ExcludedForAccessManagedRoles()

0xb95f30af

The wallet holds an orderbook admin, operator, or controller role and is barred from participant order entry. Use a participant wallet.

AccessManaged_Unauthorized(address)

0x55b9b114

Caller lacks the privileged authority required by the method. Participant integrations should not call role-gated administration methods.

Stellar uses numeric orderbook contract codes:

Stellar error
Cause / action

NotAllowedToBuy (#4) / NotAllowedToSell (#5)

Registered participant lacks the requested side permission. Confirm client permissions with 21X.

ClientNotFound (#6)

Account is not registered in the orderbook's client registry. Confirm the user address and orderbook id.

NotAllowedToCancel (#7)

Participant lacks can_cancel. Confirm permissions before retrying.

InvalidClient (#9)

Client data is invalid for the requested operation. Reconfirm onboarding and the user address.

ExcludedForAccesssControlRoles (#1015)

Address holds a privileged orderbook role and cannot submit participant orders. Use a participant account. The triple s in Accesss is the contract's canonical error spelling.

Unauthorized (#4001)

Method requires an elevated role. Use participant-facing methods, events, and authenticated history endpoints.

Receiver must be a beneficiary is emitted by a restricted EVM token, not by the orderbook. It means the receiving wallet must be enabled as a beneficiary for that token.

9.2 Encoding and input validation

Chain
Error
Cause / action

EVM

OrderBook_InvalidOrderType(uint8) (0x2c45f09d)

orderType is not Limit (0) or Market (1).

EVM

OrderBook_InvalidInputOrderData() (0xedd3a621)

Unsupported ABI length, missing/interleaved fields, invalid value width, or malformed payload. Encode two through six ordered ABI slots (§6.4).

EVM

OrderBook_InvalidExecutionCondition(uint8) (0xf55b59e0)

Condition is outside 0-3 or incompatible with the order type. Market permits only IOC or FOK.

EVM

OrderBook_InvalidValidityConstraint(uint8) (0xaea3ead0)

Validity is outside GFD (0) / GTD (1), or a Market order attempts GTD.

EVM

OrderBook_InvalidOrderLifetime() (0xa9431627)

Lifetime is above 90 or is supplied for a combination other than Limit + GTD.

Stellar

InvalidOrderType (#2000)

order_type is not 0 or 1.

Stellar

InvalidOrderExecutionCondition (#2001)

Condition is outside 0-3 or incompatible with the order type.

Stellar

InvalidOrderValidityConstraint (#2002)

Validity is outside 0-1 or incompatible with a Market order.

Stellar

InvalidOrderLifetime (#2003)

Lifetime or its field combination is invalid.

Stellar

InvalidInputOrderData (#2004)

Unsupported word count, malformed fields, or cross_identifier is neither empty nor four bytes. Use §7.6-§7.7.

Stellar

InvalidInputValueToBig (#2005)

A decoded value exceeds the target integer width. Reject it before submission.

Stellar

CastOverflowTooLargeValueToCastFromU128ToI128 (#1029)

A value exceeds the signed range used by a control calculation. Reject oversized input before submission.

Stellar CLI

order_data is not parseable as Bytes

Hex is malformed, odd-length, or contains incomplete 32-byte words. Validate 128, 192, 256, 320, or 384 hex characters.

Across both chains, validate before encoding: quantity must be positive; Limit price must be positive; Market price may be zero; Market permits only IOC/FOK and cannot be GTD; a sixth slot/word requires Limit + GTD with lifetime 0-90. crossIdentifier / cross_identifier must be empty or exactly four raw bytes.

9.3 Balances and allowances

Chain
Error / symptom
Cause / action

EVM

OrderBook_NoPrefund_InsufficientAllowance(address,address,uint256) (0x023142cc)

A no-prefund order reached matching without enough allowance. Restore allowance for the required token and account for all concurrently resting orders.

EVM token

ERC20InsufficientAllowance

Token approval is missing, too small, or was consumed by earlier pre-funded orders. Re-approve or maintain a suitably bounded standing approval.

EVM token

ERC20InsufficientBalance

Wallet cannot cover the transfer. Top up the appropriate base or quote token.

EVM

Allowance is lower after cancellation

In pre-funded mode, placement consumed allowance; returning tokens does not restore it. Re-approve before reusing the funds.

Both

Buy order requires more quote than notional

Settlement also charges commission. Size balance and allowance for notional plus the applicable commission (§6.5).

Stellar

InsufficientAllowanceForNoPrefund (#1)

A no-prefund order lacks sufficient live allowance at matching time. Renew the allowance and its expiration ledger.

Stellar token

Error(Contract, #10) observed from the token contract

The resulting balance is outside the token contract's allowed range, commonly because quote balance cannot cover value plus commission. Confirm the failing contract id before diagnosing.

Stellar token

Error(Contract, #13) observed from the token contract

Required trustline is absent. Confirm the failing contract id, create the trustline, then retry.

Soroban numeric error namespaces are contract-specific. Always identify which contract emitted Error(Contract, #N) before mapping the number; token-contract #10 is unrelated to orderbook AlreadyInitialized (#10).

9.4 Pre-trade controls and matching rejections

Control failure
EVM v1.2 custom error / selector
Stellar code

Market not in an allowed phase

OrderBook_ForbiddenDueToMarketStatus(...) / 0x931b0c21

ForbiddenDueToMarketStatus (#1014)

Invalid tick-size price

OrderBook_TickSize_InvalidPrice(uint256,uint256) / 0xed7cd145

TickSizeInvalidPrice (#1016)

Pre-trade controls not configured

OrderBook_PreTradeControlsNotSet() / 0xd1c7b9a7

PreTradeControlsNotSet (#1017)

Price above range

OrderBook_PreTradeControlPriceAboveMaxRange() / 0x2a246225

PreTradeControlPriceAboveMaxRange (#1018)

Price below range

OrderBook_PreTradeControlPriceBelowMinRange() / 0x9e88e9b2

PreTradeControlPriceBelowMinRange (#1019)

Order value above range

OrderBook_PreTradeControlOrderValueAboveMaxRange() / 0xa0fd1bca

PreTradeControlOrderValueAboveMaxRange (#1020)

Order volume above range

OrderBook_PreTradeControlOrderVolumeAboveMaxRange() / 0x2ad371e4

PreTradeControlOrderVolumeAboveMaxRange (#1021)

Order value below range

OrderBook_PreTradeControlOrderValueBelowMinRange() / 0x5ef8d87d

PreTradeControlOrderValueBelowMinRange (#1022)

Order volume below range

OrderBook_PreTradeControlOrderVolumeBelowMinRange() / 0xbd643fd0

PreTradeControlOrderVolumeBelowMinRange (#1023)

Volatility management not configured

OrderBook_VolatilityManagementNotSet() / 0x3da15eed

VolatilityManagementNotSet (#1024)

Above maximum static range

Not listed as a separate v1.2 custom revert; inspect OrderRejected and the canonical ABI

VolatilityManagementPriceOutOfMaximumStaticRange (#1025)

Below minimum static range

Not listed as a separate v1.2 custom revert; inspect OrderRejected and the canonical ABI

VolatilityManagementPriceOutOfMinimumStaticRange (#1026)

Above maximum dynamic range

Not listed as a separate v1.2 custom revert; inspect OrderRejected and the canonical ABI

VolatilityManagementPriceOutOfMaximumDynamicRange (#1027)

Below minimum dynamic range

Not listed as a separate v1.2 custom revert; inspect OrderRejected and the canonical ABI

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.

Configuration-not-set errors indicate a venue deployment/configuration problem, not a participant payload problem. Stop submitting and report the discovered pair id and orderbook address to 21X.

9.5 Cancellation, lookup, and event decoding

Chain
Error / symptom
Cause / action

EVM

OrderBook_NoSuchOrderId(uint64) (0xbbe8af6d)

Order id does not exist on the selected side, or is already terminal. Confirm side, owner, orderbook address, and local state before retrying.

Stellar

OrderNotFound (#2) / NoSuchOrderId (#8)

Order cannot be found for the requested lookup or cancellation. Treat an already-terminal order idempotently.

Both

Cancellation fails during a closed phase

Participant cancellation is allowed while open or halted, not closed. Reconcile venue-initiated terminal events rather than blindly retrying.

EVM

Event does not decode or order id is missing

ABI does not match EVM v1.2. Load the canonical compiled ABI and verify topic-0 against §6.8. Do not assume a fixed indexed-topic position.

Stellar

Order id parser returns nothing

OrderReceived, CancelOrder, and OrderRejected carry it in topic[2]; NewBuyOrder / NewSellOrder carry it in the data body (§7.10).

9.6 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.

Last updated