> ## 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.
# Swapping Tokens
> How token swaps work on OneSwap — pricing, slippage, fees, and the swap lifecycle.
# 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
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.
Confirm the swap details and set your slippage tolerance. You receive the pool swap party plus a unique transfer reference.
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.
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).
| Fee | Amount | Goes To |
| ------------ | -------- | ------------------------------------------------------------ |
| LP fee | 0.225% | Liquidity providers |
| Platform fee | 0.075% | OneSwap (0.0375% platform + 0.0375% developer for SDK swaps) |
| Network fee | Variable | OneSwap 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:
| 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 network 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 when available** — it strengthens observability and fallback matching, but standard 1-step sender attribution does not depend on it.