Retrieve a 0Pools trade
GET /pools/trades/{transactId} - Retrieve one partner-scoped trade.
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/trades/{transactId} |
| Area | Trades |
| Operation id | getTrade |
| Auth boundary | Secret key from your server. |
Use it for
Retrieve one partner-scoped trade by its transactId. This is a pure, read-only lookup of a single trade record: it returns the latest persisted state of the trade and nothing else.
Use it for support lookups, reconciliation, and audit trails where you already hold a transactId and want the current snapshot of a known trade.
This read does not advance settlement
GET /pools/trades/{transactId} is a passive read. It never moves a reserved trade forward and never triggers
delivery or payout. To drive a reserved trade toward a terminal state, poll GET /pools/transactions/{quoteId},
which is the intended, idempotent way to progress settlement. Use this trade read for snapshots and reconciliation,
not as the engine that completes a trade.
Read versus poll
Both endpoints return the same trade fields, but they do different work. Choose by intent.
| Concern | GET /pools/trades/{transactId} | GET /pools/transactions/{quoteId} |
|---|---|---|
| Lookup key | transactId | quoteId |
| Advances settlement | No (pure read) | Yes (idempotent progression) |
| Typical use | Support, audit, reconciliation snapshots | Driving a reserved trade to a terminal state |
| Safe to call often | Yes | Yes (idempotent), and use it to make progress |
Request
curl -X GET https://pools-api.0bit.app/v1/pools/trades/txn_test_0000000000abc \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"| Parameter | In | Required | Description |
|---|---|---|---|
transactId | path | Yes | The trade id returned by POST /pools/{id}/transact. |
The secret key scopes the lookup to your partner. A transactId that belongs to another partner is treated as not found; see Errors.
Trade fields
The response is a single trade object. Money and rate values are decimal strings; basis-point values are integers.
| Field | Type | Description |
|---|---|---|
transactId | string | Stable id of this trade. Use it to join your records. |
quoteId | string | The quote this trade was executed against. Use it to poll status and link back to the quote. |
poolId | string | The pool this trade ran against (pair-shaped, for example EUR-USDT). |
pair | string | The pool's trading pair, for example EUR-USDT. |
side | string | on_ramp (fiat in, crypto delivered) or off_ramp (crypto in, fiat paid out). |
status | string | Current lifecycle state. See Trade status. |
fiatCurrency | string | Fiat currency of the trade, for example EUR. |
cryptoCurrency | string | Crypto asset of the trade, for example USDT. |
cryptoNetwork | string | The chain the trade transacted on, locked on the quote: tron, ethereum, bsc, polygon, or solana. |
fiatAmount | decimal string | Fiat leg of the trade (paid in for on_ramp, received for off_ramp). |
cryptoAmount | decimal string | Crypto leg of the trade (delivered for on_ramp, sold for off_ramp). |
quotedRate | decimal string | The all-in quoted rate locked from the quote (rate direction is unspecified). |
spreadBps | integer | Spread component, in basis points. |
feeBps | integer | Fee component, in basis points. |
totalBps | integer | Total cost in basis points, equal to spreadBps + feeBps. |
engineFillTxId | string | null | Settlement fill reference for the trade; null until the trade has filled. |
createdAt | string (ISO 8601) | When the trade was created (at transact). |
settledAt | string (ISO 8601) | null | When the trade reached settled; null until then. |
Treat money as strings
Never parse fiatAmount, cryptoAmount, or quotedRate as floating-point numbers. Keep them as decimal strings
through your pipeline to avoid rounding drift, and branch logic on status, feeBps, and spreadBps.
Trade status
status | Meaning |
|---|---|
quoted | A quote exists; no reservation has been made yet. |
reserved | The trade was created at transact and is awaiting settlement. Poll the transactions endpoint to progress it. |
settled | The trade completed; the delivery or payout leg was carried out. settledAt is populated. |
failed | The trade did not complete. Inspect status and reconcile. |
released | The reservation was released without settling. |
returned | A previously settled trade was later reversed (for example, a payout returned by the receiving bank, or a delivery that failed downstream). An idempotent auto-refund returns the amount to your partner balance. Monitor for this flip via the status poll, GET /pools/transactions/{quoteId}. |
Monitor a returned flip via the status poll
A settled trade can later flip to returned. There is no webhook for returned; the canonical way to watch for it
is the status poll, GET /pools/transactions/{quoteId}, together with your partner ledger (the auto-refund posts with
reason buy_refund). This trade read merely reflects whatever the current status is, so it will show returned once
set, but it is not where you watch for the flip. If you depend on terminal webhooks alone, you will miss a returned
flip, so reconcile periodically against the status poll and ledger.
Example response
{
"transactId": "txn_test_0000000000abc",
"quoteId": "quote_test_0000000000xyz",
"poolId": "EUR-USDT",
"pair": "EUR-USDT",
"side": "on_ramp",
"status": "settled",
"fiatCurrency": "EUR",
"cryptoCurrency": "USDT",
"cryptoNetwork": "tron",
"fiatAmount": "100.00",
"cryptoAmount": "107.412300",
"quotedRate": "1.0741230",
"spreadBps": 40,
"feeBps": 25,
"totalBps": 65,
"engineFillTxId": "fill_test_0000000000def",
"createdAt": "2026-01-15T10:32:04.000Z",
"settledAt": "2026-01-15T10:33:11.000Z"
}Every response also carries an X-Request-Id header that mirrors the request_id in error bodies. Capture it for support.
Errors
Errors use the unified envelope { type, code, message, request_id, doc_url, statusCode }. Branch on code and statusCode, never on the free-form message.
| Status | type | When | What to do |
|---|---|---|---|
401 | unauthorized | Missing or invalid secret key. | Fix credentials; do not retry unchanged. |
403 | forbidden | Wrong key mode for this secret-only route (key_mode_mismatch); for example a pk_* publishable key. This read runs no entitlement check, so the pool-access denial codes do not apply here. | Call with your secret key; do not retry unchanged. |
404 | not_found | Unknown transactId, or a trade owned by another partner. | Check the id; never surface foreign ids. Cross-tenant lookups return 404, not 403. |
429 | rate_limited | Throttle limit reached. | Back off and retry. |
5xx | server_error | Server or upstream failure. | Retry with bounded backoff. |
Cross-tenant reads return 404
A transactId outside your partner scope returns 404, not 403. The API never confirms the existence of objects you
do not own. Do not infer ownership from the status, and do not log or surface foreign ids.
Production rules
- Keep secret keys on your server.
- Use this endpoint for snapshots and reconciliation; use the transactions poll to advance a
reservedtrade. - Store your own reference id, the
transactId, thequoteId, therequest_id, the currentstatus, and timestamps. - Branch on machine-readable
status, errorcode, object id, and request id. - Reconcile periodically against the status poll and your ledger to catch a
returnedflip, which has no webhook. - 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.