Read pool ledger

GET /pools/ledger - List partner-scoped balance movements (credits and debits) for reconciliation.

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/ledger`
Area	Ledger
Operation id	`listLedger`
Auth boundary	Secret key from your server.

Use it for

Read the partner-scoped ledger of balance movements so you can reconcile every change to your pre-funded balance against your own records.

The ledger is the reconciliation source for balance changes. Where the balance endpoint reports the current position, the ledger explains how it got there: each pay-in credit, each buy debit, and each auto-refund from a trade that later flips to returned, appears here as a discrete entry. Reconcile against the ledger rather than inferring movements from balance snapshots alone.

Query parameters

Parameter	Type	Description
`currency`	string	Currency to read. Defaults to `EUR`.
`limit`	number	Page size. Defaults to `50`, clamped to the range `1`–`200`.
`cursor`	string	Opaque cursor for the next page. Omit on the first request; pass the prior `nextCursor` to continue.

Entries are returned newest first.

Response shape

The response is a BalanceLedgerResponse.

Field	Type	Description
`currency`	string	Currency of the ledger.
`available`	string	Current balance as a decimal string.
`entries`	array	Array of `BalanceLedgerEntry`, newest first.
`nextCursor`	string \| null	Cursor for the next page, or `null` when there are no more entries.

Entry shape

Each BalanceLedgerEntry describes one balance movement. The credit/debit signal is the sign of delta together with the reason enum — there is no direction field.

Field	Type	Description
`delta`	decimal string	Signed movement amount: positive for a credit or refund, negative for a debit. Parse with a decimal type; never use floating point.
`reason`	string	One of `payin_credit`, `buy_debit`, or `buy_refund`.
`ref`	string	Idempotency ref. For a credit this is the deposit or credit ref; for a debit or refund it is the `quoteId`. Use it to dedupe.
`balanceAfter`	decimal string	Balance immediately after this movement, as a decimal string.
`createdAt`	string	ISO 8601 timestamp of when the movement was recorded.

Returned trades appear here as a refund

A settled trade can later flip to returned. When it does, the partner balance receives an idempotent auto-refund, recorded as an entry with a positive delta and reason of buy_refund, whose ref is the original quoteId. The returned state itself is surfaced only through the transaction status poll — there is no webhook for it — so the ledger is the durable record of the refund movement.

Example

curl "https://pools-api.0bit.app/v1/pools/ledger?currency=EUR&limit=50" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "currency": "EUR",
  "available": "900.00",
  "entries": [
    {
      "delta": "100.00",
      "reason": "buy_refund",
      "ref": "qt_test_000000000456",
      "balanceAfter": "900.00",
      "createdAt": "2025-01-03T09:30:00.000Z"
    },
    {
      "delta": "-100.00",
      "reason": "buy_debit",
      "ref": "qt_test_000000000456",
      "balanceAfter": "800.00",
      "createdAt": "2025-01-01T12:00:00.000Z"
    },
    {
      "delta": "900.00",
      "reason": "payin_credit",
      "ref": "dep_test_000000000123",
      "balanceAfter": "900.00",
      "createdAt": "2025-01-01T08:00:00.000Z"
    }
  ],
  "nextCursor": null
}

The first entry above is the auto-refund for a trade that flipped to returned; it shares the same ref (the quoteId) as the original buy_debit.

Production rules

Keep secret keys on your server.
Treat the ledger, not balance snapshots, as the source of truth for movements.
Derive credit versus debit from the sign of delta and the reason enum — there is no direction field.
Match each entry to your records by ref; entries are idempotent on ref, so a replayed refund does not double-count.
Parse delta, available, and balanceAfter as decimal strings; never use floating point for money.
Page with cursor: follow nextCursor until it is null.
Treat examples and placeholder ids as fake data only.

Errors

Errors use the unified envelope { type, code, message, request_id, doc_url, statusCode }, and every response carries an X-Request-Id header. Branch on type, code, and statusCode, never on message. See Errors for the full contract.

Status	When
`401`	Missing or invalid secret key.
`403`	`key_mode_mismatch` — wrong key mode. This is a secret-key-only route, so the pool-access denial codes do not apply here.
`404`	The balance gate is off for your account.

The ledger is partner-scoped: it returns only your own movements, and never exposes entries belonging to another partner.

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.

Read pool ledger

On this page