Partner-visible balances
How prefunded balances, funding instructions, ledger entries, debits, refunds, and returns fit into 0Pools.
Some 0Pools programs run on a prefunded model: the partner funds a balance first, then draws liquidity. This prevents a partner from receiving crypto delivery before fiat funding is actually available.
Balance lifecycle
Funding instructions
Funding instructions usually include:
| Field | Why it matters |
|---|---|
currency | Balance currency. |
iban or funding destination | Where the partner sends funds when enabled. |
reference | The mandatory payment reference used to attribute funds. |
instructions | Human-safe top-up guidance. |
If a payment reference is missing or wrong, attribution may require operator review.
Ledger entries
Ledger entries are the finance trail.
| Reason | Meaning |
|---|---|
payin_credit | Funds credited to partner balance. |
buy_debit | Balance debited for an on-ramp buy. |
buy_refund | Debit refunded because the trade failed or released. |
| Return-related entries | Downstream return or correction to reconcile. |
Integration rule
Your app should not trust a button click or a quote alone as evidence of money movement. Join:
- Funding reference.
- Balance ledger entry.
- Quote id.
- Trade id.
- Terminal status.
- Your internal order id.
Example reconciliation row
{
"partner_order_id": "order_123",
"pool_id": "EUR-USDT",
"quote_id": "pq_test_123",
"transact_id": "txn_test_456",
"balance_delta": "-100.00",
"ledger_ref": "pq_test_123",
"trade_status": "reserved"
}What not to infer
Partner-visible balance is not total 0Bit treasury. It is not venue liquidity. It is not proof that every pool can execute every amount. It is a partner-scoped reconciliation view.
Balance accounting model
The balance model exists to prevent credit risk and support reconciliation. It should not be presented as a live view into all 0Bit reserves. A partner balance answers: "How much of this partner's funded program can be used or reconciled?"
Before and after
| Before 0Pools | With partner-visible balances |
|---|---|
| Partners asked support whether treasury had enough funds. | Partners can see their own funding, debits, and releases where enabled. |
| Product code accepted orders before funding was actually available. | Prefunded programs can block execution when balance is insufficient. |
| Finance reconciled pay-ins and crypto delivery separately. | Funding reference, quote id, trade id, and ledger entries join the record. |
| Refunds/releases required manual spreadsheet matching. | Released or failed trades can attach to balance ledger movements. |
Example ledger sequence
| Time | Entry | Delta | Balance | Meaning |
|---|---|---|---|---|
| 09:00 | payin_credit | +1000.00 | 1000.00 | Partner top-up attributed by reference. |
| 09:15 | buy_debit | -100.00 | 900.00 | Accepted on-ramp trade reserved/debited. |
| 09:17 | buy_refund | +100.00 | 1000.00 | Trade failed or released before settlement. |
| 10:05 | buy_debit | -250.00 | 750.00 | Later trade settles and debit remains. |
Use decimal strings in API and ledger records. Do not convert money values through floating-point math.
Product behavior rules
- Block or pause new executions when the partner balance is insufficient.
- Show balance prompts to partner admins, not end users, unless the partner product owns that UX.
- Keep quote creation separate from balance debit.
- Treat reserved/debited balances as pending until the trade reaches an approved terminal state.
- Reconcile returned or failed movements before closing finance reports.
Support packet for balance issues
{
"partner_id": "partner_123",
"pool_id": "EUR-USDT",
"funding_reference": "REF-partner_123",
"ledger_entry_id": "ple_789",
"quote_id": "pool_quote_123",
"trade_id": "pool_trade_456",
"balance_delta": "-100.00",
"request_id": "req_abc"
}Balance lifecycle accounting
Partner-visible balances should be auditable from funding through trade reservation, settlement, release, return, and close.
| Balance event | Ledger effect | User/product effect |
|---|---|---|
| Funding received | Credit partner prefunded balance. | New quote capacity may become available. |
| Firm quote created | No ledger movement unless explicitly reserved by product design. | User sees expiry. |
| Trade reserved | Reserve or debit available balance depending on returned model. | User sees pending. |
| Trade settled | Final debit/credit is posted. | User sees completed movement. |
| Trade released | Reservation unwinds. | User can retry with fresh quote. |
| Trade returned | Return/refund path is posted. | User sees returned or failed state. |
Ledger sequence example
[
{ "type": "funding_credit", "asset": "EUR", "amount": "50000.00", "balance_after": "50000.00" },
{ "type": "trade_reserve", "trade_id": "pt_live_9A2", "asset": "EUR", "amount": "100.00", "balance_after": "49900.00" },
{ "type": "trade_settle", "trade_id": "pt_live_9A2", "asset": "USDT", "amount": "107.42", "balance_after": "settled" }
]Reconciliation rule
Never reconcile only from current balance. Reconcile from immutable balance movements with ids, timestamps, asset, amount, and trade linkage.
Implementation depth
This page is about using balances and ledger entries safely in prefunded flows. For developers, the durable boundary is simple: your product should depend on partner balance, funding credit, trade debit, refund, return, and ledger reference; it should not depend on bank account internals, treasury accounts, and attribution operations. That boundary is what lets 0Pools improve liquidity operations without forcing every partner to rebuild product code.
Product scenario
A partner wires fiat before users buy stablecoin. The product credits available balance only after confirmation, debits it when a trade reserves, and posts a refund or return entry when the flow unwinds.
Before and after in practice
| Before 0Pools | With 0Pools |
|---|---|
| A spreadsheet tracks deposits and order debits separately, so support cannot prove remaining balance after failures. | Every credit, debit, refund, and return is an immutable partner-visible ledger entry. |
| Product teams infer liquidity behavior from provider-specific screens or manual notes. | Product teams branch on 0Pools objects: pool, quote, trade, balance, webhook, and ledger. |
| Support asks engineering to reconstruct state from logs. | Support starts from request id, quote id, trade id, event id, and ledger id. |
System flow
Records to keep
| Record | Why it matters | Example |
|---|---|---|
ledger_entry_type | Explains the movement. | payin_credit |
amount | Decimal string amount. | 1000.00 |
currency | Balance currency. | EUR |
related_trade_id | Trade that consumed or restored balance. | pt_test_456 |
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": "partner-visible-balances",
"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
| Failure mode | Product response |
|---|---|
| Credit before confirmation | Wait for confirmed funding state. |
| Debit without trade id | Block ledger posting until trade reference exists. |
| Refund not linked | Tie refunds to the original debit. |
| Balance shown as treasury | Show partner balance only. |
Use-case patterns
| Pattern | How 0Pools helps |
|---|---|
| Prefunded wallet | Draw down a partner balance. |
| Finance export | List ledger entries by day. |
| Support investigation | Explain why balance decreased. |
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.