Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oneswap.cc/llms.txt

Use this file to discover all available pages before exploring further.

​
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

1

Get a Quote

Choose your input token and exact deposit amount. OneSwap calculates the expected output using the constant product formula, then shows the network-fee and pool-fee breakdown applied inside that deposit.
2

Create a Swap Intent

Confirm the swap details and set your slippage tolerance. You receive the pool swap party plus a unique transfer reference.
3

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

Receive Output Tokens

OneSwap detects your deposit, executes the swap, and sends the output tokens back to the same wallet party you sent from. No extra steps required.

​
Pricing

OneSwap uses the constant product formula: 
x · y = k
Where 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 k stays the same (minus fees)
Larger swaps relative to pool size result in more price impact — the difference between the quoted rate and the actual execution rate.

​
Fees

Every swap incurs a 0.3% fee taken from the input amount. This fee is split between liquidity providers (0.225%), the platform (0.075%), and — for SDK swaps — the integrating developer (0.0375% from the platform’s share).
FeeAmountGoes To
LP fee0.225%Liquidity providers
Platform fee0.075%OneSwap (0.0375% platform + 0.0375% developer for SDK swaps)
Network feeVariableOneSwap treasury recovery for Canton execution costs
The network fee is a small Canton execution-cost recovery charge that varies based on transaction size. OneSwap shows it separately but deducts it internally from the exact deposit amount you entered, then applies the 0.3% pool fee to the remainder before AMM pricing. The API exposes this as networkFeeAmount, poolFeeAmount, inputAmountAfterPoolFee, and totalInputAmount, and keeps trafficFeeInInput as a compatibility alias. Internally, the recovered network cost is still recorded as a traffic fee event and later collected from the pool’s swap party to treasury. Example for a 100 CC swap:
  • Swap amount: 100 CC
  • Swap fee at 0.3%: 0.3 CC
  • Amount priced into the pool: 99.7 CC
  • Estimated network fee: shown separately and deducted internally
  • Total deposit: 100 CC
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
For example, with 1% slippage on a swap expecting 100 USDCx output, the swap executes as long as you receive at least 99 USDCx. If the output would be less, you get your input tokens back.

​
Swap Lifecycle

Every swap goes through a status lifecycle: 
pending → matched → deposit_received → forwarded → processing → sending_output → completed
Common terminal failure states:
StatusWhat Happened
expiredNo deposit was received before the current 24-hour intent deadline
cancelledThe intent was cancelled before execution started
slippage_failedPrice moved beyond your tolerance
price_impact_exceededSwap would move the pool price beyond the maximum allowed (currently 15%)
insufficient_amountDeposit was below the minimum needed to cover network cost
insufficient_liquidityPool didn’t have enough reserves
output_failedOutput transfer failed after execution; the input refund succeeded
no_output_holdingsThe swap party had no output holdings available for payout
failedThe swap reached a generic terminal failure state
refund_failedA 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 when available — it strengthens observability and fallback matching, but standard 1-step sender attribution does not depend on it.