IPO Leaderboard API

GET /health

Service health plus latest-snapshot metadata.

• ok stays true while the volume source is degraded — the queue is still served; check volumeDegraded instead.
• relayer is null when no relayer key is configured: gasless deposits and withdrawals are unavailable and their routes 503.

{ "ok": true, "latestSnapshotId": 42, "asOf": 1756677600, "users": 1337,
  "volumeFetchedAt": 1756677000, "volumeDegraded": false,
  "relayer": { "wallets": 2, "redisHealthy": true } }

GET /leaderboard?limit=50&offset=0

The current queue, paginated.

• limit defaults to 50, max 500. offset defaults to 0.
• totalDepositsUsd is the pool-wide sum in whole USD — an aggregate, not anyone's balance.
• 503 until the first ranking has run (the server ranks before binding the port, so this only appears mid-recovery).

{ "snapshotId": 42, "asOf": 1756677600, "users": 1337,
  "totalDepositsUsd": 523000, "limit": 50, "offset": 0,
  "rows": [ { "rank": 1, "user": "0xabc…", "depositUsd": 12000 }, … ] }

GET /leaderboard/:address

One user's queue position.

• 404 if the address is not ranked (no net deposit).

{ "snapshotId": 42, "asOf": 1756677600, "users": 1337, "user": "0xabc…", "rank": 17 }

GET /snapshots?limit=20

Ids of retained past rankings, newest first (limit max 100).

{ "snapshotIds": [42, 41, 40, …] }

GET /snapshots/:id?limit=50&offset=0

A past ranking, same shape as /leaderboard.

• 404 once the snapshot has aged out of retention.

GET /pools

Every indexed pool with metadata, as { pools: [ { pool, …metadata } ] }.

GET /pools/:address

One pool's metadata.

• 404 if the pool has no catalog entry or is not indexed here, 503 if no catalog is configured.

{ "pool": "0x033d…0973", "name": "Anthropic", "ticker": "ANTH", "logoUrl": null,
  "description": "Anthropic is an AI safety and research company…",
  "marketCapEstimate": { "low": "$1.5T", "high": "$2.5T" }, "closeTime": null,
  "links": { "website": "https://www.anthropic.com", "x": "https://x.com/anthropicai" },
  "details": { "sector": "Artificial Intelligence / Enterprise Software", "founded": 2021,
    "founder": "Dario Amodei", "headquarters": "San Francisco, CA",
    "type": "Public Benefit Corporation" },
  "fundingRounds": [ { "label": "Series F", "year": 2025, "amountUsd": "$183B" }, … ],
  "totalRaise": "$44B+", "lastValuation": "$1.3T" }

POST /relayDeposit

Relay a Permit2-signed deposit. Body: { pool, owner, beneficiary, amount, permitNonce, deadline, signature }.

• Permit2 must hold an allowance on the quote token first. An owner without one no longer pays for it: pass additionalAllowances — one signed ERC-2612 permit — and the relayer lands permit() and the deposit back-to-back, both on our gas.
• additionalAllowances is [{ token, value, deadline, signature }]: at most one entry, token must be the pool's quote token, value must cover amount, signature exactly 65 bytes. The permit's spender is always Permit2 — it is not a field. Signed over the TOKEN's own EIP-712 domain with the TOKEN's sequential nonces(owner); see the second typed payload below. Silently dropped when the allowance already suffices, so it is safe to always include for a first-time depositor.
• permitNonce is a Permit2 *unordered* nonce — any unused 256-bit value, no sequence required. Reusing a spent one is a 400.
• spender in the signature is the ADAPTER, not the pool: it receives the pulled tokens before forwarding them.
• token is the pool's quoteToken(); read it from the pool, since the adapter signs over that value.
• 200 means broadcast, not mined — txHash is real but pending (permitTxHash too, when a permit was folded). 400 is a bad request (error says which); 503 means retry.

// domain — Permit2's, and it has NO version field
{ "name": "Permit2", "chainId": <CHAIN_ID>,
  "verifyingContract": "0x000000000022d473030f116ddee9f6b43ac78ba3" }
