# SimpleDEX — Analytics API & on-chain reads (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

## 1 — Analytics API (no auth required)

The indexer polls on-chain data every 5 minutes and serves analytics via
a public REST API. All endpoints return JSON with CORS enabled.

Base URL: `https://indexer.protonnz.com`

**Agent efficiency guide** — choose the smallest endpoint for your task:
- Quick market check: `GET /api/tokens?fields=compact&limit=5` (~400 bytes)
- Latest launches: `GET /api/tokens?sort=newest&fields=compact&limit=5` (~400 bytes)
- One token lookup: `GET /api/tokens?symbol=MARSH` (~300 bytes)
- Platform stats only: `GET /api/stats` (~200 bytes, includes volume/fees)
- Volume summary: `GET /api/volume` (~500 bytes, daily time-series + totals)
- My position/PnL: `GET /api/portfolio/:account/pnl` (~1KB per token traded)
- My recent trades: `GET /api/portfolio/:account/trades?limit=10` (~500 bytes)
- Top traders: `GET /api/leaderboard/profit?limit=5` (~300 bytes)
- All traders: `GET /api/traders?sort=volume&limit=50` (~3KB, paginated)
- Full protocol snapshot: `GET /api/overview` (~15KB, use sparingly)

### 1.1 Full protocol overview (one call)

```
GET /api/overview
```

Returns everything in one response: protocol info, live stats, all tokens
(with prices, images, creators), and all pools (with TVL and depth).
Updated every 5 minutes. This is the best starting point for agents
that need a complete picture of the platform.

### 1.3 Token prices

#### v1 (flat)

```
GET /api/prices                # default: flat array
GET /api/prices?format=object  # keyed by symbol (legacy)
```

Default returns a flat array of all tokens:

```json
[
  {
    "symbol": "PUMP",
    "price": 0.000123,
    "mcap": 123000,
    "contract": "simpletoken",
    "change24h": 5.2,
    "change7d": -2.1,
    "ath": 0.000456,
    "athTimestamp": 1740700000,
    "high24h": 0.00013,
    "low24h": 0.00011,
    "supply": 715614513.8,
    "maxSupply": 1000000000,
    "burned": 148375585.9,
    "circulatingSupply": 567238927.9
  }
]
```

`?format=object` returns the same data keyed by symbol: `{ "PUMP": { ... } }`.

#### v2 (paginated, sorted, nested)

```
GET /api/v2/prices
GET /api/v2/prices?page=1&limit=50&sort=mcap&order=desc
```

Parameters:
- `page` — page number, 1-based (default: 1)
- `limit` — items per page (default: 100, max: 1000)
- `sort` — field to sort by: `mcap`, `price`, `change24h`, `change7d`, `symbol`
- `order` — `asc` or `desc` (default: desc)

Response:

```json
{
  "items": [
    {
      "symbol": "PUMP",
      "contract": "simpletoken",
      "tokenId": 42,
      "precision": 4,
      "price": {
        "usd": 0.000123,
        "change24h": 5.2,
        "change7d": -2.1,
        "ath": 0.000456,
        "athTimestamp": 1740700000,
        "high24h": 0.00013,
        "low24h": 0.00011
      },
      "market": {
        "mcap": 123000,
        "supply": 715614513.8,
        "maxSupply": 1000000000,
        "circulatingSupply": 567238927.9,
        "burned": 148375585.9
      }
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 404,
  "pages": 9
}
```

Fields `change24h`, `change7d` are null until enough snapshots accumulate.
Supply fields are null for non-graduated tokens (virtual curve, no on-chain supply).

### 1.3.1 Token price history (for charts)

```
GET /api/prices/MARSH/history           # all history (up to 30 days)
GET /api/prices/MARSH/history?since=TS  # from unix timestamp
```

Returns time-series price data for charting:

```json
{
  "symbol": "MARSH",
  "history": [
    { "price": 0.0000211, "timestamp": 1740600000 },
    { "price": 0.0000222, "timestamp": 1740600300 }
  ]
}
```

Data points are ~5 minutes apart. Retained for 30 days.
Useful `since` values: `now - 86400` (24h), `now - 604800` (7d).

### 1.4 Token details (for investigating launches)

