How Swapping Works
OneSwap lets you exchange one token for another using automated liquidity pools. No order books, no counterparties — just pool reserves and math.The Swap Flow
Get a Quote
Choose your input token and amount. OneSwap calculates the expected output using the constant product formula, accounting for fees and price impact.
Create a Swap Intent
Confirm the swap details and set your slippage tolerance. You receive the pool swap party plus a unique transfer reference.
Send Your Tokens
Transfer the input tokens to the pool swap party from the same connected wallet party and include the transfer reference in the Canton reason/reference field. You currently have 24 hours to complete the deposit.
Pricing
OneSwap uses the constant product formula:x and y are the reserves of each token in the pool, and k is a constant. When you swap token A for token B:
- You add token A to the pool (increasing
x) - The pool sends you token B (decreasing
y) - The product
kstays the same (minus fees)
Fees
Every swap incurs a 1% fee taken from the input amount. This fee is split between liquidity providers (0.75%), the platform (0.25%), and — for SDK swaps — the integrating developer (0.125% from the platform’s share).| Fee | Amount | Goes To |
|---|---|---|
| LP fee | 0.75% | Liquidity providers |
| Platform fee | 0.25% | OneSwap (0.125% platform + 0.125% developer for SDK swaps) |
| Traffic fee | Variable | OneSwap treasury recovery for Canton execution costs |
traffic fee event, accumulated with platform fees, and later collected from the pool’s swap party to treasury. The quote endpoint shows this as estimatedTrafficCost, trafficFeeInInput, and inputAmountAfterTrafficFee so you know the exact net input upfront. outputAmount is calculated from that net input after traffic recovery.
Displayed reserves and TVL exclude pending platform, developer, and traffic-fee collections so swap pricing and LP values are based on effective pool liquidity rather than treasury-owned balances waiting to be swept.
Slippage Protection
Token prices can change between when you get a quote and when your deposit is detected. Slippage tolerance protects you:- Default: 1%
- Range: 0.1% to 50%
- If the price moves beyond your tolerance, the swap is cancelled and your tokens are refunded
Swap Lifecycle
Every swap goes through a status lifecycle:| Status | What Happened |
|---|---|
expired | No deposit was received before the current 24-hour intent deadline |
cancelled | The intent was cancelled before execution started |
slippage_failed | Price moved beyond your tolerance |
price_impact_exceeded | Swap would move the pool price beyond the maximum allowed (currently 15%) |
insufficient_amount | Deposit was below the minimum needed to cover traffic cost |
insufficient_liquidity | Pool didn’t have enough reserves |
output_failed | Output transfer failed after execution; the input refund succeeded |
no_output_holdings | The swap party had no output holdings available for payout |
failed | The swap reached a generic terminal failure state |
refund_failed | A refund attempt failed and needs manual intervention |
Most validation and pricing failures are refunded automatically. Rare operational states such as
no_output_holdings, failed, or refund_failed require manual investigation by OneSwap.Tips
- Check price impact before large swaps. High impact means you’re moving the price significantly. Swaps exceeding the 15% price impact cap are automatically rejected.
- Use reasonable slippage — 1% works for most swaps. Only increase for volatile markets.
- Check the intent deadline — swap intents currently stay open for 24 hours, and the UI shows the exact
expiresAt. - Use the same connected wallet party — deposits from a different party will not complete the swap.
- Include the transfer reference — the pool party is shared across intents, so the reference is what lets OneSwap match your deposit safely.