0Pools operations

0Pools is the headless liquidity surface for approved partners. This page is the operations narrative that ties the endpoints together; each endpoint has its own reference page with the full request and response shape. These docs stay at the partner-safe lifecycle level and never expose provider, treasury, reserve, bank, routing, or risk-control internals.

Authentication

Every key is partner-scoped. A request for a resource that belongs to another partner resolves as 404, never 403 — cross-tenant access is indistinguishable from "not found". Money and rate values are decimal strings; bps values are integers.

Endpoint map

Lifecycle

The production rule: a quote is short-lived and single-use. Your server requests the quote, stores the quote id and expiry, shows the user only the partner-visible economics, and transacts once if the user accepts before expiry. The browser never holds a secret key or creates a quote.

Discover and describe

Start with discovery and read the pool's own description instead of hard-coding networks, fees, or limits.

• GET /pools (pk_*) returns { pools: [...] }, where each pool has id, pair, fiatCurrency, cryptoCurrency, and available (a boolean). Treat availability as current state, not a promise.
• GET /pools/{id}/capabilities (sk_*) is self-describing: supportedNetworks, sides, tier, drawFeeBps, spreadCapBps, minOrderUsdt, maxOrderUsdt, and your dedicated cryptoDepositAddress. Read this rather than assuming order limits or supported networks.

See List entitled 0Pools and Read pool capabilities.

Quote

POST /pools/{id}/quote prices a conversion. Choose type:

• firm (default) locks a short-TTL (~15s), single-use quote and returns a quoteId, rate, spreadBps, feeBps, expiresAt, and executable: true. Only a firm quote can be transacted.
• indicative returns price-only economics with executable: false and no quoteId. It is not persisted and cannot be transacted.

When pricing is unavailable, the call fails soft: HTTP 200 with { "available": false, "unavailableReason": "pool_dry" | "engine_unavailable" | "rate_unavailable" } and no quoteId. Never attempt to transact without a quoteId.

The amount is a decimal string whose meaning depends on side:

For an on_ramp (buy), destAddress is required (optional destNetwork) and is captured and locked at quote time — a missing destAddress on an on_ramp returns 400. See Create a 0Pools quote and the Quotes and pricing guide.

curl -X POST https://pools-api.0bit.app/v1/pools/pool_test_123/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",
    "destAddress": "0x1111111111111111111111111111111111111111",
    "destNetwork": "arbitrum"
  }'

Transact

POST /pools/{id}/transact executes a firm quote. The body carries only the quoteId; side, amounts, rate, and the on-ramp delivery address all come from the locked quote, never the body.

curl -X POST https://pools-api.0bit.app/v1/pools/pool_test_123/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 call reserves the trade and returns { transactId, quoteId, status: "reserved", ... }. A reserved trade is not final — poll to progress it. See Execute against a 0Pools quote.

If the user declines, call POST /pools/quotes/{quoteId}/reject. Rejecting is money-free and sets the quote to rejected, a state distinct from consumed. Reject is not idempotent: a second reject of an already consumed, rejected, or expired quote returns 409.

Poll to a terminal state

GET /pools/transactions/{quoteId} is the intended, idempotent way to advance a reserved trade. Each poll moves it toward a terminal state.

See Get 0Pools transaction status and 0Pools webhooks.

Funding, balance, and ledger

0Pools trades draw from a pre-funded partner balance. These reads let you fund, check headroom, and reconcile.

• GET /pools/funding returns your dedicated runtime deposit instructions for the pre-funded fiat balance — { currency, iban, reference, instructions }. Funding is EUR-only: the optional ?currency defaults to EUR, and any non-EUR currency returns 400. It returns 404 when the balance gate is off, and iban: null with an ops note when not yet provisioned. See Get pool funding.
• GET /pools/{id}/balance returns { poolId, pair, available, tier, allowedPools, balance }, where available is a boolean, allowedPools is a string array, and balance is the partner pre-funded fiat balance as a decimal string (or null when the balance gate is off); poolId, pair, and tier are plain strings. Access and KYC states are not echoed here — they surface only as 403 denial codes. See Read 0Pools balance.
• GET /pools/ledger lists partner-scoped credits and debits for reconciliation. Use it alongside transactId/quoteId to tie balance movements to trades. See Read pool ledger.

List trades with GET /pools/trades for support and reconciliation: cursor pagination (?cursor=<last transactId>, response { data, nextCursor, hasMore }, limit 1–100 default 50) with side, status, created_after, and created_before filters.

Delivery and sides

Errors and limits

Errors use a unified envelope { type, code, message, request_id, doc_url, statusCode }, and every response carries an X-Request-Id header. Branch on the machine-readable code.

Order size limits come from minOrderUsdt/maxOrderUsdt on /pools/{id}/capabilities. See Errors.

Public boundary

This reference covers partner-visible discovery, quote, transact, status, trade, balance, funding, and ledger behavior. Liquidity operations, routing internals, provider and bank details, reserve logic, rebalancing thresholds, and operator runbooks are outside the public API contract and must stay out of browser code and customer-facing UI.

Related pages