```
GET /api/tokens                          # all tokens (full details)
GET /api/tokens?symbol=MARSH             # single token lookup
GET /api/tokens?creator=westcoastred     # tokens by launcher account
GET /api/tokens?graduated=true           # only graduated tokens
GET /api/tokens?graduated=false          # only tokens still on curve
GET /api/tokens?sort=newest&limit=5      # 5 most recently created tokens
GET /api/tokens?fields=compact           # lightweight: no description/image/ATH
GET /api/tokens?fields=compact&limit=10  # top 10 by mcap, minimal fields
GET /api/tokens?sort=newest&fields=compact&limit=5  # latest launches, minimal
```

Full response (default):

```json
{
  "tokens": [{
    "tokenId": 5, "symbol": "MARSH", "name": "Marshall Coin",
    "description": "A homage to the Living Legend...",
    "imageUrl": "https://simplelaunch.mypinata.cloud/ipfs/QmRPc...",
    "creator": "westcoastred", "graduated": true, "dexPoolId": 6,
    "price": 0.0000222, "mcap": 22284, "change24h": 5.2, "change7d": -2.1,
    "ath": 0.0000456, "athTimestamp": 1740700000,
    "high24h": 0.000025, "low24h": 0.000020,
    "supply": 710382366.7, "maxSupply": 1000000000,
    "burned": null, "circulatingSupply": 710382366.7,
    "buys24h": 182, "sells24h": 175,
    "volume24h": 1200.50, "uniqueTraders24h": 45,
    "totalUnclaimed": 180000000, "unclaimedAccounts": 3
  }],
  "count": 29
}
```

Compact response (`fields=compact`) — 8 fields per token instead of 16:

```json
{ "tokens": [{ "tokenId": 5, "symbol": "MARSH", "name": "Marshall Coin",
    "creator": "westcoastred", "graduated": true,
    "price": 0.0000222, "mcap": 22284, "change24h": 5.2 }], "count": 1 }
```

**Tip for agents**: Use `?fields=compact&limit=10` for a quick market
overview, then `?symbol=X` to drill into a specific token.

### 1.5 Pool data with liquidity depth

```
GET /api/pools
GET /api/pools?poolId=6
```

Returns all pools with reserves, TVL, fee rate, volume, fees, APY,
and max swap size at 5% and 10% price impact:

```json
{
  "pools": [{
    "poolId": 6,
    "tokenA": { "symbol": "XPR", "contract": "eosio.token" },
    "tokenB": { "symbol": "MARSH", "contract": "simpletoken" },
    "reserveA": "1700000000",
    "reserveB": "50000000000",
    "tvlUsd": 5136.52,
    "feeRate": 30,
    "depth5pct": { "tokenA": 135.2, "tokenB": 132.8 },
    "depth10pct": { "tokenA": 285.6, "tokenB": 280.1 },
    "volumeUsd24h": 1200.50,
    "volumeUsd7d": 8400.00,
    "feesUsd24h": 3.60,
    "apyBase": 12.5
  }],
  "count": 27
}
```

`depth5pct.tokenA` = max USD you can sell of tokenA before 5% price impact.
`apyBase` = annualized LP fee yield based on 7d volume and current TVL.

### 1.6 TVL history

```
GET /api/tvl
GET /api/tvl?since=1740600000
```

Aggregate TVL history and current platform stats:

```json
{
  "history": [{ "totalTvlUsd": 50000, "timestamp": 1740600000 }],
  "current": {
    "totalTvlUsd": 14741,
    "totalMarketCapUsd": 48473,
    "poolCount": 27,
    "tokenCount": 29,
    "graduatedCount": 16
  }
}
```

### 1.7 Pool TVL history

```
GET /api/pools/6/tvl
GET /api/pools/6/tvl?since=1740600000
```

### 1.8 Volume and fees

```
GET /api/volume                  # aggregate daily volume time-series + summary
GET /api/volume?since=1740600000 # from unix timestamp
```

```json
{
  "daily": [
    { "day": 1740700000, "volume": 9020.50, "fees": 27.06, "trades": 1005 }
  ],
  "summary": {
    "volume24h": 9020.50,
    "volume7d": 42000.00,
    "volumeTotal": 142000.00,
    "fees24h": 27.06,
    "fees7d": 126.00,
    "trades24h": 1005,
    "trades7d": 7035
  }
}
```

