Top-up and rebalancing
How to explain 0Pools availability and balance behavior without exposing private treasury top-up or rebalancing mechanics.
Shared liquidity needs maintenance. Pools can become imbalanced, venue balances can move, fiat and crypto can settle on different clocks, and operational workers may need to reconcile or refill. 0Pools hides those internal mechanics behind partner-safe availability and status signals.
Conceptual model
What partners see
| Internal condition | Partner-visible expression |
|---|---|
| Pool is healthy. | Pool available; quote can be issued. |
| Pool depth is low. | available: false or wider approved quote terms. |
| Pricing source unavailable. | rate_unavailable or engine_unavailable. |
| Balance gate lacks funds. | Insufficient balance. |
| Settlement needs review. | Pending, failed, released, or returned state. |
What partners should not see
Do not surface:
- Treasury wallet balances.
- Rebalancing thresholds.
- Venue refill instructions.
- Internal reserve ratios.
- Worker names or cron schedules.
- Private "why" strings from operator runbooks.
UX guidance
Use state-based messaging:
| State | Message |
|---|---|
| Quote unavailable | "This route is unavailable right now." |
| Quote expired | "Refresh for a new price." |
| Balance insufficient | "Top up your balance before transacting." |
| Reserved too long | "Settlement is pending. Contact support with the trade id." |
Why it matters
Before 0Pools, rebalancing was often a product concern: teams had to know which account was dry and manually steer users away. With 0Pools, products consume availability and quote outcomes while the liquidity network handles internal maintenance.
Public operating model
Think of top-up and rebalancing as private maintenance behind a public availability surface:
Partners can react to available, unavailable, reserved, settled, failed, released, and returned. They should not react to raw inventory ratios, refill instructions, route names, or provider names.
Example state transitions
| Scenario | Public signal | Partner behavior |
|---|---|---|
| Demand temporarily exceeds approved pool availability. | Quote unavailable or amount rejected. | Ask the user to try later, reduce amount, or choose another entitled pool. |
| User accepts a quote, but final movement is still in progress. | Trade remains reserved or processing. | Keep the user ledger pending and monitor age. |
| Internal maintenance restores availability. | New quotes become available. | Let users request fresh quotes; do not execute old expired quotes. |
| Partner prefunded balance is too low. | Insufficient balance or funding prompt. | Top up through the approved funding flow before accepting more orders. |
Before and after for operations
| Before 0Pools | With 0Pools |
|---|---|
| Product teams hard-code operational workarounds for thin inventory. | Product teams consume a stable availability and quote result. |
| Rebalancing thresholds leak into support or dashboards. | Dashboards show partner-safe states and ids. |
| Users see confusing provider-specific errors. | Users see a route unavailable, pending, or retry state. |
| Engineering changes are needed for every liquidity maintenance change. | Internal pool maintenance can change without changing partner code. |
Developer checklist
- Cache discovery lightly, but re-check availability before user confirmation.
- Treat firm quote expiry as absolute.
- Never execute an expired quote as a rebalancing workaround.
- Store unavailable reasons for analytics, but show user-safe copy.
- Keep internal runbook names out of logs that support agents or partners can see.
- Escalate repeated unavailable outcomes with request ids, not private route guesses.
Partner-visible balance health
Top-up and rebalancing should appear to partners as availability and balance signals, not operational instructions.
| Signal | Partner behavior | Example UI/ops action |
|---|---|---|
| Balance available | Allow eligible quotes under limits. | Show normal buy/sell action. |
| Balance below threshold | Continue only if quotes still available. | Alert finance to top up partner balance. |
| Pool temporarily unavailable | Disable new quote action. | Show retry-later copy. |
| Reserved exposure rising | Monitor age of reserved trades. | Alert operations if terminal status is delayed. |
Finance top-up runbook
{
"partner_balance_id": "bal_partner_eur",
"asset": "EUR",
"visible_balance": "50000.00",
"reserved_amount": "12000.00",
"available_for_new_quotes": "38000.00",
"recommended_action": "review_top_up_before_daily_peak"
}Do not build against
- Source-specific refill instructions.
- Reserve account names.
- Provider-specific inventory labels.
- Private rebalancing thresholds.
- Manual operator notes as product state.
Implementation depth
This page is about representing liquidity health without exposing private top-up or rebalancing mechanics. For developers, the durable boundary is simple: your product should depend on availability, balance state, limits, and temporary unavailable states; it should not depend on thresholds, sweep logic, treasury refill, and inventory targets. That boundary is what lets 0Pools improve liquidity operations without forcing every partner to rebuild product code.
Product scenario
A pool becomes unavailable because the underlying liquidity network is being replenished. The partner product should disable new firm quotes and keep existing trades tracked by status.
Before and after in practice
| Before 0Pools | With 0Pools |
|---|---|
| Product teams treat rebalancing as a customer-visible explanation and expose operational details. | Products show availability and retry guidance while 0Pools manages private inventory operations. |
| 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 |
|---|---|---|
availability_state | What the product can show. | temporarily_unavailable |
last_successful_quote | Helps support compare behavior. | pq_test_123 |
limit_context | Amount bounds that reduce pressure. | maxOrderUsdt |
reopened_at | When your product saw the lane recover. | 2026-06-28T... |
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": "top-up-rebalancing-boundaries",
"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 |
|---|---|
| Inventory threshold exposed | Use availability language only. |
| Infinite quote retry | Back off and refresh. |
| Existing trade ignored | Continue polling reserved trades. |
| Manual promise made | Do not promise timing beyond the product state. |
Use-case patterns
| Pattern | How 0Pools helps |
|---|---|
| High-volume app | Protect users during liquidity pressure. |
| Support page | Explain temporary unavailability. |
| Partner dashboard | Track availability without private balances. |
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.