Core Concepts
The shared 0Bit concepts behind products, credentials, sessions, quotes, payment objects, events, and reconciliation.
This page is the shared vocabulary for the 0Bit developer docs. Product pages go deeper, but the concepts below appear everywhere: organization accounts, product entitlements, environment modes, credentials, idempotency, objects, statuses, webhooks, Scan visibility, and reconciliation records.
Concept map
| Concept | Meaning | Where it appears |
|---|---|---|
| Organization | Your company account on 0Bit. It owns users, credentials, entitlements, product configuration, and webhook settings. | All products. |
| Entitlement | Product access granted to the organization, such as gate or pools. | Access checks and Partner Hub setup. |
| Product surface | A public product contract such as 0Gate, 0Pools, 0Base, 0Link, or 0Pools Scan. | Navigation, API boundaries, examples. |
| Environment | Test/sandbox or live/production mode. Keys and data do not cross modes. | Setup, authentication, webhook testing. |
| Session | A server-created unit of hosted 0Gate work. | 0Gate. |
| Quote | A short-lived price/terms preview or lock. | 0Gate quote-enabled flows, 0Pools, 0Link review. |
| Trade | A partner-visible execution/status record created from an accepted liquidity quote. | 0Pools. |
| Payment object | A checkout, payment intent, invoice, payment link, refund, ledger, report, or payout setting. | 0Base. |
| Link/route | A connected workflow or route review record. | 0Link. |
| Event | A signed asynchronous notification from 0Bit to your backend. | Webhooks across products. |
| Reconciliation | Joining your records, 0Bit ids, events, reports, ledgers, and Scan visibility into one support/accounting trail. | Operations. |
Ownership rule
The most important rule is simple: your backend owns your business state; 0Bit owns the product object; the browser owns only immediate UX.
| Layer | Trusted for | Not trusted for |
|---|---|---|
| Browser callback | Immediate UI transitions, pending screens, user messaging. | Final fulfillment, balances, settlement, invoice closure, or trade completion. |
| Server API response | Creating objects, storing ids, reading current trusted state. | Assuming asynchronous work is terminal unless the object says so. |
| Webhook event | Durable state after signature verification and event dedupe. | Business logic before verification. |
| 0Pools Scan | Activity visibility, support context, explorer-style investigation. | Replacing signed webhooks or proving private reserve state. |
| Ledger/report | Reconciliation and finance operations. | Real-time customer UX by itself. |
Credentials
| Credential | Where it belongs | Use |
|---|---|---|
pk_test_* / pk_live_* | Browser/mobile where allowed. | Bootstraps hosted or embedded flows. |
sk_test_* / sk_live_* | Server only. | Creates sessions, reads protected objects, executes approved writes. |
client_secret | Browser-safe for one product object where returned. | Binds an embed or hosted flow to one server-created object. |
whsec_* | Server only. | Verifies webhook signatures. |
| Idempotency key | Server-generated and stored. | Retries one logical write safely. |
Never ship sk_* or whsec_* to the browser. Never let a user change amount, currency, destination, entitlement, quote id, or settlement terms from client state alone.
Statuses
Every product has its own status model, but the lifecycle pattern is consistent:
| Phase | Typical meaning | Developer behavior |
|---|---|---|
| Created/open | The object exists but work is not complete. | Store ids, show pending UX, wait for next status. |
| Pending/processing | Payment, quote, route, KYC, transfer, or settlement work is in progress. | Keep user state non-final and make retry behavior idempotent. |
| Completed/settled | The product reached a terminal success state. | Fulfill only after trusted server read or verified webhook. |
| Failed/cancelled/expired | The product cannot complete in its current form. | Mark your record terminal or create a new product object. |
| Requires action/review | A user, partner, compliance, or operator step is missing. | Surface the allowed next action without exposing internal details. |
Idempotency
Use an Idempotency-Key on state-changing writes. Generate it in your backend, store it next to your own record, and reuse it for retries of the same logical action. Do not reuse one key for different amounts, destinations, quotes, users, or products.
curl -X POST "$OBIT_GATE_API_BASE_URL/gate_sessions" \
-H "Authorization: Bearer $OBIT_SECRET_KEY" \
-H "Idempotency-Key: order_123_create_gate_session" \
-H "Content-Type: application/json" \
-d '{"amount":"100.00","currency":"EUR","return_url":"https://app.partner.example/done"}'Reconciliation record
Keep one internal record that joins your state to 0Bit state:
| Field | Example |
|---|---|
| Your reference | order_123, account_action_456, invoice_789 |
| Product | 0gate, 0pools, 0base, 0link |
| 0Bit object id | Session id, quote id, trade id, payment intent id, route id |
| Idempotency key | The key used for the create/execute call |
| Latest trusted status | Last status from verified event or trusted read |
| Event ids | Webhook event ids already processed |
| Scan/report links | Public-safe investigation or finance references |
Mistakes to avoid
| Mistake | Correct pattern |
|---|---|
| Building a custom ramp UI by mixing 0Pools concepts into a 0Gate flow. | Use 0Gate hosted/embedded flows unless approved for headless 0Pools. |
| Showing provider/source names in customer UX. | Show product-safe states: available, quoted, processing, completed, failed. |
| Treating a quote as permanent. | Respect expiry and create a fresh quote when needed. |
Fulfilling from browser onSuccess. | Fulfill from verified webhook or trusted backend read. |
| Assuming examples prove live support. | Check entitlement, environment, country, currency, asset, and product availability. |