Pools API

The Pools API is the headless liquidity surface for approved partners. Because 0Pools is partner-gated and liquidity-sensitive, the docs stay at the safe lifecycle level: discover entitled pools, read pool capabilities, request a short-lived quote, accept or reject it, transact once, poll or retrieve status, and reconcile partner-visible records.

This page deliberately does not publish treasury balances, provider names, reserve allocation, market-maker terms, routing strategy, bank rails, rebalancing thresholds, or internal risk controls.

What this page covers

• The safe Pools API lifecycle, end to end.
• Which calls use publishable keys and which require secret keys.
• Quote (firm vs indicative), transact, reject, status, trade, capabilities, funding, balance, and ledger behavior.
• Idempotency, HTTP status handling, velocity limits, and reconciliation rules.
• What must stay out of browser code, customer-facing UI, and support artifacts.

Value types

Endpoint map

Lifecycle

The important production rule is that a firm quote is short-lived and single-use. Do not let the browser create or execute it directly. Your server should request the quote, store the quote id and expiry, show the user only the partner-visible economics, and execute once if the user accepts before expiry.

Trade status lifecycle

A trade moves through PoolTxnStatus values. Polling the status by quote id is the intended, idempotent way to advance a reserved transaction toward a terminal state.

Discovery

GET /pools returns the pools the partner is entitled to, including an availability signal. Treat that signal as current state, not a promise that every future quote will be available.

curl -X GET https://pools-api.0bit.app/v1/pools \
  -H "Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Use discovery to populate UI choices, cache lightly, and hide unavailable pools. Do not expose internal route details or fallback providers.

Capabilities

GET /pools/{id}/capabilities is self-describing. Read it instead of hard-coding networks, sides, fees, or order limits — these are configured per partner and per pool and can change.

curl -X GET https://pools-api.0bit.app/v1/pools/EUR-USDT/capabilities \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Quote

POST /pools/{id}/quote prices a specific conversion. A firm quote (the default) locks a short time-to-live quote when the route is available; an indicative quote is price-only.

curl -X POST https://pools-api.0bit.app/v1/pools/EUR-USDT/quote \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "side": "on_ramp",
    "fiatCurrency": "EUR",
    "cryptoCurrency": "USDT",
    "amount": "100.00",
    "type": "firm",
    "cryptoNetwork": "tron",
    "destAddress": "0xAbC0000000000000000000000000000000000123",
    "destNetwork": "arbitrum"
  }'

type selects the quote kind (firm or indicative, default firm). cryptoNetwork selects the crypto network for the quote (tron, ethereum, bsc, polygon, or solana, default tron); the on-ramp delivery network is set separately by destNetwork from the EVM-only allowlist.

Amount semantics. For on_ramp, amount is the fiat you pay in and the quoted rate (output-per-input) describes the crypto you receive. For off_ramp, amount is the crypto you sell and the quoted rate describes the fiat you receive. rate is always output-per-input; derive the opposite leg from amount × rate.

On-ramp delivery

For a buy (on_ramp), destAddress is required and is captured and locked at quote time — validated as an EVM 0x address (a mixed-case address must pass an EIP-55 checksum; all-lowercase or all-uppercase addresses pass on format), restricted to the EVM-only network allowlist. The address is copied onto the trade from the quote at transact (never re-read from the transact body) and delivered on settle. A missing destAddress on an on_ramp quote returns 400.

Delivery networks are EVM-only — for example, USDT on Arbitrum. Read the exact set from supportedNetworks in /capabilities rather than hard-coding it. The customer needs only an EVM wallet address; no wallet on any other chain is required.

Accept or reject

If the user accepts, call POST /pools/{id}/transact with the quote id from your server.

curl -X POST https://pools-api.0bit.app/v1/pools/EUR-USDT/transact \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000123" \
  -d '{
    "quoteId": "quote_test_123"
  }'

A successful transact returns the reserved trade (transactId, quoteId, status: reserved, …); poll to progress it. Transact can fail with 402 (insufficient balance to reserve), 409 (quote expired, already consumed, or reservation failed), or 501 (off-ramp not enabled for this partner, pool, or environment — see below).

If the user declines, call POST /pools/quotes/{quoteId}/reject. Rejecting is money-free and sets the quote's status to rejected — a distinct terminal state from consumed, so a rejected quote can never be transacted. If a quote is already consumed, rejected, or expired, refresh state and branch instead of retrying blindly.

Off-ramp (sell)

off_ramp is account-gated. It deny-closes with HTTP 501 unless explicitly enabled for the partner, pool, and environment. When enabled, off-ramp requires a crypto-receipt gate: the partner first sends the crypto leg to its dedicated per-partner deposit address from cryptoDepositAddress in /capabilities; 0Pools credits the partner-scoped crypto balance; only then can a sell trade debit that balance and move toward fiat payout. Do not retry a 501 in a loop — request enablement through account review.

Funding

GET /pools/funding returns your dedicated deposit instructions for the pre-funded fiat balance that backs on-ramp orders (EUR-only).

curl -X GET https://pools-api.0bit.app/v1/pools/funding \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

If the balance gate is off for the partner, this returns 404. If funding is enabled but not yet provisioned, iban is null with an operations note — wait for provisioning rather than retrying in a loop.

Status and reconciliation

Use read endpoints to join the quote to the resulting trade, balance, and ledger.

GET /pools/trades uses cursor pagination: pass ?cursor=<last transactId>; the response is { data[], nextCursor, hasMore } with nextCursor null when exhausted. limit is 1–100 (default 50). Filter with side, status, created_after, and created_before.

The balance view returns { poolId, pair, available, tier, allowedPools, balance } with money as decimal strings. It deliberately does not echo access or KYC state (those surface only as 403 denial codes) and exposes no venue or external numbers.

Support and operations should be able to answer: which pool was selected, which quote was shown, whether it expired or was rejected, whether a trade was created, what status it reached, whether it later returned, and which request ids belong to the workflow.

HTTP status handling

Every response carries an X-Request-Id header (mirroring request_id in the unified error envelope { type, code, message, request_id, doc_url, statusCode }). Branch on statusCode, type, and code — never on the free-form message.

Rate limits

Ordinary throttling is applied per client IP. Separately, an optional per-partner rolling 24-hour notional velocity cap can return 429 at transact when exceeded; idempotent retries are excluded so they are not double-counted. The velocity cap is off by default and configured per partner. Per-order minimum and maximum (minOrderUsdt / maxOrderUsdt) come from /capabilities.

Error and retry guidance

Public documentation boundary

Public docs may describe:

• Entitled pool discovery and capabilities.
• Quote request (firm and indicative) and partner-visible quote fields.
• Accept/reject behavior and derived quote status.
• Trade status, the returned auto-refund, and partner-scoped reads.
• Funding instructions, balance, and ledger for reconciliation.
• Fee and spread fields only where approved.

Public docs must not describe:

• Treasury balances or reserve allocation.
• Liquidity-provider or settlement-provider identities and bank rails.
• Internal routing or rebalancing logic and thresholds.
• Provider contracts or market-maker terms.
• Operational runbooks.
• Risk controls beyond partner-facing status/error guidance.

Related pages