Volume is indexed from Hyperion swap history into SQLite. Updated every
5 minutes. Daily buckets are UTC midnight-aligned.

### 1.8.1 Pool volume history

```
GET /api/pools/6/volume
GET /api/pools/6/volume?since=1740600000
```

```json
{
  "poolId": 6,
  "daily": [{ "day": 1740700000, "volume": 1200.50, "fees": 3.60, "trades": 150 }],
  "summary": { "volume24h": 1200.50, "volume7d": 8400.00, "fees24h": 3.60, "fees7d": 25.20 }
}
```

### 1.8.2 DefiLlama integration endpoints

These endpoints serve pre-computed data in DefiLlama's expected format:

```
GET /api/defillama/summary              # daily + total volume, fees, revenue
GET /api/defillama/pools                # per-pool TVL, APY, volume (yield format)
GET /api/defillama/volume?timestamp=TS  # historical daily volume for a specific day
```

Summary response:

```json
{
  "dailyVolume": 9020.50,
  "totalVolume": 142000.00,
  "dailyFees": 27.06,
  "dailyUserFees": 27.06,
  "dailyRevenue": 9.02,
  "dailySupplySideRevenue": 18.04,
  "totalFees": 426.00,
  "totalRevenue": 142.00,
  "tvl": 22000.00,
  "timestamp": 1709251200
}
```

Fee breakdown: 0.3% swap fee → 50% protocol revenue, 50% to LPs.

### 1.9 Platform stats

```
GET /api/stats
```

```json
{
  "totalTvlUsd": 14741,
  "totalMarketCapUsd": 48473,
  "poolCount": 27,
  "tokenCount": 29,
  "graduatedCount": 16,
  "dailyVolumeUsd": 9020.50,
  "dailyFeesUsd": 27.06,
  "dailyTradeCount": 1005,
  "weeklyVolumeUsd": 42000.00,
  "weeklyFeesUsd": 126.00,
  "weeklyTradeCount": 7035,
  "timestamp": 1740700000
}
```

### 1.10 Top movers

```
GET /api/movers
GET /api/movers?limit=10
```

Top gainers and losers by 24h % change:

```json
{
  "gainers": [{ "symbol": "PUMP", "tokenId": 1, "price": 0.000123, "mcap": 123000, "change24h": 25.5 }],
  "losers": [{ "symbol": "DUMP", "tokenId": 2, "price": 0.000001, "mcap": 1000, "change24h": -40.2 }]
}
```

### 1.11 Graduation events

```
GET /api/events
GET /api/events?limit=10&since=1740600000
```

```json
{
  "graduations": [{
    "tokenId": 5,
    "symbol": "PUMP",
    "name": "PumpCoin",
    "creator": "pumpmaker",
    "dexPoolId": 12,
    "detectedAt": 1740700000
  }]
}
```

### 1.12 Trade history

```
GET /api/tokens/107/trades?limit=50&offset=0    # token trades (paginated)
GET /api/tokens/107/trades?limit=50&offset=200   # page 5 of token trades
GET /api/pools/107/trades?limit=50&offset=0      # pool trades from DB (paginated)
GET /api/pools/107/trades?limit=5&live=1         # pool trades from live Hyperion (10s cache)
GET /api/tokens/107/holders?limit=50             # top holders (pre-computed, zero RPC)
```

Query params for token/pool trades:
- `limit` — results per page (default 50, max 200)
- `offset` — skip first N results (default 0). Use for pagination.
- `live` — (pool trades only) `1` for near-real-time Hyperion data instead of DB

Token trade response format (graduated tokens from DB):

```json
{
  "trades": [
    {
      "type": "buy",
      "account": "trader1",
      "xprAmount": 1000.0,
      "tokenAmount": 45000000,
      "outputQuantity": null,
      "timestamp": "2026-03-14T03:37:43.000Z",
      "txId": "abc123..."
    },
    {
      "type": "sell",
      "account": "trader2",
      "xprAmount": 500.0,
      "tokenAmount": 22000000,
      "outputQuantity": null,
      "timestamp": "2026-03-14T03:30:00.000Z",
      "txId": "def456..."
    }
  ],
  "total": 1270,
  "hasMore": true,
  "source": "indexer"
}
```

