# SimpleDEX — Swap & liquidity (v1.11 · 2026-05-12)

> Part of the SimpleDEX agent guide. Index: https://simpledex.fun/llms.txt
> Full single file: https://simpledex.fun/llms-full.txt

## 3 — Swap tokens (DEX)

Swaps use a two-step deposit-then-execute pattern, but **memo-based swaps
do both in a single transfer**.

### 3.1 Memo-based swap (recommended)

Transfer the input token to the DEX contract with memo
`swap:<poolId>:<minAmountOut>:<isTokenAIn>`.

```bash
# Swap 100 XPR for tokens in pool 1, require at least 950000 raw output
proton action eosio.token transfer \
  '["youraccount","simpledex","100.0000 XPR","swap:1:950000:true"]' \
  youraccount@active
```

Memo format: `swap:POOL_ID:MIN_OUT:IS_TOKEN_A_IN`
- `POOL_ID` — integer pool ID
- `MIN_OUT` — minimum output amount (raw u64), for slippage protection
- `IS_TOKEN_A_IN` — `true` if you're sending tokenA, `false` if tokenB

### 3.2 Calculate expected output

Use the constant product formula:

```
amountOut = (reserveOut * amountIn * (10000 - feeRate))
          / (reserveIn * 10000 + amountIn * (10000 - feeRate))
```

Example with pool feeRate=30 (0.3%):
- Sending 100.0000 XPR (raw: 1000000) into pool with reserveA=10000000, reserveB=5000000
- amountOut = (5000000 * 1000000 * 9970) / (10000000 * 10000 + 1000000 * 9970)
- amountOut = 453636

Set `minAmountOut` to `amountOut * (1 - slippage)`. A 1% slippage tolerance
means `minAmountOut = floor(453636 * 0.99) = 449099`.

### 3.3 Multi-hop swap

For tokens without a direct pool, route through intermediate pools:

```bash
# Deposit input token first
proton action eosio.token transfer \
  '["youraccount","simpledex","100.0000 XPR","deposit:1"]' \
  youraccount@active

# Execute multi-hop: pool 1 -> pool 3, minimum final output 9000
proton action simpledex multihopswap \
  '["youraccount",[1,3],9000,[true,true]]' \
  youraccount@active
```

Maximum 4 pools per multi-hop. Each `isTokenAIns` entry indicates
whether the input to that hop is tokenA of that pool.

### 3.4 Limits

- **Max swap size**: 50% of the input reserve per transaction
- **Cooldown**: 1 second between `swap`/`multihopswap` actions (anti-MEV)
- **Fee**: 0.3% default (configurable per pool), built into the constant product formula
- **Fee distribution**: The 0.3% fee stays in pool reserves (growing LP token value). Then 50% of the fee is deducted from the swap output and sent to treasury (`dex.protonnz`). The remaining 50% stays in reserves as LP earnings.

**Note**: Memo-based swaps via `onTransfer` are intentionally NOT
rate-limited, allowing bots to chain multiple memo swaps in one tx.

---

## 4 — Liquidity (DEX)

### 4.1 Add liquidity

Deposit both tokens, then execute:

```bash
# Deposit token A
proton action eosio.token transfer \
  '["youraccount","simpledex","100.0000 XPR","deposit:1"]' \
  youraccount@active

# Deposit token B
proton action simpletoken transfer \
  '["youraccount","simpledex","50000.0000 COOK","deposit:1"]' \
  youraccount@active

# Execute — minLpTokens for slippage protection
proton action simpledex execaddliq \
  '["youraccount",1,0]' \
  youraccount@active
```

First deposit to a pool locks 1000 LP tokens permanently (minimum liquidity).

**Critical: Always bundle all 3 actions in a single atomic transaction.**
If you send deposit transfers without `execaddliq`, or if `execaddliq` fails,
stale deposits pile up. Maximum 10 pending deposits per account — after that,
all liquidity operations are blocked until deposits are cleaned or withdrawn.

### 4.1.1 Clean stale deposits

Deposits expire after 24 hours. Anyone can clean expired deposits (no auth required):

```bash
# Clean up to 10 expired deposits for an account
proton action simpledex cleandeposit \
  '["targetaccount",10]' \
  anyaccount@active
```

To withdraw non-expired deposits manually (requires account auth):

```bash
# Withdraw a specific deposit by ID
proton action simpledex withdrawdep \
  '["youraccount",DEPOSIT_ID]' \
  youraccount@active
```

Check pending deposits:
```bash
proton table simpledex youraccount deposits
```

### 4.2 Remove liquidity

```bash
# Remove all LP tokens, accept any output amounts
proton action simpledex remliquidity \
  '["youraccount",1,500000,0,0]' \
  youraccount@active
```

Parameters: `[account, poolId, lpTokens, minAmountA, minAmountB]`

### 4.3 LP token calculation

```
First add:  lpTokens = sqrt(amountA * amountB) - 1000
Later adds: lpTokens = min(amountA * totalLP / reserveA,
                           amountB * totalLP / reserveB)
Withdrawal: amountA = lpTokens * reserveA / totalLP
            amountB = lpTokens * reserveB / totalLP
```

LP tokens are raw u64 integers (no decimals).

**How LPs earn fees**: The full 0.3% swap fee stays in pool reserves,
growing LP token value over time. The protocol fee (50% of the fee amount)
is an additional deduction from the swap output — LPs keep the full 0.3%.
When you withdraw, you get back more tokens than you deposited. There are
no separate fee claim actions — earnings are realized on remove liquidity.

---