IPO Leaderboard API

GET /health

Service health plus latest-snapshot metadata.

• ok stays true while a ranking input is degraded — the queue is still served; check inputs.<name>.degraded instead. Inputs: arcusVolume, ammVolume, points, holdings.
• final is true once the latest snapshot is safe to allocate from: past the lock, every input refreshed after it, nothing pending.
• 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,
  "inputs": {
    "arcusVolume": { "enabled": true, "degraded": false, "fetchedAt": 1756677000 },
    "ammVolume": { "enabled": true, "degraded": false, "fetchedAt": 1756677000 },
    "points": { "enabled": true, "degraded": false, "fetchedAt": 1756677000 },
    "holdings": { "enabled": true, "degraded": false, "fetchedAt": 1756677000 } },
  "final": 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.
• bonusPending: true marks a new depositor ranked on deposits alone while their trading, holdings and points are fetched; it clears within seconds.
• 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, "bonusPending": false }, … ] }

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, "bonusPending": false }

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 token the deposit pulls (the pool's quote token, or USDG for a Paxos pool), 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.
• A pool whose quoteToken() is the Paxos wrapped token deposits through the Paxos deposit adapter instead: spender is that adapter, token is the underlying (USDG) it wraps 1:1, any folded permit approves USDG, and the witness struct is named TokenAllocationPaxosDeposit (same fields). Every other pool pulls its own quoteToken() through the Permit2 adapter.
• 200 means broadcast, not mined — txHash is real but pending (permitTxHash too, when a permit was folded). 400 is a bad request (code says which); 202 with permitTxHash means only the folded permit was sent: wait for its receipt (up to ~10s), then resend the same request. Don't send a fresh deposit before the signature's deadline: both can land.

// 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.
• A pool whose quoteToken() is the Paxos wrapped token is signed the same way and pays recipient USDG: the pool unwraps through its withdrawal unwrapper. recipient cannot be the pool or its unwrapper.
• 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.
• 403 when this deployment has withdrawals turned off.

// 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, newQuoteAmount, maxPriceUsd, slippageBps, waiveCancellationRights, expectedQuoteAmount, 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; newQuoteAmount cannot exceed their deposit.
• expectedQuoteAmount is the request being replaced: 0 for a first request, otherwise allocationRequests(user).quoteAmount read just before signing. 400 allocation_state_stale if it has changed since: regenerate the request form from fresh state and have the user confirm before re-signing.
• maxPriceUsd is USD per whole offered token in 1e18 fixed point, and cannot be below finalPriceUsd() once that is set; slippageBps caps the discount from the oracle-implied amount (at most the pool's maxSlippageBps()).
• 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 newQuoteAmount, uint256 maxPriceUsd, uint256 slippageBps, bool waiveCancellationRights, uint256 expectedQuoteAmount, uint256 nonce, uint256 deadline)
// message
{ "user": <user>, "newQuoteAmount": <newQuoteAmount>, "maxPriceUsd": <1e18 USD>,
  "slippageBps": <bps>, "waiveCancellationRights": <bool>,
  "expectedQuoteAmount": <current request, 0 if none>,
  "nonce": <from /poolNonce>, "deadline": <unix seconds> }
// primaryType: AllocationRequest

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

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.