Setting Up a Bitnob Account

Building on Bitnob starts with creating and configuring your developer account. Follow the steps below to test in our Sandbox environment and go live in Production once you’re ready.

Create Your Account

Visit https://app.bitnob.com/

Enter a valid email address.

Check your email for a confirmation code.

Enter your personal details and choose a strong password (at least 12 characters, mix of letters, numbers, symbols).

After email confirmation, go to Dashboard.

Enter your email and password to sign in.

Familiarize yourself with the main sections: API Keys, Wallets, Transactions, and Usage Reports.

Tip

If you plan to collaborate with others, invite your colleagues through your account settings.

Complete Basic Profile Setup

Add Company and Contact Info

In the Profile section, enter your company name or project name.

Provide a contact phone number and mailing address (used for invoices and notifications).

Optionally upload a logo or avatar to personalize your dashboard view.

KYC and Compliance (Optional for Sandbox)

For sandbox testing, you can skip verification and operate under default limits.

To lift transaction limits and unlock Production, submit your business registration documents, ID proofs, and bank account details under Identity & Compliance.

Verification usually completes within 24–48 hours. You’ll get an email update once approved.

Sandbox vs. Production Environments

Bitnob uses the same API base URL (https://api.bitnob.com) for both sandbox and production. The difference is the API keys used, not separate endpoints. Always isolate your keys to avoid mixing environments.

Sandbox Environment

API Base URL: https://api.bitnob.com

Use sandbox keys to test wallet creation, payments, and webhooks without moving real funds.

Sandbox data may reset periodically; don’t rely on it for long-term records.

Production Environment

API Base URL: https://api.bitnob.com

Use production keys to process real transactions and manage live balances.

Only switch after fully testing all flows and completing any required KYC.

Caution

Before moving to production, ensure your code uses your production secret key. Your Client ID is the same across sandbox and production — only the Secret Key differs. Mixing secret keys across environments causes authentication failures.

Generate HMAC Client ID and Secret Key

Secure your integration by generating separate credentials for sandbox and production.

Locate API Keys Section

In the left menu, select Settings > API Keys.

You’ll see existing keys (if any) and the option to create new ones.

Create New Key

Click Create Key and fill the create an API Key form.

After creation, copy the Client ID and Secret Key immediately; you won’t see the secret again.

Secure Storage

Store credentials in environment variables or a secure vault (e.g., AWS Secrets Manager, HashiCorp Vault).

Never hardcode keys or check them into source control.

Rotate keys regularly and revoke unused ones.

Example `.env` File

BITNOB_CLIENT_ID=yourClientId***

BITNOB_SECRET_KEY=yourSecretKey***

HMAC Signature Authentication

Standard API requests are authenticated with an HMAC signature. Both your CLIENT_ID and CLIENT_SECRET are required. Each request is signed with a timestamp and nonce, making it tamper-proof and resistant to replay attacks.

Signing a Request

Build the canonical message by concatenating these fields in exactly this order, separated by colons, then sign it with HMAC-SHA256 keyed by your CLIENT_SECRET and hex-encode the result. PAYLOAD is the exact JSON body you're sending (empty string if there is no body).

Signature

Sending the Headers

Attach all four custom headers on every API request:

header	value	purpose
X-Auth-Client	Your CLIENT_ID	Identifies who is calling the API
X-Auth-Timestamp	Unix timestamp in seconds	Prevents replay of old requests
X-Auth-Nonce	16-byte hex-encoded nonce	Adds per-request uniqueness
X-Auth-Signature	The hex-encoded HMAC	Verifies integrity & authenticity

For the full signing walkthrough — nonce/timestamp generation and worked examples in Node.js, Go, and Python — see the Authentication Guide.

Enterprise API Authentication

Every request to the Enterprise API is authenticated with an API key. Keys are issued from the Bitnob dashboard and carry a permission set that is bound to your organisation at issue time.

Sending Your API Key

Pass your key on the X-API-Key header with every request:

Required Headers

The organisation context is resolved automatically from the key — you never need to send an org ID header. Keep keys server-side. A leaked key grants the same authority a signed-in admin user does, up to the limits of its permission set and configured policies.

header	required	description
X-API-Key	Yes	Your API key. Organisation is derived from the key automatically.
X-API-VERSION	No	API version. Defaults to v1 if not supplied.
Content-Type	For writes	Must be application/json for all POST, PUT, and PATCH requests.

Keep keys server-side

Never expose an Enterprise API key in a mobile app, frontend JavaScript bundle, or public repository. All signing should happen in your backend.

For the full enterprise flow — how authorization and policies are evaluated, API versioning, and idempotency — see the Enterprise Authentication Guide.

Verify Your Setup

A quick call to the /api/whoami endpoint confirms you’ve set up your account and keys correctly — it validates your credentials and returns your authenticated account details. To learn how to sign these requests, see HMAC Signature Authentication above, or refer to our full Authentication Guide. Here’s an example using a sandbox key:

API Request Example

Note

If everything is working properly, you’ll receive a 200 OK with JSON data about your authenticated account.

Next Steps

Explore the Quickstart: Follow our guide to create wallets, send test payments, and handle callbacks.

Review Core Concepts: Understand how Bitnob’s rails, wallets, and events connect across the platform.

Check Tutorials: See real-world use cases—like Lightning transactions—before diving into the full API Reference.

That’s It!

With your Bitnob account created and your API credentials verified in sandbox, you’re ready to integrate with confidence. Move on to advanced features and scale your application for production when you’re ready.