// types
PermitWitnessTransferFrom(TokenPermissions permitted, address spender, uint256 nonce, uint256 deadline, TokenAllocationDeposit witness)
TokenPermissions(address token, uint256 amount)
TokenAllocationDeposit(address owner, address beneficiary, address pool)
// message
{ "permitted": { "token": <quoteToken>, "amount": <amount> },
  "spender": <DEPOSIT_ADAPTER>, "nonce": <permitNonce>, "deadline": <unix seconds>,
  "witness": { "owner": <owner>, "beneficiary": <owner>, "pool": <pool> } }
// primaryType: PermitWitnessTransferFrom

// additionalAllowances[0].signature signs the TOKEN's domain (read it
// via eip712Domain(); the nonce is the token's nonces(owner)):
Permit(address owner, address spender, uint256 value, uint256 nonce, uint256 deadline)
// message: { "owner": <owner>, "spender": "0x000000000022d473030f116ddee9f6b43ac78ba3",
//   "value": <value>, "nonce": <token.nonces(owner)>, "deadline": <unix seconds> }

// → { "txHash": "0x…", "relayer": "0x…", "pool": "0x…", "owner": "0x…",
//     "beneficiary": "0x…", "amount": "25000000000", "permitTxHash": "0x…"? }

GET /relayerWallets

Wallets that may be named as a withdrawal's executor.

• Pick any one before signing a withdrawal. The pool hashes executor against msg.sender, so a signature naming an address we do not hold is unusable.

{ "wallets": ["0x99…", "0x88…"] }

GET /poolNonce/:pool/:owner

The nonce a withdrawal or allocation-request signature must carry.

• Read it immediately before signing. It is ONE counter per user shared by every signed pool operation (withdraw, allocation request, cancel, invalidateSignatures), so any of those invalidates a pending signature.
• 400 if the pool is not one this service relays.

{ "pool": "0x033d…0973", "owner": "0xabc…", "nonce": "3" }

POST /relayWithdraw

Relay a signed withdrawal. Body: { pool, owner, recipient, executor, amount, nonce, deadline, signature }.

• A different scheme from /relayDeposit: the POOL is the verifying contract, not Permit2, and the domain has a version.
• No Permit2 approval is involved — the pool holds the tokens already.
• 400 on a stale nonce (re-read /poolNonce and re-sign), an executor we do not hold, more than the owner's unallocated deposit, or an expired deadline.

// domain — the POOL is the verifying contract
{ "name": "TokenAllocationPool", "version": "1",
  "chainId": <CHAIN_ID>, "verifyingContract": <pool> }
// types
Withdraw(address owner, address recipient, address executor, uint256 amount, uint256 nonce, uint256 deadline)
// message
{ "owner": <owner>, "recipient": <owner>, "executor": <from /relayerWallets>,
  "amount": <amount>, "nonce": <from /poolNonce>, "deadline": <unix seconds> }
// primaryType: Withdraw

// → { "txHash": "0x…", "relayer": "0x…", "pool": "0x…", "owner": "0x…",
//     "recipient": "0x…", "amount": "12500000000" }

POST /relayAllocationRequest

Relay a signed allocation request. Body: { pool, user, quoteAmount, maxPriceUsd, slippageBps, waiveCancellationRights, nonce, deadline, signature }.

• Same scheme as /relayWithdraw — the POOL's domain, the shared sequential nonce from /poolNonce — but with NO executor field: the pool does not bind this signature to a sender.
• Creates or REPLACES the user's request; quoteAmount cannot exceed their deposit.
• maxPriceUsd is USD per whole offered token in 1e18 fixed point; slippageBps caps the discount from the oracle-implied amount (max 10000).
• waiveCancellationRights is part of the signed struct. false: relayable only before an allocation lock is scheduled. true: relayable any time and fillable while locked — but the request cannot be cancelled once locked.
• Cancelling and claiming have their own relayed routes below; the msg.sender-only cancelAllocationRequest()/claimOfferedTokens() remain for a user sending their own transaction.
• 400 on a stale nonce (re-read /poolNonce and re-sign), a bad signature, or an expired deadline.

