# SimpleDEX — Reference (params, patterns, errors, about) (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

## 7 — Protocol parameters

| Parameter | Value | Description |
|-----------|-------|-------------|
| DEX swap fee | 0.3% (30 bps) | Built into AMM formula (fee stays in reserves) |
| Protocol fee share | 50% (5000 bps) | Deducted from swap output, sent to treasury |
| LP fee share | 50% | Accrues in pool reserves, increasing LP token value |
| Max swap ratio | 50% | Single swap limited to 50% of reserves |
| Minimum liquidity | 1,000 | Locked on first LP deposit |
| Deposit expiry | 24 hours | Pending deposits expire after this |
| Max multi-hop | 4 pools | Maximum route length |
| Swap cooldown | 1 second | Per-account rate limit |
| Launch buy fee | 1% (100 bps) | Fee on bonding curve buys |
| Launch sell fee | 1% (100 bps) | Fee on bonding curve sells |
| Creator fee share | 50% | Of launch buy/sell fees |
| Graduation threshold | 50,000 XPR | XPR needed to graduate |
| Creation fee | 20,000 XPR (live; on-chain) | To launch a new token. Check `simplelaunch::fees.creationFee` before charging. |
| Token precision | 4 decimals | All amounts are x10000 |

---

## 8 — Useful patterns for agents

### Get token price from the API (easiest)

```bash
curl -s https://indexer.protonnz.com/api/prices \
  | jq '.COOK'
```

### Get platform overview

```bash
curl -s https://indexer.protonnz.com/api/stats
```

### Find the best pool to trade

```bash
curl -s https://indexer.protonnz.com/api/pools \
  | jq '.pools | sort_by(-.tvlUsd) | .[0:5] | .[] | {poolId, pair: (.tokenA.symbol + "/" + .tokenB.symbol), tvlUsd}'
```

### Price check before swap (on-chain)

```bash
# Get pool state
POOL=$(curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simpledex","scope":"simpledex","table":"pools","lower_bound":"1","upper_bound":"1","limit":1}')

# Extract reserves (use jq)
RESERVE_A=$(echo $POOL | jq -r '.rows[0].reserveA')
RESERVE_B=$(echo $POOL | jq -r '.rows[0].reserveB')
FEE=$(echo $POOL | jq -r '.rows[0].feeRate')

# Spot price: tokenB per tokenA
echo "scale=8; $RESERVE_B / $RESERVE_A" | bc
```

### Check if a token is graduated

```bash
CURVE=$(curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simplelaunch","scope":"simplelaunch","table":"curves","lower_bound":"1","upper_bound":"1","limit":1}')

GRADUATED=$(echo $CURVE | jq -r '.rows[0].graduated')
POOL_ID=$(echo $CURVE | jq -r '.rows[0].dexPoolId')

if [ "$GRADUATED" = "1" ]; then
  echo "Token graduated — trade on DEX pool $POOL_ID"
else
  REAL_XPR=$(echo $CURVE | jq -r '.rows[0].realXpr')
  echo "Still on curve — $REAL_XPR / 500000000 XPR collected"
fi
```

### Monitor graduation progress

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simplelaunch","scope":"simplelaunch","table":"curves","limit":100}' \
  | jq '.rows[] | select(.graduated == 0) | {id, name: .name, progress: ((.realXpr / 5000000) | tostring + "%")}'
```

### Get recent graduations from the API

```bash
curl -s https://indexer.protonnz.com/api/events \
  | jq '.graduations'
```

### Check liquidity depth before large trade

```bash
# How much can you trade with <5% price impact?
curl -s https://indexer.protonnz.com/api/pools?poolId=6 \
  | jq '.pools[0] | {pair: (.tokenA.symbol + "/" + .tokenB.symbol), depth5pct, depth10pct}'
```

### Top tokens by supply burned

```bash
curl -s https://indexer.protonnz.com/api/leaderboard/burns?limit=10 \
  | jq '.tokens[] | {symbol, burnPercent, burned, circulatingSupply}'
```

### Check your P&L and holdings

```bash
# Am I profitable? What do I hold?
curl -s https://indexer.protonnz.com/api/portfolio/youraccount/pnl \
  | jq '{realizedPnl: .summary.totalRealizedPnlUsd, winRate: .summary.winRate, tokens: [.tokens[] | {symbol, realizedPnlUsd, stillHeld, unrealizedPnlUsd, inLp}]}'
```

### Get your recent trades

```bash
curl -s 'https://indexer.protonnz.com/api/portfolio/youraccount/trades?limit=10' \
  | jq '.trades[] | {type: .tradeType, symbol, amount, outputSymbol, outputAmount, usd: .amountUsd}'
```

### Check your trading volume and fees paid

```bash
curl -s https://indexer.protonnz.com/api/portfolio/youraccount \
  | jq '{volume: .summary.totalVolumeUsd, fees: .summary.totalFeesPaidUsd, trades: .summary.totalTrades, byType: .byType}'
```

### See top traders (leaderboard)

```bash
curl -s 'https://indexer.protonnz.com/api/leaderboard/profit?limit=5' \
  | jq '.traders[] | {account, pnl: .realizedPnlUsd, winRate, volume: .volumeUsd}'
```

---

## 9 — Error handling

| Error message | Cause | Fix |
|--------------|-------|-----|
| `Swap amount exceeds maximum` | Input > 50% of reserve | Split into smaller swaps |
| `Slippage exceeded` | Price moved past minAmountOut | Increase slippage tolerance or retry |
| `Pool is paused` | Admin paused pool | Wait or use a different pool |
| `Insufficient balance` | Not enough tokens | Check balance first |
| `Token must be graduated` | Trying DEX ops on curve token | Use buy/sell actions on launch contract instead |
| `Swap cooldown active` | < 1 second since last swap action | Wait 1 second between swap/multihopswap calls |
| `Deposit expired` | Deposit older than 24 hours | Withdraw and re-deposit |
| `Maximum 10 deposits per user` | 10 stale deposits from incomplete add-liquidity attempts | Run `cleandeposit` to clear expired deposits, or `withdrawdep` for non-expired ones (see §4.1.1) |
| `Pool already exists for this token pair` | Pair already has a pool | Use existing pool |
| `insufficient ram` | Account needs more RAM to hold new token balances | Buy RAM via `eosio::buyrambytes` or at resources.xprnetwork.org/storage |

---

## 10 — About

SimpleDEX is built by [Proton NZ](https://protonnz.com) on [XPR Network](https://xprnetwork.org).
Smart contracts are open source. The protocol is non-custodial — no one can
access your funds except through on-chain actions signed by your private key.

Security: Audited Feb & Mar 2026. Guardian monitoring with auto-pause on
anomalous pool drains. Circuit breakers and timelocked admin changes.
23 reserved symbols prevent impersonation of ecosystem tokens (XPR, METAL,
SNIPS, all wrapped xtokens). Creator blacklist for moderation.

Report bugs or security issues: https://protonnz.com