Skip to main content
When two orders match off-chain, the engine creates a fill and begins the settlement process. Settlement is the on-chain transfer of USDC between the maker’s and taker’s personal smart wallets.

​
Fill Status Lifecycle

matched → settling → settled
                  ↘ retrying → settled
                  ↘ failed
StatusMeaning
matchedOrders matched off-chain. Fill created, awaiting settlement
settlingSettlement transaction submitted to Solana, waiting for confirmation
settledTransaction confirmed. USDC transferred between personal smart wallets
retryingSettlement failed temporarily; engine will retry automatically
failedSettlement failed permanently (e.g., insufficient on-chain balance)
failed_insufficient_balanceUser’s smart wallet balance was insufficient at settlement time

​
How Settlement Works

1

Match

The matching engine pairs a maker order with a taker order. A fill record is created with status: matched.
2

Batch

The settlement worker groups pending fills into batches for efficient on-chain submission. Multiple fills can settle in a single Solana transaction.
3

Submit

The engine builds a Solana transaction containing the fill details and both users’ Ed25519 signatures (from the original order messages). The fill status moves to settling.
4

Verify On-Chain

The on-chain program verifies:
  • Both order signatures are valid
  • Prices and quantities match
  • Both users have sufficient balances in their personal smart wallets
  • The market is still active
5

Settle (Smart Wallet Accounting)

On success, the program atomically transfers USDC between the maker’s and taker’s personal smart wallets, and outcome tokens are minted/transferred as needed. The fill status moves to settled and the settleTx field contains the Solana transaction signature.

​
Fill Types

The engine supports three matching mechanisms, each with a different settlement flow:

​
Direct Fill

A buyer and seller of the same outcome are matched. Settlement transfers USDC from the buyer’s smart wallet to the seller’s smart wallet, while outcome tokens transfer from seller to buyer.
SideSmart Wallet DebitReceives
Buyer (YES)USDC (from smart wallet)YES tokens
Seller (YES)YES tokensUSDC (to smart wallet)

​
Complementary Fill

A buyer of YES and a buyer of NO are matched when yesPriceBps + noPriceBps >= 10000. USDC is transferred from both buyers’ smart wallets into the market vault, and the vault mints one YES token and one NO token (always backed 1:1).
SideSmart Wallet DebitReceives
YES buyerUSDC (yesPrice, from smart wallet)YES tokens
NO buyerUSDC (noPrice, from smart wallet)NO tokens

​
Sell Complementary Fill

A seller of YES and a seller of NO are matched. Both outcome tokens are burned, and the vault returns the backing USDC directly to both sellers’ personal smart wallets.
SideSendsReceives (Smart Wallet Credit)
YES sellerYES tokensUSDC (split, to smart wallet)
NO sellerNO tokensUSDC (split, to smart wallet)

​
WebSocket Events

During the settlement lifecycle, relevant events are emitted on both the market channel and user channel:
EventChannelWhen
trade (status: matched)MarketFill is created
trade (status: settled)MarketFill is settled on-chain (includes settleTx)
fill:matchedUserYour fill is created
fill:settlingUserYour fill is being settled
fill:settledUserYour fill is settled (includes settleTx)
fill:failedUserYour fill failed settlement
balance:updateUserYour balances changed

​
Viewing Settlement Transactions

After a fill is settled, the settleTx field contains the Solana transaction signature. You can view it on:
  • Solscan: https://solscan.io/tx/{settleTx}
  • Solana Explorer: https://explorer.solana.com/tx/{settleTx}

​
Timing

Settlement typically occurs within a few seconds of matching. The engine processes fills in batches and submits transactions as quickly as Solana block times allow. If settlement fails due to a transient issue (RPC errors, congestion), the engine automatically retries. The fill status will show retrying during this period.
While a fill is in settling or retrying status, the associated orders show settling status and cannot be cancelled. This lock is released once settlement succeeds or permanently fails.