Pool trade response format:

```json
{
  "trades": [
    {
      "type": "swap",
      "account": "trader1",
      "amountIn": "1000.0000 XPR",
      "amountOut": "45000.0000 AGENT",
      "timestamp": "2026-03-14T03:37:43.000Z",
      "txId": "abc123..."
    }
  ],
  "total": 1270,
  "hasMore": true,
  "source": "indexer"
}
```

**Pagination example** — to get ALL trades for a token:
```bash
# Page 1
curl -s 'https://indexer.protonnz.com/api/tokens/182/trades?limit=200&offset=0'
# Page 2
curl -s 'https://indexer.protonnz.com/api/tokens/182/trades?limit=200&offset=200'
# Continue until hasMore=false
```

**Data freshness guide for agents:**
- **Non-graduated tokens**: Trades come from live Hyperion (10s cache). Brand new tokens (not yet in 5-min poll) are also served live.
- **Graduated tokens**: Trades come from SQLite DB (synced every ~5 min). For real-time needs, use pool trades with `?live=1`.
- **Holders**: Pre-computed LP-augmented balances (zero RPC at request time). Returns empty `[]` for non-graduated tokens (virtual curve, no on-chain balances).
- **Prices/stats**: Updated every 5 min from on-chain poll. Use `/api/prices` for latest.

### 1.12.1 Rate limiting

The indexer API has IP-based rate limits:

| Endpoint type | Limit |
|---------------|-------|
| General (prices, stats, pools, tokens) | 120 requests/min |
| Expensive (trades, holders, OG images, exports) | 50 requests/min |

When scanning multiple tokens (e.g., all 200 holders endpoints), add a small
delay between requests (~1.5s) to stay within limits. Or use `/api/overview`
which returns all tokens and pools in one call.

### 1.13 Health check

```
GET https://indexer.protonnz.com/health
```

```json
{ "status": "ok", "snapshots": 8352, "poolSnapshots": 7776, "lastPoll": 1740700000 }
```

### 1.14 Portfolio & PnL (know your position)

**Agent efficiency guide** — choose the right endpoint:
- Quick position check: `GET /api/portfolio/:account/pnl` (per-token P&L, holdings, LP)
- Trade history: `GET /api/portfolio/:account/trades?limit=20` (paginated)
- Account summary: `GET /api/portfolio/:account` (volume, fees, trade counts)
- LP activity: `GET /api/portfolio/:account/lp-events?limit=20`
- LP fee earnings: `GET /api/portfolio/:account/lp-earnings` (estimated fees per pool)

#### Account summary

```
GET /api/portfolio/youraccount
```

```json
{
  "account": "youraccount",
  "summary": {
    "totalTrades": 142,
    "totalVolumeUsd": 15230.50,
    "totalFeesPaidUsd": 45.69,
    "lastTrade": 1740700000
  },
  "byType": {
    "swap": { "count": 80, "volumeUsd": 10000.00 },
    "buy": { "count": 30, "volumeUsd": 3000.00 },
    "sell": { "count": 20, "volumeUsd": 2000.00 },
    "addlp": { "count": 6, "volumeUsd": 200.00 },
    "removelp": { "count": 6, "volumeUsd": 30.50 }
  },
  "lpSummary": {
    "totalDepositsUsd": 200.00,
    "totalWithdrawalsUsd": 30.50,
    "eventCount": 12,
    "pools": [
      { "poolId": 6, "depositsUsd": 200.00, "withdrawalsUsd": 30.50 }
    ]
  }
}
```

#### Per-token PnL (cost basis + unrealized)

```
GET /api/portfolio/youraccount/pnl
```

```json
{
  "account": "youraccount",
  "summary": {
    "totalRealizedPnlUsd": 1250.00,
    "totalVolumeUsd": 15230.50,
    "winRate": 66.67,
    "tradeCount": 142,
    "profitableCount": 4,
    "totalTokensTraded": 6,
    "bestToken": "MARSH",
    "worstToken": "DUMP"
  },
  "tokens": [
    {
      "symbol": "MARSH",
      "totalBought": 50000000,
      "totalBoughtUsd": 1500.00,
      "totalSold": 20000000,
      "totalSoldUsd": 800.00,
      "lpSold": 5000000,
      "lpSoldUsd": 150.00,
      "realizedPnlUsd": 200.00,
      "avgBuyPriceUsd": 0.00003,
      "currentPriceUsd": 0.0000222,
      "stillHeld": 30000000,
      "unrealizedPnlUsd": -234.00,
      "inLp": 5000000,
      "inLpUsd": 111.00
    }
  ]
}
```

