Read 0Pools balance
GET /pools/{id}/balance - Read your partner-visible balance and entitlement view for an entitled pool.
0Pools API pages are for approved headless partners. They cover the partner-visible quote, transact, status, trade, and balance lifecycle only.
Endpoint
| Field | Value |
|---|---|
| Method | GET |
| Path | /pools/{id}/balance |
| Area | Balance |
| Operation id | getBalance |
| Auth boundary | Secret key from your server. |
Use it for
Read the partner-visible balance for an entitled pool, plus the entitlement context you transact within: your provisioned tier and the set of pools you are allowed to use (allowedPools). The available boolean tells you whether the pool is usable. When the balance gate is on, balance is your pre-funded fiat balance (a decimal string) you can reconcile against your own ledger; when the gate is off, balance is null. The endpoint requires your secret key and is partner-scoped; a key scoped to another partner, or an id outside your scope, resolves as 404, never 403.
Use this endpoint only for the partner-scoped resource it describes. Store your own reference id, the returned 0Bit object id, the request id, timestamps, and the current values so support and reconciliation do not depend on browser callbacks alone.
This response carries entitlement context, not access state
The balance response includes your tier and allowedPools, but it deliberately does not echo your access status or KYC state. Those never appear as fields here — they surface only as 403 denial codes (pools_not_enabled, pool_access_suspended, kyc_not_approved, pool_not_allowed, key_mode_mismatch). If a pool is usable, you get a balance; if it is not, you get a 403. Branch on the denial code, not on a missing field.
This is your balance, not a liquidity view
This endpoint reports only your own partner-scoped balance. It does not return any liquidity, depth, venue, or reserve numbers, and there is no venues field. Do not infer market liquidity, routing, or settlement internals from it.
Response fields
| Field | Type | Use |
|---|---|---|
poolId | string | Pool selected by entitlement; join quote, transact, capabilities, and trade records. |
pair | string | Human-readable currency pair for display and reconciliation. Do not parse it for machine logic. |
available | boolean | Whether the pool is usable. Branch on this boolean, not on a numeric value. |
tier | string | Your provisioned tier for the pool. |
allowedPools | string array | The pool ids your key is entitled to. Use it to scope which pools you can quote and transact. |
balance | string | null | Your partner pre-funded fiat balance as a decimal string when the balance gate is on; null when the gate is off. |
When balance is non-null it is the pre-funded fiat balance as a decimal string — keep it as a string and do not convert to floating point for storage or arithmetic. When the balance gate is off, balance is null; treat that as "no pre-funded balance to reconcile" rather than as zero.
Request
curl https://pools-api.0bit.app/v1/pools/EUR-USDT/balance \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Response
{
"poolId": "EUR-USDT",
"pair": "EUR/USDT",
"available": true,
"tier": "standard",
"allowedPools": ["EUR-USDT", "EUR-USDC"],
"balance": "2000.00"
}Values shown are fake placeholders. Read the live response for your account; do not copy these into production configuration.
Where to read networks, fees, and limits
Balance does not describe how a pool can be used. For supported delivery networks, allowed sides, fee and spread ceilings, order-size limits, and your dedicated deposit address, read Read pool capabilities. Treat capabilities as the source of truth and refresh it periodically instead of hard-coding values.
Errors
The API returns a unified error envelope with type, code, message, request_id, doc_url, and statusCode. Every response carries an X-Request-Id header. Branch on code, not on the free-form message.
| Status | type | Notable code values | What it means |
|---|---|---|---|
401 | unauthorized | — | Missing or invalid secret key. Fix credentials before retrying. |
403 | forbidden | pools_not_enabled, pool_access_suspended, kyc_not_approved, pool_not_allowed, key_mode_mismatch | Valid key but access is denied. Branch on the denial code. |
404 | not_found | — | Pool not found or not scoped to your account. Cross-tenant reads return 404. |
429 | rate_limited | — | Throttled. Retry with backoff. |
5xx | server_error | — | Server or upstream failure. Retry bounded with backoff. |
Production rules
- Keep secret keys on your server.
- Branch on the
availableboolean to decide whether the pool is usable, and reconcilebalanceagainst your own ledger (handlingnullwhen the balance gate is off). - Drive entitlement from
allowedPools; read capabilities for networks, fees, and limits instead of hard-coding them. - Treat access and KYC state as
403denial codes, not as fields on this response. - Branch on machine-readable fields, error code, object id, and request id.
- Treat examples and placeholder ids as fake data only.
Public boundary
This reference covers partner-visible discovery, quote, transact, status, trade, and balance behavior. Liquidity operations, routing internals, provider details, reserve logic, and runbooks are outside the public API contract.