Order Book

This page explains the concepts behind XentFi Pro’s order book. For the full request/response schema of every endpoint, see the XentFi Pro API Reference.

Overview

XentFi Pro adds a hybrid off-chain matching / on-chain settlement order book on top of your existing XentFi wallets. Orders are matched off-chain for speed, and matched trades settle on-chain in batches — so you get exchange-grade order types and latency without giving up self-custody of the wallets involved.

Markets

A market is a trading pair (e.g. USDC-USDT) scoped to one blockchain, with its own tick size, lot size, order size limits, fee schedule, and batch-auction cadence.

Field	Description
`symbol`	The market’s trading pair, e.g. `USDC-USDT`.
`baseAssetId` / `quoteAssetId`	The two assets being traded.
`tickSize`	Minimum price increment.
`lotSize`	Minimum quantity increment.
`minOrderSize` / `maxOrderSize`	Order size bounds.
`makerFeeBps` / `takerFeeBps`	Fee schedule, in basis points.
`batchAuctionIntervalMs`	How often resting orders are matched (default `250`ms).
`maxDeviationFromMidBps`	Price-band width used to reject fat-finger/spoofing orders.
`status`	`ACTIVE`, `PAUSED`, `HALTED`, or `AUCTION_ONLY` — see Market status below.

Discover available markets with GET /v1/orderbook/markets, and a single market’s live config with GET /v1/orderbook/markets/{marketSymbol}.

Market status

New markets are created in PAUSED status by design — this gives you a chance to verify asset configuration and confirm the settlement wallet is funded before trading opens. A market moves to ACTIVE via PATCH /v1/orderbook/markets/{marketSymbol}.

Status	Meaning
`ACTIVE`	Accepting and matching orders normally.
`PAUSED`	Not yet activated, or paused by an operator (`pauseReason` explains why).
`HALTED`	Trading stopped — typically a circuit breaker (e.g. gas price spike) or an operational incident.
`AUCTION_ONLY`	Only participates in batch auctions, no continuous matching.

Order types

Type	Behavior
`LIMIT`	Rests on the book at your specified `price` until matched or cancelled.
`MARKET`	Executes immediately against the best available price(s); no `price` field. Checked against the reference price oracle (see Liquidity) to avoid walking a thin or stale book.
`POST_ONLY`	Only ever adds liquidity — rejected instead of matching immediately, so it never pays taker fees.
`IOC` (Immediate-Or-Cancel)	Fills whatever is immediately available, cancels the rest.
`FOK` (Fill-Or-Kill)	Fills completely and immediately, or is cancelled entirely — no partial fills.

timeInForce (GTC, IOC, FOK, GTT) is set independently of type and controls how long an order (typically a LIMIT) is allowed to rest before it’s cancelled.

Placing an order

curl -X POST https://api.pro.xentfi.com/v1/orderbook/orders \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "marketSymbol": "USDC-USDT",
    "walletId": "your-wallet-id",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "price": "1.0002",
    "quantity": "500",
    "clientOrderId": "my-app-order-00147"
  }'

clientOrderId is your own idempotency key, unique per organization + app — always set one so a retried request after a timeout can’t place the same order twice.

A 201 response means the order was admitted to the book, not that it filled. Matching happens asynchronously on the market’s batch-auction cadence. Poll GET /v1/orderbook/orders/{orderId} or subscribe to your private realtime channel (see below) to track fills.

Order lifecycle

Only orders in OPEN or PARTIALLY_FILLED status can be cancelled (DELETE /v1/orderbook/orders/{orderId}) — the reserved balance behind the order is released atomically as part of cancellation.

Fees

Every trade charges the maker (the resting order that got matched against) and the taker (the order that triggered the match) separately, per the market’s makerFeeBps / takerFeeBps. Maker fees are typically lower — sometimes zero or rebated — to reward the side providing liquidity. Fees are visible per trade on Trade.makerFee / Trade.takerFee.

Market data

Endpoint	Returns
`GET /v1/orderbook/markets/{marketSymbol}/book`	Current bid/ask depth snapshot, with a `sequence` number for websocket resync.
`GET /v1/orderbook/markets/{marketSymbol}/trades`	Recent trades, most recent first.
`GET /v1/orderbook/markets/{marketSymbol}/ticker`	24h open/high/low/last/volume.
`GET /v1/orderbook/markets/{marketSymbol}/candles`	OHLCV candles at `1m`/`5m`/`15m`/`1h`/`4h`/`1d` intervals.

Realtime updates

Rather than polling, subscribe to your organization’s private order-update channel for pushed fills, cancels, and rejects:

curl -X POST https://api.pro.xentfi.com/v1/orderbook/realtime/auth \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{ "socket_id": "...", "channel_name": "private-orders-your-org-id" }'

Order book depth updates are published per-market and carry a WAL sequence number — if your client detects a gap, resync with GET /v1/orderbook/markets/{marketSymbol}/book rather than assuming continuity.

Your trade history

GET /v1/orderbook/orders/{orderId}/trades — fills for a specific order, whether it was maker or taker.
GET /v1/orderbook/wallets/{walletId}/trades — full trade history for a wallet. Only visible if your organization has itself placed an order with that wallet.

API Reference

Endpoint	Method	Description
`/v1/orderbook/orders`	POST	Place an order
`/v1/orderbook/orders`	GET	List orders
`/v1/orderbook/orders/{orderId}`	GET	Get an order
`/v1/orderbook/orders/{orderId}`	DELETE	Cancel an order
`/v1/orderbook/orders/{orderId}/trades`	GET	Fills for an order
`/v1/orderbook/wallets/{walletId}/trades`	GET	Trade history for a wallet
`/v1/orderbook/markets`	GET / POST	List / create markets
`/v1/orderbook/markets/{marketSymbol}`	GET / PATCH	Get / update a market
`/v1/orderbook/markets/{marketSymbol}/book`	GET	Order book depth
`/v1/orderbook/markets/{marketSymbol}/trades`	GET	Recent trades
`/v1/orderbook/markets/{marketSymbol}/ticker`	GET	24h ticker
`/v1/orderbook/markets/{marketSymbol}/candles`	GET	OHLCV candles
`/v1/orderbook/realtime/auth`	POST	Authorize a private realtime channel

Full request/response schemas: XentFi Pro API Reference.

Liquidity & Settlement

How matched trades settle on-chain and how to keep a market funded.

XentFi Pro Quickstart

Place your first order end to end.

XentFi Pro Authentication

Get an API key with the Trade scope.

Getting Started

Wallet Management

Payment Links & Webhooks

Transfers & Auto Settlement

Security & Compliance

Trading & Liquidity

Overview

Markets

Market status

Order types

Placing an order

Order lifecycle

Fees

Market data

Realtime updates

Your trade history

API Reference

Liquidity & Settlement

XentFi Pro Quickstart

XentFi Pro Authentication

​Overview

​Markets

​Market status

​Order types

​Placing an order

​Order lifecycle

​Fees

​Market data

​Realtime updates

​Your trade history

​API Reference

​Related

Liquidity & Settlement

XentFi Pro Quickstart

XentFi Pro Authentication

Overview

Markets

Market status

Order types

Placing an order

Order lifecycle

Fees

Market data

Realtime updates

Your trade history

API Reference

Related