Cost basis method: average cost. `stillHeld` is the on-chain wallet balance.
`inLp` is the amount locked in LP positions (resolved from DEX `lp` table).
`totalSold`/`totalSoldUsd` = direct sells only (LP deposits excluded).
`lpSold`/`lpSoldUsd` = tokens deposited into LP (tracked separately for tax exports).
`realizedPnlUsd` = profit/loss from direct sells only (LP deposits excluded).
`unrealizedPnlUsd = stillHeld * (currentPrice - avgBuyPrice)`.
PnL is recomputed every ~50 minutes. Prices update every 5 minutes.

#### Trade history (paginated)

```
GET /api/portfolio/youraccount/trades?limit=20&offset=0
GET /api/portfolio/youraccount/trades?type=swap&limit=50
GET /api/portfolio/youraccount/trades?since=1740600000
```

Query params:
- `limit` (default 50, max 200)
- `offset` (default 0)
- `type` — filter: `swap`, `buy`, `sell`, `claim`, `send`, `addlp`, `removelp`
- `since` — unix timestamp, only trades on or after

```json
{
  "trades": [
    {
      "id": 1234,
      "trxId": "abc123...",
      "account": "youraccount",
      "tradeType": "swap",
      "poolId": 6,
      "tokenId": null,
      "symbol": "XPR",
      "tokenContract": "eosio.token",
      "amount": 1000000,
      "amountUsd": 30.00,
      "feeUsd": 0.09,
      "timestamp": 1740700000,
      "blockNum": 123456789,
      "outputAmount": 45000000,
      "outputSymbol": "MARSH",
      "tokenSymbol": "MARSH"
    }
  ],
  "total": 142,
  "hasMore": true
}
```

**Critical: Understanding `tradeType` values for direction:**

| `tradeType` | Source | Direction |
|-------------|--------|-----------|
| `buy` | Bonding curve buy | XPR → Token (on simplelaunch) |
| `sell` | Bonding curve sell | Token → XPR (on simplelaunch) |
| `swap` | DEX pool trade | **Either direction** — check `symbol` to determine: if `symbol` is `XPR` it's a buy, otherwise it's a sell |
| `multihop` | Multi-pool routed swap | Same as `swap` — check `symbol` for direction |
| `claim` | Post-graduation claim | Free token issuance |
| `send` | Token transfer | Peer-to-peer send |
| `addlp` | Add liquidity | LP deposit |
| `removelp` | Remove liquidity | LP withdrawal |

**Example: finding all DEX sells of AGENT by an account:**
```bash
curl -s 'https://indexer.protonnz.com/api/portfolio/someaccount/trades?type=swap&limit=200' \
  | jq '[.trades[] | select(.symbol == "AGENT")] | length'
# symbol=AGENT means the user SENT Agent → this is a sell
# symbol=XPR with outputSymbol=AGENT means the user SENT XPR → this is a buy
```

LP add/remove events are merged into the trade list (as `tradeType: "addlp"` / `"removelp"`) unless you filter by `type`.

#### LP events

```
GET /api/portfolio/youraccount/lp-events?limit=20
GET /api/portfolio/youraccount/lp-events?poolId=6
```

Query params: `limit` (default 50, max 200), `offset` (default 0), `poolId` (filter)

```json
{
  "events": [
    {
      "id": 56,
      "trxId": "def456...",
      "account": "youraccount",
      "eventType": "add",
      "poolId": 6,
      "amountA": 1000000,
      "symbolA": "XPR",
      "amountB": 45000000,
      "symbolB": "MARSH",
      "totalUsd": 60.00,
      "timestamp": 1740700000,
      "blockNum": 123456789
    }
  ],
  "total": 12,
  "hasMore": false
}
```

#### LP fee earnings (estimated)

```
GET /api/portfolio/youraccount/lp-earnings
```

