Getting Started with Stablecoins

This section prepares you to start building with Bitnob’s stablecoin APIs. Before issuing addresses, sending tokens, or listening for webhooks, there are a few foundational steps you need to complete.

Account Setup

To use stablecoin features on Bitnob, you’ll need to:

Create an organization via the Bitnob Dashboard

Generate API keys – separate keys are recommended for development and production

Request permissions – stablecoin operations require the wallet:read, wallet:write and transfer:create scopes

What the scopes mean

A scope is a permission attached to an API key. It decides which endpoints that key may call — a key without a scope can still authenticate, but every call to an endpoint behind that scope is rejected. These three cover the full stablecoin flow:

scope	what it lets the key do	endpoints it unlocks
wallet:read	Read-only access to wallets — check how much USDC/USDT you hold and read wallet metadata. Safe to give to reporting, reconciliation and dashboard services.	Get Balances
wallet:write	Create deposit addresses on a wallet, optionally tied to a customer. It does not move funds — it only creates places to receive them.	Generate Addresses
transfer:create	Send stablecoins out to an on-chain address. This is the only scope of the three that can move money, so keep it on as few keys and services as possible.	Create Withdrawal

To see which scopes a key actually carries, call Validate Authentication and read data.permissions on the response. A null value means the key is unscoped and has full account-level access — convenient in development, but not what you want in production.

All keys are scoped and role-based. Give each key only the scopes its service needs — see Role-Based Scopes for the full list, including webhook permissions. Never use a master API key directly from a frontend application.

Environments

Bitnob provides same URLs for testnet and production environments:

environment	base url
Testnet	https://api.bitnob.com/
Production	https://api.bitnob.com/

Your keys determine which environment a request hits — see the authentication overview. Stablecoin functionality is fully supported in both environments, and we recommend replicating your integration flow in testnet before going live. Testnet stablecoins may behave slightly differently due to network configuration, but all APIs and webhooks are consistent.

Authentication

All API requests must be authenticated using HMAC-based authentication. Include the generated HMAC signature and API key in the request headers. Copy-paste signing helpers live under Setup the Signing Function, with worked GET and POST examples, and you can confirm your setup with Validate Authentication.

header	description
X-Auth-Client	Your unique client ID from the Bitnob Dashboard
X-Auth-Timestamp	Current Unix timestamp in seconds
X-Auth-Nonce	A unique random string for each request
X-Auth-Signature	Hex-encoded HMAC-SHA256 signature over CLIENT_ID:TIMESTAMP:NONCE:PAYLOAD

Best practices:

Use environment variables to store and inject keys securely

Rotate keys regularly

Monitor and audit key usage from the Bitnob Dashboard

If your key is compromised, revoke it immediately from your dashboard to avoid unauthorized fund movement.

Rate Limits

Bitnob enforces per-key rate limits to protect against abuse and accidental overload:

Default: 60 requests per minute

Burst handling: brief spikes are tolerated but sustained overload is throttled

Error code on throttle: 429 Too Many Requests — listed with the other codes under Error Responses

Design your application to back off and retry with exponential delay. Contact support if you need higher throughput for enterprise use cases.

Idempotency

All state-changing requests (transfers, address generation) accept the Idempotency-Key header:

Idempotency-Key: 7f3b8f2a-9a3a-4e2c-8f16-01a17f8b2f8b

This guarantees:

Safe retries – clients can safely retry failed or timed-out requests

De-duplication – only one action is executed per key, even if sent multiple times

Traceability – logs and dashboard views reflect the original request status

You must generate a unique key per business event. Reusing the same key for different actions will result in validation errors.

Webhooks Overview

Webhooks are the primary way Bitnob informs your application of key events such as:

Incoming deposit detection

Withdrawal status changes

Network-level failure notifications

Webhook features:

Delivered over HTTPS

Signed for verification, and delivered from a fixed set of Source IPs

Retry with exponential backoff until acknowledged (2xx response)

We’ll go deeper into webhooks in the “Core Workflows” section, including payload structure, sample events, and how to set up reliable receivers.