Reconcile pool movements

Reconciliation is the production backbone of a 0Pools integration. A user flow is not complete until your system can explain the movement from internal order to quote, trade, terminal status, and ledger entry.

Reconciliation graph

Join keys

State mapping

Webhook handler pattern

1. Verify signature over raw body.
2. Dedupe by event id.
3. Load the trade/order by quote or transact id.
4. Compare event status with current order state.
5. Apply only legal forward state transitions.
6. Store event payload reference and request metadata.
7. Return 2xx quickly.

Example reconciliation table

Anti-patterns

• Reconciling by amount alone.
• Treating browser success as settlement.
• Dropping request ids.
• Overwriting terminal states without audit.
• Logging webhook secrets or secret keys.

Reconciliation close process

Do this as a batch/reporting process as well as in real-time product code. Real-time code keeps users informed; reconciliation proves the records agree after events, retries, and terminal statuses settle.

Example exception types

Before and after

Minimal database shape

{
  "order_id": "order_123",
  "environment": "live",
  "pool_id": "EUR-USDT",
  "quote_id": "pool_quote_123",
  "trade_id": "pool_trade_456",
  "idempotency_key": "order_123:accept:v1",
  "latest_status": "settled",
  "ledger_ref": "pool_trade_456",
  "last_event_id": "evt_789",
  "last_request_id": "req_abc"
}

Store enough to reconstruct the history. A single mutable status column without event and request references is not enough for production finance review.

Finance close artifacts

A finance-grade reconciliation process needs exportable artifacts, not only dashboard state.

Sample exception query

select
  t.transact_id,
  t.quote_id,
  t.status,
  l.ledger_entry_id
from pool_trades t
left join ledger_entries l on l.transact_id = t.transact_id
where t.status in ('settled', 'returned', 'released')
  and l.ledger_entry_id is null;

Close checklist

• Every terminal trade has a ledger entry or approved exception.
• Every ledger entry joins to a trade, quote, and partner order.
• Amounts are compared as exact decimal strings/minor units.
• Webhook gaps are reconciled with trusted status reads.
• Exceptions have owners and next review dates.

Implementation depth

This page is about joining quotes, trades, balances, webhooks, and partner ledger records. For developers, the durable boundary is simple: your product should depend on ids, statuses, event ids, amounts, timestamps, and ledger entries; it should not depend on internal settlement worker details and provider reconciliation files. That boundary is what lets 0Pools improve liquidity operations without forcing every partner to rebuild product code.

Product scenario

At daily close, finance joins partner orders to quote ids, trade ids, terminal events, and balance ledger entries. Anything unmatched becomes an exception with a clear next action.

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": "reconcile-pool-movements",
  "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.