Returns estimated fee earnings for each pool the account has provided liquidity to.
Compares current LP value against deposited value and HODL value to estimate fees earned.

```json
{
  "account": "youraccount",
  "totalDepositedUsd": 500.00,
  "totalCurrentValueUsd": 520.00,
  "totalHodlValueUsd": 510.00,
  "totalLpValueUsd": 520.00,
  "totalEarningsUsd": 10.00,
  "totalEstimatedFeesUsd": 15.50,
  "pools": [
    {
      "poolId": 6,
      "pair": "XPR/SNIPS",
      "depositedUsd": 300.00,
      "withdrawnUsd": 0,
      "currentValueUsd": 315.00,
      "hodlValueUsd": 305.00,
      "earningsUsd": 10.00,
      "earningsPercent": 3.28,
      "sharePercent": 12.5,
      "lpTokens": 50000,
      "firstDeposit": "2026-02-15T10:00:00Z",
      "estimatedDailyFees": 0.35,
      "estimatedFeesEarned": 15.50,
      "daysInPool": 41
    }
  ]
}
```

#### Tax export (CSV)

```
GET /api/portfolio/youraccount/export?format=koinly&year=2026
GET /api/portfolio/youraccount/export?format=csv&year=2026
```

Returns a CSV file download. Formats: `koinly` (Koinly-compatible labels) or `csv` (standard).

**Requires payment.** If not paid, returns HTTP 402 with pricing and payment instructions:

```json
{
  "error": "payment_required",
  "pricing": {
    "30_days": { "xpr": "800.0000 XPR", "xmd": "2.000000 XMD" },
    "365_days": { "xpr": "6000.0000 XPR", "xmd": "15.000000 XMD" },
    "lifetime": { "xpr": "12000.0000 XPR", "xmd": "30.000000 XMD" }
  },
  "instructions": {
    "to": "dex.protonnz",
    "memo": "taxreport:youraccount:DAYS",
    "example": "taxreport:youraccount:30",
    "note": "Send XPR (via eosio.token) or XMD (via xmd.token)"
  }
}
```

Includes: all trades, LP events (staked/unstaked), creator fee income, token
creation fees (deductible). Historical prices from on-chain snapshots.

### 1.15 Leaderboard

```
GET /api/leaderboard/profit
GET /api/leaderboard/profit?limit=10
```

Top traders by realized PnL:

```json
{
  "traders": [
    {
      "account": "toptrader",
      "realizedPnlUsd": 5000.00,
      "volumeUsd": 50000.00,
      "tradeCount": 500,
      "profitableCount": 8,
      "totalTokensTraded": 12,
      "winRate": 66.67,
      "lastTrade": 1740700000
    }
  ]
}
```

`limit` default 20, max 100. Ordered by realized PnL descending.

### 1.16 All traders

```
GET /api/traders
GET /api/traders?sort=volume&order=desc&limit=50&offset=0
GET /api/traders?sort=pnl&min_trades=5
```

Paginated list of all traders with stats. Sortable and filterable.

Query params:
- `sort`: `volume` (default), `pnl`, `trades`, `last_trade`, `tokens`, `win_rate`
- `order`: `desc` (default), `asc`
- `limit`: 1–200, default 50
- `offset`: default 0
- `min_trades`: minimum trade count filter (default 1)

```json
{
  "traders": [
    {
      "account": "sometrader",
      "tradeCount": 320,
      "volumeUsd": 45000.00,
      "realizedPnlUsd": 1200.50,
      "profitableCount": 6,
      "totalTokensTraded": 10,
      "winRate": 60.00,
      "lastTrade": 1740700000
    }
  ],
  "total": 1500,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}
```

### 1.17 Burns leaderboard

```
GET /api/leaderboard/burns
GET /api/leaderboard/burns?limit=10
```

Top tokens by percentage of supply burned:

```json
{
  "tokens": [
    {
      "symbol": "DOG",
      "tokenId": 42,
      "burned": 565897586,
      "supply": 733697075,
      "circulatingSupply": 167799489,
      "burnPercent": 77.13,
      "price": 0.0000012,
      "mcap": 201
    }
  ]
}
```

