API Reference

Base URL: https://api.coffer.so. The endpoints on this page are public: no API key, no sign-in. They read indexed data; trades and liquidity operations are signed Solana transactions (see the SDK).

Interactive OpenAPI documentation with exact schemas lives at https://api.coffer.so/docs. Endpoints that back the Coffer app itself (wallet sign-in, portfolio, referrals, pool registration and renaming) are not covered here: create and manage pools through app.coffer.so.

Conventions

• Addresses are base58; token amounts and LP supply are raw integer strings. Calculate with bigint.
• swapFee, protocolFeeRate and weight are display percentages: swapFee: 0.3 means 0.3%; protocolFeeRate: 20 means the protocol takes 20% of the base fee.
• Pagination: limit 1–100 (default 50), offset 0–10,000 (default 0).
• Standard envelope: { "success": true, "data": ... }; paginated responses add hasMore and totalCount. The exceptions below return a flat object.
• Rate limits are per IP: 10 requests per second and 200 per minute across the API; chart endpoints have their own per-IP limits. On 429, back off.
• Indexed state lags the chain by seconds to minutes. Refresh from chain before building a transaction.

Pool and token discovery

Discovery can include disabled pools: check poolEnabled and swapsEnabled.

Pool fields include poolAddress, poolName, baseAssetMint, swapFee, protocolFeeRate, poolEnabled, swapsEnabled, poolAdmin, bptMint, bptTotalSupply, bptPriceUsd, tvlUsd, virtualTvlUsd, volume24h, apy, apy7d, apyUnreliable, the range-manager settings (rangeManager*) and tokens. Each token carries mintAddress, ticker, decimals, weight, leverage (rounded for display), actualBalance, virtualBalance, vaultAddress, tokenProgram, orderIndex, imageUrl, isActive and the sell-off window settings (maxSelloffPct, variableFee*, currentSelloff, windowStartTimestamp).

• apy is the 24-hour figure shown in the app, apy7d the 7-day one; both are compounded, see How Yield Is Generated. apyUnreliable: true means the pool's TVL is too small for the figure to mean anything and both are reported as 0.
• actualBalance is already net of protocol fees: never subtract protocolFeesOwed again. protocolFeesOwed is not returned; read it on chain.
• Metrics and token metadata can be null while a pool is being indexed.

Swap routes

GET /api/pools/swap-route?tokenIn=<mint>&tokenOut=<mint>&amountIn=<raw>&decimalsIn=9

Response, with placeholder addresses:

{
  "success": true,
  "data": {
    "routes": [{
      "poolAddress": "<pool>",
      "poolName": "SOLUSDC",
      "amountIn": "1000000000",
      "expectedOut": "149000000",
      "minAmountOut": "146020000",
      "percentage": 100,
      "swapFee": 0.3,
      "surgeFeeAmount": "0",
      "surgeFeePct": 0,
      "tokenInIndex": 0,
      "tokenOutIndex": 1,
      "tokenProgramIn": "<input-token-program>",
      "tokenProgramOut": "<output-token-program>",
      "vaultIn": "<input-vault>",
      "vaultOut": "<output-vault>"
    }],
    "totalAmountIn": "1000000000",
    "totalExpectedOut": "149000000",
    "minReceived": "146020000",
    "slippageBps": 200,
    "effectivePrice": 0.149,
    "spotPrice": 0.15,
    "priceImpact": 0.36777,
    "feePercent": 0.3,
    "totalSurgeFee": "0",
    "estimatedXp": 0,
    "xpBoostApplied": false
  }
}

The route is a quote, not a transaction. HTTP 200 with an empty routes array or zero output means no usable route. Swap Routing covers how to turn a route into a protected transaction.

Transactions and aggregate statistics

Transaction rows carry raw amounts (amountIn, amountOut, feeAmount, protocolFeeAmount, surgeFeeAmount), their USD values, the pool state after the transaction (virtualBalances, actualBalances, normalizedWeights, bptTotalSupply) and blockTime/slot. Base fees and their protocol share are in input-token units; surge fees in output-token units. zap is a single-token deposit.

Time series

GET /api/stats/:metric?pool=<address>&window=7d

Metrics: tvl, volume, swap_count, avg_swap, median_swap, fees_lp, fees_protocol, users_total, dau, mau, deposits, removals. pool defaults to all (the whole protocol). Windows: 1d, 7d (default), 30d, all (everything since launch). Points are ten-minute buckets.

Flat response: { "points": [{ "t": 1714003200000, "v": 1234567.89 }] }, t in Unix milliseconds, v in USD or a count.

Charts

The series behind the app's charts, on a uniform time grid and cached for a couple of minutes.

Pair-chart ratios keep six significant digits (BONK/SOL-style prices are tiny); a mint without a known USD price history yields a flat line at its current price.

XP leaderboard

Read-only views of Coffer XP. Flat responses.

swapXpPerUsdLpFee applies to the trade's entire base fee in USD (LP plus protocol share, excluding surge). currentRates.lpXpPerUsd is per three-hour run; lpXpPerUsdPerDay is the daily figure shown in the app.

Errors

Errors use { "success": false, "error": "..." } with the HTTP status: 400 invalid input, 404 unknown pool or wallet, 429 rate limited, 500 server error.

Health and version

GET /health       → { "status": "ok", "timestamp": "..." }
GET /api/version  → { "version": "...", "timestamp": "..." }

Health is HTTP liveness only, not indexing freshness.