Core Concepts & Architecture
This section provides a big-picture view of how Bitnob’s platform and its associated APIs—support Bitcoin transactions, stablecoin rails, and a growing suite of value-added services like airtime top-ups and bill payments. By understanding these components, you’ll be better equipped to build secure, efficient solutions on top of Bitnob.
Overview of Bitnob’s Infrastructure
Bitnob is built to streamline financial operations, particularly in Africa—yet it remains accessible to developers and businesses worldwide. Key elements include:
Crypto Rails:: Bitcoin (on-chain and Lightning) and stablecoins.
Fiat Integration: On/off ramps supporting key African currencies, enabling seamless crypto-fiat conversion.
Value-Added Services: Airtime purchases, bill payments, and more.
Account & Wallet Services: Secure custody, address management, and transaction tracking.
Multi-Asset Management: Handle Bitcoin, stablecoins, and fiat transactions seamlessly in one wallet, allowing diversified asset storage and transactions for users and businesses.
Key Entities & Concepts
Accounts
When you sign up for Bitnob, you gain access to an account that holds your API credentials, usage analytics, and security configurations. This is your primary control center for all Bitnob services.
Wallets
A wallet in Bitnob is a logical container for storing or transacting funds. Bitnob supports various wallet types, each tailored to different use cases:
BTC Wallet: For on-chain Bitcoin storage and transactions.
Stablecoin Wallet : For holding and transacting in stablecoins (e.g., USDT, USDC) on supported blockchains (ERC20, TRC20, etc.).
Transactions & Payment Flows
Bitnob’s transaction ecosystem can be broadly grouped into three areas:
Crypto Transactions:
On-chain Bitcoin transfers, Lightning payments, and stablecoin transfers.
Fiat Transactions
Deposits (on-ramps) from local bank accounts or mobile money, and withdrawals (off-ramps) back to those accounts.
Value-Added Services:
Airtime & Bill Payments :: Convert crypto or fiat balances directly into airtime purchases or utility bill settlements.
Virtual Card Issuance :: Create and manage virtual cards for day-to-day spending, payroll, or e-commerce purchases.
Rate Limits & Quotas::
To maintain platform stability, some API calls have usage limits. Each response usually includes headers indicating your current usage or remaining quota. The API Reference details specific thresholds so you can avoid hitting rate limits.
Authentication & Security:
Bitnob uses Bearer Token authentication for all API requests. Important best practices:
Secure Storage:Keep these tokens in encrypted vaults or environment variables.
Token Lifecycles: Ensure tokens are up to date and promptly revoke or refresh if compromised.
Permissions: Larger organizations can set role-based permissions to limit API access based on function.
Value-Added Services in Detail
Airtime & Bill Payments:
Bitnob expands its core crypto capabilities with airtime and bill payment services. This means developers can:
Directly use wallet balances (BTC, stablecoins, or fiat) to purchase airtime or pay utility bills.
Reduce friction by providing an integrated “spend crypto” experience—no separate manual withdrawals required.
By linking these services into your application, you can offer end-users a streamlined option to top up phone credit or settle bills, all within one workflow.
Virtual Cards:
Alongside airtime and bills, Bitnob enables virtual card issuance for more flexible spending options:
Single-Use or Recurring Cards: Useful for one-off purchases or ongoing corporate expenses.
Global Acceptance: In many cases, virtual cards can be used wherever major card networks are accepted.
Real-Time Funding : Instantly load a card from your Bitnob wallet—simplifying everything from employee reimbursements to e-commerce checkouts.
Architecture Diagram (Conceptual)
Client App sends a request with its bearer token to the Bitnob API Layer.
Auth & Security verifies credentials and roles.
Depending on the endpoint, the request may route to Wallet Management, the Transactions Engine, or Value-Added Services , .
All modules update and retrieve data from the Database & Ledger .
Client App receives a response with transaction details, balances, or confirmation of a completed service.
Security & Compliance
Encryption at Every Layer: HTTPS for data in transit; recommended encryption for data at rest.
Regulatory Requirements: Certain features may require KYC or compliance steps depending on user location or transaction size.
Monitoring & Alerts: Suspicious or large transactions may trigger flags for further review, ensuring platform integrity.
Best Practices
Use Sandbox for Testing: Validate your logic and user flows on sandboxapi.bitnob.co before switching to production.
Leverage Webhooks (where available): Automate your back-end with real-time transaction notifications.
Monitor Updates: Subscribe to changelogs or dev announcements so you’re aware of new value-added services or changes to existing ones.
Next Steps
Now that you understand Bitnob’s Bitcoin and stablecoin rails, plus the additional services for airtime, bill payments, and beyond, you’re ready to:
Explore the Endpoint Reference: Learn how to manage wallets, process crypto payments, and integrate airtime/bill pay flows.
Regulatory Requirements: Certain features may require KYC or compliance steps depending on user location or transaction size.
Build Your Use Case: Start combining these components to craft a seamless experience—from funding a wallet to paying a phone bill in one go.