`limit` default 10, max 50. Ordered by burn percentage descending.
`burned` = tokens sent to `token.burn` account. `supply` = total minted (includes burned).
`circulatingSupply = supply - burned`. Only graduated tokens have burn data.

---

## 2 — Reading on-chain state (no auth required)

All reads use the standard EOSIO `get_table_rows` RPC endpoint.

### 2.1 List all pools

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -H 'Content-Type: application/json' \
  -d '{"json":true,"code":"simpledex","scope":"simpledex","table":"pools","limit":100}'
```

Response fields per row:
- `id` — pool ID (use this in swap/liquidity actions)
- `tokenAContract`, `tokenASymbol` — first token
- `tokenBContract`, `tokenBSymbol` — second token
- `reserveA`, `reserveB` — current reserves (raw u64)
- `totalLpTokens` — total LP supply
- `feeRate` — basis points (30 = 0.3%)
- `paused` — 1 if paused

### 2.2 Get a single pool

Set `lower_bound` and `upper_bound` to the pool ID:

```bash
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}'
```

### 2.3 Get your LP position

Scope is your account name:

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simpledex","scope":"youraccount","table":"lp","limit":100}'
```

### 2.4 Get token balance

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"eosio.token","scope":"youraccount","table":"accounts","limit":100}'
```

For SimpleLaunch tokens use `"code":"simpletoken"`.

### 2.5 List bonding curves

```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}'
```

Response fields per row:
- `id` — token ID
- `symbol` — e.g. `"4,COOK"`
- `creator`, `name`, `description`, `imageUrl`
- `virtualXpr`, `virtualTokens` — bonding curve reserves
- `realXpr` — actual XPR collected (compare to graduation threshold)
- `realTokensSold`
- `graduated` — 1 if graduated to DEX
- `dexPoolId` — DEX pool ID after graduation

### 2.6 Get launch config and fees

```bash
# Graduation parameters
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simplelaunch","scope":"simplelaunch","table":"gradparams","limit":1}'

# Fee config
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simplelaunch","scope":"simplelaunch","table":"fees","limit":1}'
```

### 2.7 Get your bonding curve holdings

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simplelaunch","scope":"youraccount","table":"holdings","limit":100}'
```

### 2.8 Contract table quick reference

**simpledex tables** (scope: `simpledex` unless noted):
| Table | Scope | Key fields |
|-------|-------|------------|
| `pools` | simpledex | id, tokenAContract, tokenASymbol, tokenBContract, tokenBSymbol, reserveA, reserveB, totalLpTokens, feeRate, paused |
| `lp` | *user account* | poolId, lpTokens |
| `deposits` | *user account* | poolId, amountA, amountB |
| `protofee` | simpledex | enabled, feeShareBps, treasury |
| `allowedctrs` | simpledex | contract (whitelisted token contracts) |

**simplelaunch tables** (scope: `simplelaunch` unless noted):
| Table | Scope | Key fields |
|-------|-------|------------|
| `curves` | simplelaunch | id, symbol, creator, name, description, imageUrl, virtualXpr, virtualTokens, realXpr, realTokensSold, graduated, dexPoolId, createdAt |
| `holdings` | *user account* | tokenId, amount |
| `gradparams` | simplelaunch | threshold, cooldownSec, dexFeeRate |
| `fees` | simplelaunch | buyFeeBps, sellFeeBps, creatorShareBps |
| `antisnipe` | simplelaunch | creatorOnlyPeriodSec, earlyPeriodSec, maxBuyPerTxEarly, maxBuyPerTx |
| `community` | simplelaunch | tokenId, description, website, telegram, twitter, discord, bannerUrl |
| `config` | simplelaunch | treasury, creationFee |
| `blacklist` | simplelaunch | account, blocked |
| `hidden` | simplelaunch | tokenId, hide |
| `reserved` | simplelaunch | symbol, reserve |

### 2.9 Get protocol fee config

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"simpledex","scope":"simpledex","table":"protofee","limit":1}'
```

### 2.10 Get XPR/USD oracle price

```bash
curl -s -X POST https://api.protonnz.com/v1/chain/get_table_rows \
  -d '{"json":true,"code":"oracles","scope":"oracles","table":"data","lower_bound":"3","upper_bound":"3","limit":1}'
```

The `aggregate.d_double` field contains the USD price. Feed index 3 = XPR.

---