0Pools quickstart

This quickstart is the fastest safe path through 0Pools. It shows the developer flow without pretending 0Pools is self-serve. Before this works in production, the partner must be active, KYC/KYB approved, tiered, allowlisted for pools, and provisioned for funding/webhooks where required.

End-to-end picture

1. Confirm access

No money route works until every gate is open.

Before building the flow, confirm which pools, sides, networks, limits, and funding model are approved for your account.

2. Discover entitled pools

Use discovery as the source of truth for what to display.

curl https://pools-api.0bit.app/v1/pools \
  -H "Authorization: Bearer $OBIT_PUBLISHABLE_OR_SECRET_KEY"

Example response:

{
  "pools": [
    {
      "id": "EUR-USDT",
      "pair": "EUR/USDT",
      "fiatCurrency": "EUR",
      "cryptoCurrency": "USDT",
      "available": true
    }
  ]
}

Do not hard-code pool ids from examples. Entitlements can differ by partner, market, and environment.

3. Read capabilities

Capabilities tell your UI what it can safely show: sides, networks, fees, limits, and optional deposit instructions.

4. Preview with an indicative quote

Indicative quotes let you refresh a price while the user edits. They are not persisted and cannot be executed.

curl -X POST https://pools-api.0bit.app/v1/pools/EUR-USDT/quote \
  -H "Authorization: Bearer $OBIT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "side": "on_ramp",
    "fiatCurrency": "EUR",
    "cryptoCurrency": "USDT",
    "amount": "100.00",
    "type": "indicative"
  }'

5. Lock a firm quote

When the user is ready, request a firm quote. A firm quote is short-lived, single-use, and returns quoteId.

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

For a buy, the destination wallet is locked here. Execution cannot redirect delivery later.

6. Execute once

Execute with an Idempotency-Key. Treat a successful response as reserved, not final settlement.

curl -X POST https://pools-api.0bit.app/v1/pools/EUR-USDT/transact \
  -H "Authorization: Bearer $OBIT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_123_accept_1" \
  -d '{ "quoteId": "pq_test_123" }'

Example acknowledgement:

{
  "transactId": "txn_test_456",
  "status": "reserved",
  "quoteId": "pq_test_123",
  "idempotent": false
}

7. Track status

Poll by quote id or consume terminal webhooks.

curl https://pools-api.0bit.app/v1/pools/transactions/pq_test_123 \
  -H "Authorization: Bearer $OBIT_SECRET_KEY"

8. Reconcile

Your production record should be able to answer: who requested the flow, what pool was quoted, what terms were accepted, which trade was created, what terminal state arrived, and which ledger movement resulted.

{
  "order_id": "order_123",
  "environment": "sandbox",
  "pool_id": "EUR-USDT",
  "quote_id": "pq_test_123",
  "transact_id": "txn_test_456",
  "side": "on_ramp",
  "amount": "100.00",
  "status": "reserved",
  "idempotency_key": "order_123_accept_1",
  "request_id": "req_..."
}

Before and after

Production integration artifacts

A production quickstart should leave the partner backend with one durable lifecycle record. Do not split discovery, quote, execution, status, and reconciliation across disconnected tables.

Minimal server flow

async function acceptPoolQuote(order: PartnerOrder) {
  const idempotencyKey = `${order.id}:accept:${order.acceptVersion}`;

  const quote = await pools.createFirmQuote({
    poolId: order.poolId,
    side: order.side,
    sourceAmount: order.sourceAmount,
    destination: order.destinationRef,
  });

  await db.poolQuotes.insert({
    orderId: order.id,
    quoteId: quote.quoteId,
    expiresAt: quote.expiresAt,
    acceptedTerms: quote,
  });

  const trade = await pools.transact({ quoteId: quote.quoteId }, { idempotencyKey });

  await db.poolTrades.upsert({
    orderId: order.id,
    quoteId: quote.quoteId,
    transactId: trade.transactId,
    status: trade.status,
    idempotencyKey,
  });

  return trade;
}

Acceptance tests before launch

Implementation depth

This page is about launching the first server-side 0Pools flow. For developers, the durable boundary is simple: your product should depend on entitled pools, capabilities, quote ids, trade ids, statuses, and ledger joins; it should not depend on route choice, venue balances, reserve allocation, and treasury movement. That boundary is what lets 0Pools improve liquidity operations without forcing every partner to rebuild product code.

Product scenario

A neobank lets a user buy USDT from EUR inside its own app. The app previews an indicative quote while the user edits the amount, locks a firm quote only on confirmation, executes once from the server, and updates the ledger only from terminal status.

Before and after in practice

System flow

Records to keep

A useful implementation stores these records before adding optional analytics. Analytics can be rebuilt from durable state; missing ids usually cannot be reconstructed after a customer-impacting failure.

Example product record

{
  "product_area": "quickstart",
  "partner_reference": "partner_order_123",
  "pool_id": "EUR-USDT",
  "quote_id": "pq_test_123",
  "transact_id": "pt_test_456",
  "status": "reserved",
  "request_id": "req_01HZY0POOLS",
  "reconciliation_state": "open"
}

This record is intentionally partner-facing. It references 0Pools objects and your own product ids, but it does not include private liquidity routes, treasury balances, raw provider payloads, or customer secrets.

Failure modes and recovery

Use-case patterns

Developer checklist

• Read runtime discovery and capabilities before rendering enabled actions.
• Create firm quotes only when the user is ready to accept the terms.
• Execute from your server with an idempotency key.
• Treat webhooks and status reads as the source of truth for settlement state.
• Reconcile by durable ids first, then by amount and timestamp.
• Do not branch product behavior on provider names, route names, reserve balances, or treasury assumptions.

Next pages