// domain — the POOL is the verifying contract
{ "name": "TokenAllocationPool", "version": "1",
  "chainId": <CHAIN_ID>, "verifyingContract": <pool> }
// types
AllocationRequest(address user, uint256 quoteAmount, uint256 maxPriceUsd, uint256 slippageBps, bool waiveCancellationRights, uint256 nonce, uint256 deadline)
// message
{ "user": <user>, "quoteAmount": <quoteAmount>, "maxPriceUsd": <1e18 USD>,
  "slippageBps": <bps>, "waiveCancellationRights": <bool>,
  "nonce": <from /poolNonce>, "deadline": <unix seconds> }
// primaryType: AllocationRequest

// → { "txHash": "0x…", "relayer": "0x…", "pool": "0x…", "user": "0x…",
//     "quoteAmount": "5000000", "maxPriceUsd": "25000000000000000000",
//     "slippageBps": "50", "waiveCancellationRights": false }

POST /relayCancelAllocationRequest

Relay a signed cancellation. Body: { pool, user, nonce, deadline, signature }.

• Same domain and shared nonce as /relayAllocationRequest. The struct names only the signer, so there is no amount and nothing the relayer can vary.
• Only before an allocation lock takes effect: the pool reverts AllocationRequestsLocked afterwards, and a request signed with waiveCancellationRights: true cannot be cancelled once locked.
• Reverts AllocationRequestNotFound when the user has no open request.
• 400 on a stale nonce (re-read /poolNonce and re-sign), a bad signature, or an expired deadline.

// domain — the POOL is the verifying contract
{ "name": "TokenAllocationPool", "version": "1",
  "chainId": <CHAIN_ID>, "verifyingContract": <pool> }
// types
CancelAllocationRequest(address user, uint256 nonce, uint256 deadline)
// message
{ "user": <user>, "nonce": <from /poolNonce>, "deadline": <unix seconds> }
// primaryType: CancelAllocationRequest

// → { "txHash": "0x…", "relayer": "0x…", "pool": "0x…", "user": "0x…" }

POST /relayClaimOfferedTokens

Relay a signed claim of filled offered tokens. Body: { pool, user, nonce, deadline, signature }.

• Only after the pool has been locked, priced and the user's request accepted; reverts NoOfferedTokensToClaim otherwise.
• The pool always transfers to user — the signature carries no recipient, so the relayer cannot redirect the tokens.
• No dust floor applies: a claim the user is already owed stays relayable however small.
• 400 on a stale nonce (re-read /poolNonce and re-sign), a bad signature, or an expired deadline.

// domain — the POOL is the verifying contract
{ "name": "TokenAllocationPool", "version": "1",
  "chainId": <CHAIN_ID>, "verifyingContract": <pool> }
// types
ClaimOfferedTokens(address user, uint256 nonce, uint256 deadline)
// message
{ "user": <user>, "nonce": <from /poolNonce>, "deadline": <unix seconds> }
// primaryType: ClaimOfferedTokens

// → { "txHash": "0x…", "relayer": "0x…", "pool": "0x…", "user": "0x…" }

GET /linkedWallets/:address

Wallets currently linked to an account.

{ "account": "0xabc…", "wallets": ["0xdef…"] }

GET /linkNonce/:account/:wallet

The nonce the next link/unlink signature must carry.

{ "account": "0xabc…", "wallet": "0xdef…", "nonce": 3 }

POST /linkWallet

Link a wallet. Body: { account, wallet, nonce, signature }.

• signature is the wallet's EIP-712 signature over the typed data below. ERC-1271 contract wallets verify too.
• 401 on a bad signature or stale nonce (the current nonce is echoed back), 409 if the wallet is linked elsewhere.

// domain
{ "name": "IPO Leaderboard", "version": "1", "chainId": <CHAIN_ID> }
// types
LinkWallet(address account, address wallet, uint256 nonce)
// message: the lowercased account + wallet and the nonce from /linkNonce

POST /unlinkWallet

Unlink a wallet. Same body and signature scheme as /linkWallet.

• 404 if the wallet is not linked to that account.