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 wallet:read, wallet:write, and transfer:create scopes
All keys are scoped and role-based. Never use a master API key directly from a frontend application.
Environments
Bitnob provides separate URLs for testnet and production environments:
| Environment | Base URL |
|---|---|
| Testnet | https://sandboxapi.bitnob.com/v1 |
| Production | https://api.bitnob.com/v1 |
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 your secret key in the Authorization header:
Authorization: Bearer sk_live_xxxx
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
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
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.
