Exchange Integration Guide

A complete walkthrough for building a production exchange on top of Bitnob Enterprise — from customer onboarding to policy-governed withdrawals.

This guide covers the full integration lifecycle: creating the vault topology, onboarding customers, detecting deposits, setting up gas sponsorship, processing withdrawals, and locking down the system with layered policies.

Prerequisites

You need a Bitnob Enterprise API key with admin permissions. All requests use the X-API-Key header. See Authentication for details.

Step 1: Create a Pool Vault

Create one pool vault per chain your exchange supports. A pool vault holds unlimited wallets, which makes it the correct choice for assigning a dedicated deposit wallet to each customer.

Create an Ethereum Pool Vault

Repeat this for each chain you support — Bitcoin, Solana, Tron, Base, and so on. Store the vault id for each chain; you will use it in the next step.

Step 2: Onboard Customers

For each customer, create a wallet inside the pool vault using customer_ref_id to link it to your internal customer ID. The response includes pre-derived deposit addresses for every asset you specify.

Create a Customer Wallet

Show the customer their deposit address from primary_addresses. Store the wallet id in your database mapped to the customer's account.

Step 3: Detect Deposits

Poll for inbound transactions on customer wallets, or use Subscriptions to receive real-time webhook notifications for each deposit.

Query Inbound Transactions

Credit the customer's exchange balance when a deposit reaches completed status with sufficient confirmations. Always reconcile against amount_decimal and asset_symbol — do not rely on internal accounting alone.

Use subscriptions for real-time deposits

For production, subscribe to incoming_token_tx and confirmation_threshold_met events via the Subscriptions API instead of polling. See the Webhook Notifications section of the API reference for payload details.

Step 4: Set Up Gas Stations

Create one gas station per chain to sponsor withdrawal fees automatically. Without a gas station, your customers would need to hold native tokens (ETH, TRX, SOL, etc.) alongside their assets.

Create an ETH Gas Station

Tron: Stake TRX for energy

On Tron, USDT transfers consume energy instead of TRX. Stake TRX from your gas station to get energy units — this dramatically reduces the per-transfer cost.

Stake TRX for Energy (Tron)

Monitor gas station health with GET /gasstations/stats. Set up alerting when health_status is low.

Step 5: Process Withdrawals

When a customer requests a withdrawal, create a transaction with gas sponsorship enabled. As long as every configured policy passes, the transaction is signed by the Enclave and broadcast automatically.

Submit a Customer Withdrawal

If a policy requires multi-party approval, the response status will be pending_authorization instead of signed. Always wait for a webhook notification of completed status before crediting or debiting exchange balances.

Step 6: Configure Policy Layers

Build a layered policy stack for defense in depth. Policies are evaluated in priority order — higher numbers are evaluated first.

Layer 1 — Root Quorum: Protect policy changes themselves. Without this, any admin key can modify policies unilaterally.

Create Root Quorum

Layer 2 — Block large withdrawals (over $50,000)

Block Large Withdrawals

Layer 3 — Velocity limits: Max $100K per day per wallet

Daily Velocity Limit

Step 7: Populate Address Book

Add known safe addresses — exchange hot wallets, partner addresses, institutional counterparties — to the address book. Then create a whitelist policy to block transfers to any non-listed destination.

Add a Known Address

Create Whitelist Policy

Step 8: Monitor and Export

Use these endpoints to power your operational dashboards and run daily reconciliation.

Monitoring Endpoints

Export Transactions for Reconciliation

Run daily reconciliation by matching your internal ledger against the exported transaction history. Investigate any withdrawal that was initiated but lacks a final completed status within your expected settlement window.

Match idempotency_key against your internal withdrawal records

Verify amount_decimal and asset_symbol against customer ledger entries

Alert on any transaction stuck in pending_authorization beyond your SLA window

Track gas station health daily and refill before health_status reaches low