Skip to main content
This page explains the concepts behind liquidity and settlement on XentFi Pro. For the full request/response schema of every endpoint, see the XentFi Pro API Reference.

​
Overview

Matched trades on XentFi Pro don’t settle one-by-one on-chain, and they don’t net arbitrary wallet pairs against each other directly either — every wallet is a real, independent on-chain account, so two different owners’ balances can’t be merged into a single transaction without a shared contract. Instead, settlement routes through each market’s settlement master wallet, in a hub-and-spoke pattern, batched every 2 seconds. This means N trades in a market during one settlement window collapse to at most (number of distinct payer wallets) + 1 on-chain transactions — not N — and a payout is never broadcast against funds that haven’t actually landed yet.

​
Settlement batches

Every settlement batch tracks its legs individually, so a partial failure (e.g. one payer’s IN leg reverts) is visible per-wallet rather than collapsing the whole batch into one opaque status.
Once a batch reaches CONFIRMED, its trades are marked settled and the affected wallets’ cached balances are immediately re-synced against on-chain state.

​
Funding a market’s liquidity

Every market needs a real settlementMasterWalletId — an existing XentFi master wallet — with enough working capital on the market’s settlementBlockchainId to cover Phase 2 payouts between settlement cycles.
This is real custody. Monitor a market’s settlement master wallet balance the same way you’d monitor any other hot wallet — if it can’t cover a settlement cycle’s payouts, that cycle’s OUT legs fail even though the matching trades already executed off-chain.
Because a Market is scoped to a single chain (settlementBlockchainId), plan working capital per chain per market rather than assuming one wallet covers multiple markets across chains.

​
Price oracle & market-order protection

An external reference price feed protects two situations the order book’s own trade history can’t cover on its own:
  • Empty or thin books — before a book has a mid price of its own, a price-band check falls back to the oracle so a brand-new market’s first order can’t set an arbitrary opening price for everyone after it.
  • MARKET orders — before a MARKET order is allowed to walk the book, its expected execution price is checked against the oracle, rejecting execution against a stale or thinly-manipulated book independent of the order book’s own recent trades.
If no oracle is configured for a pair, both checks fail open — price discovery proceeds unconstrained rather than blocking trading on long-tail markets. This is a deliberate default, not a gap: configure an oracle for any market where you want that protection active.

​
Anti-MEV & fair matching

  • Batch auctions (batchAuctionIntervalMs, default 250ms) remove intra-batch latency races — orders within the same window are matched on price-time priority rather than rewarding whoever’s request lands microseconds earlier.
  • Private relay routing is used for settlement transactions where available, reducing exposure to public-mempool front-running on the settlement leg itself.
  • Price bands (maxDeviationFromMidBps) and rate limiting reject spoofing and fat-finger orders before they ever reach the book.

​
Gas & fee volatility

Settlement legs are quoted and submitted using a rolling EMA base-fee estimate per chain, with a volatility-scaled buffer. If live gas exceeds a hard multiple of that baseline, a circuit breaker holds and requeues affected trades rather than dropping them or settling at an unpredictable cost — they settle once conditions normalize.

​
Reconciliation

Off-chain cached balances are reconciled against actual on-chain state in two ways:
  1. Event-driven — immediately after every confirmed settlement batch.
  2. Real-time on external activity — a deposit or withdrawal that happens outside the order book (e.g. your business moving funds directly) is detected via the platform’s existing webhook pipeline and immediately reconciles that wallet’s balance if it has open orders, unwinding any now-under-collateralized resting orders within seconds.
A downward discrepancy freezes the affected wallet and unwinds excess resting-order reservations, rather than allowing it to trade on a balance that no longer exists.

​
API Reference

Full request/response schemas: XentFi Pro API Reference.

Order Book

Markets, order types, and the order/trade lifecycle.

XentFi Pro Quickstart

Place your first order end to end.

Master Wallets

How settlement master wallets fit into XentFi’s wallet hierarchy.