API reference
Explore 0Bit API groups, authentication, request and response boundaries, idempotency, errors, webhooks, status lifecycles, and production notes.
The 0Bit API reference is organized by product surface and availability boundary. The published partner API pages currently cover 0Gate and 0Pools. 0Base and 0Link product documentation remains available, but their endpoint-level partner API pages are not published until those products are ready for partner API access.
Use this page as the product-safe overview. Operation pages and product guides can go deeper, but they should keep the same rules: keep secrets server-side, use idempotency keys for writes, verify webhooks, branch on machine-readable error fields, and avoid unsupported live availability claims.
Generated 0Gate reference
The generated Scalar reference is wired to the current gate-v1.yaml OpenAPI contract copied from the 0Gate source
repo. Open it at Scalar 0Gate API. This generated view covers 0Gate only; it
does not enable 0Pools, 0Base, or 0Link endpoint-level access for every account.
What this page covers
- API group boundaries by product.
- Authentication and key placement.
- Documented endpoint groups.
- Request/response and idempotency conventions.
- Error, retry, webhook, pagination, and production readiness behavior.
- Which areas are public, partner-gated, review-only, or account-gated.
API group overview
| Area | Purpose | Common operations |
|---|---|---|
| 0Gate sessions | Create, retrieve, list, and cancel hosted payment sessions. | POST /gate_sessions, GET /gate_sessions/{id}, POST /gate_sessions/{id}/cancel. |
| 0Gate embed | Bootstrap hosted browser experiences. | POST /embed/bootstrap using publishable key and session client_secret. |
| 0Gate capabilities | Discover configured countries, fiat currencies, assets, payment methods, payout methods, and eligibility where approved. | GET /capabilities/*. |
| 0Gate transactions | List and retrieve partner transaction records. | GET /transactions, GET /transactions/{refid}. |
| 0Gate webhooks | Inspect delivery logs, replay dead-lettered deliveries, and send test events where supported. | Webhook delivery list, replay, and test sample operations. |
| 0Pools | Quote and execute partner-scoped liquidity workflows. | GET /pools, POST /pools/{id}/quote, POST /pools/{id}/transact, trade/quote reads. |
| 0Pools Scan | Query normalized protocol activity and explorer records. | Transactions, swaps, pool activity, mint/burn, assets, status, analytics, indexer views. |
0Base and 0Link API pages are not published yet
0Base and 0Link product guides remain available under Products, but their partner API reference pages are intentionally hidden until those surfaces are ready for partner API access. Do not build against unpublished endpoint paths.
Generated reference
| Artifact | Source |
|---|---|
| OpenAPI title | Gate API |
| OpenAPI version | 2026-05-25 |
| Website copy | public/openapi/gate-v1.yaml |
| Generated UI | Scalar 0Gate API |
The website copy should stay aligned with the current OpenAPI file. If the OpenAPI changes, regenerate the copy, review the SDK examples, and update the changelog before release.
Authentication model
| Credential | Where it lives | What it is for |
|---|---|---|
sk_test_* / sk_live_* | Server only | Creates or reads privileged resources, creates sessions, locks quotes, executes writes, reads protected records. |
pk_test_* / pk_live_* | Browser/mobile only where allowed | Browser-safe bootstrap or discovery calls, such as 0Gate embed bootstrap or product-specific publishable-key discovery. |
client_secret | Browser-safe but session-scoped | Binds a hosted experience to a single server-created session. |
whsec_* | Server only | Verifies signed webhook deliveries. |
| Idempotency key | Server-generated per logical write | Collapses duplicate retries into one logical operation. |
Never expose secret keys
sk_* keys belong on your server. Browser code can receive only product-approved browser-safe values such as pk_*
and session-scoped client secrets.
Request and response conventions
| Convention | Guidance |
|---|---|
| Decimal values | Send and store amounts as strings where the operation expects decimal strings. |
| Fake examples | Documentation examples use fake ids, keys, URLs, users, and order references. |
| Idempotency | Send Idempotency-Key on state-changing writes and persist it with your order/workflow record. |
| Request ids | Log response request ids and event ids for support and reconciliation. |
| Undocumented fields | Do not depend on fields that are not in the operation/schema reference. |
| Environment | Use sandbox/test keys and fake data until live access is approved. |
0Gate session example
curl -X POST https://gate-api-sandbox.0bit.app/v1/gate_sessions \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 00000000-0000-4000-8000-000000000123" \
-d '{
"amount": "100.00",
"currency": "EUR",
"return_url": "https://partner.example/complete",
"target_token": "USDT",
"metadata": { "order_id": "order_test_123" }
}'The creation response includes a client_secret for the browser. Retrieval responses should not expose that raw secret again.
0Pools quote and transact lifecycle
0Pools endpoint-level documentation is partner-sensitive. The public-safe lifecycle is:
| Step | API shape | Notes |
|---|---|---|
| Discover | GET /pools | Returns partner-entitled pools and availability. |
| Quote | POST /pools/{id}/quote | Locks a short-lived single-use quote; unavailable routes should not create stale locks. |
| Execute | POST /pools/{id}/transact | Executes against a quote; repeated execution should be idempotent for the quote/logical transaction. |
| Retrieve | Quote/trade read endpoints | Use for support and reconciliation. |
Errors, retries, and idempotency
Published Gate and Pools specs use a common error envelope with fields such as type, code, message, request_id, doc_url, and statusCode. Integrations should branch on machine-readable fields, log request ids, and avoid parsing free-form messages as business logic.
| Condition | Retry? | Notes |
|---|---|---|
| Network timeout or connection error | Yes, with bounded backoff and jitter | Use idempotency keys for writes. |
429 | Yes, respecting retry guidance where provided | Add jitter and alert on sustained rate limiting. |
5xx | Yes, with bounded backoff | Preserve request ids for support. |
| Validation error | No, unless request changes | Fix the request body or user input. |
| Auth or permission error | No, unless credentials/access changes | Rotate or request access; do not loop. |
| State conflict | Usually no | Retrieve current state and branch intentionally. |
Webhook lifecycle
Webhook handlers should verify signatures, reject stale timestamps, dedupe by event id, persist state transitions, and return 2xx only after durable handling. Browser callbacks are useful UX signals, not settlement truth.
Production readiness
- Product access approved.
- API credentials issued and stored server-side.
- Publishable keys isolated to client configuration.
- Allowed origins configured.
- Webhook endpoint deployed over HTTPS.
- Raw-body signature verification implemented.
- Idempotency implemented for writes.
- Duplicate event handling implemented.
- Bounded retry strategy implemented.
- Sandbox tests completed.
- Reconciliation, monitoring, alerting, support, security, and compliance reviews completed.
Related pages
0Gate sessions
Build server-side session flows.
Pools API
Review partner-safe liquidity API concepts.
Webhooks API
Understand event delivery, signing, and replay behavior.
Scalar 0Gate API
Browse the generated OpenAPI-backed API reference.
Errors and rate limits
Handle failures, retries, and idempotency safely.