API Reference

SellPolia exposes a small, read-only HTTP API. It’s public and credential-less (no API keys), used by the dApp and available for anyone building dashboards or integrations. All responses are JSON.

There are no write endpoints — you never “submit an order” over HTTP. Selling and buying happen entirely on-chain (deposit to the vault, or call a collector); the backend indexes those events. This API only reads the resulting state.

Conventions

Auth: none. CORS: open.
Rate limit: 120 requests per 60 seconds per client (fixed window). Responses include X-RateLimit-* headers; exceeding it returns 429.
Amounts are returned both human-readable (e.g. "1.5") and as raw base units (the *Raw fields, 18 decimals for SETH/ETH, 8 for USD).
Endpoints that take a chainId query param default to the sell chain (Sepolia) when omitted.

Market & status

GET /api/market

The single source of truth for market configuration: asset & decimals, buyPriceUsd (+Raw), minimumSellSeth (+Raw), sellerTiers (stepSeth + the tier ladder), minPayoutSoldSeth (+Raw), payoutChainId, payoutContract, vaultContract, sellChainId, wallets (owner, SETH sender), the active payments[] (each with name, chainId, collector, accepted tokens), and per-chain chains[] config. Only chains that are actually enabled appear under payments.

GET /api/listener/status

Health of the indexer: the sell-order listener, payment listeners, payout worker, and delivery worker.

GET /health

Liveness probe → { "status": "ok", "service": "backend" }.

Queue & stats

GET /api/queue

Query: chainId. Queue summary — queuedOrderCount, totalQueuedSeth (+Raw), oldestQueuedAt.

GET /api/stats

Query: chainId. Market depth — purchasableSeth (+Raw) (deliverable balance = unsold deposits plus the house reserve), queuedOrderCount, queuedSeth, totalSoldSeth, sellerSoldSeth, paidSoldSeth (with *Raw variants).

Orders

GET /api/queue/orders

Query: chainId, limit (default 50, max 100). The open seller queue as an orders[] array, oldest first.

GET /api/orders/:orderId

A single sell order by id (404 if unknown).

POST /api/buy-orders/quote

Body: { "sethAmount": "10" } (or { "requestedSethRaw": "…" }). Returns requestedSeth (+Raw), costUsd (+Raw), and the split fromQueueSethRaw / fromHouseSethRaw.

costUsd = requestedSeth × buyPrice. The exact native amount for a buy is computed on-chain by the collector’s nativeAmountForSeth() at execution time, not by this endpoint.

GET /api/buy-orders/:orderId

A single buyer order by id (404 if unknown).

Sellers

GET /api/sellers/:address/orders

Query: limit (default 25). A seller’s sell orders, newest first.

GET /api/sellers/:address/balance

A seller’s full pricing + payout state: payoutAddr, priceUsd (+Raw), priceTier, priceTierIndex, sellerFractionBps, lifetime & effective sold amounts, any tier override, minPayoutSoldSethRaw, a balance breakdown (pending / processing / paid — in SETH, USD, and ETH), and the 20 most recent payouts.

Buyers

GET /api/buyers/:address/orders

Query: limit (default 25). A buyer’s orders, newest first.

Ledger

GET /api/ledger

Query: limit (default 100, max 200), types (comma-separated filter). A unified activity feed. Entry types:

Type	Meaning
`buy`	A buy was filled.
`sell_order_created`	A seller deposit entered the queue.
`seller_payout`	A payout was released.
`house_fill`	A buy was filled from the reserve.