# HoneyCoin Documentation

> Hi, you're in the HoneyCoin Documentation Space, we're a next-generation settlement, liquidity, and credit network leveraging blockchain and machine learning technologies to build better ways for businesses and consumers to transfer value, accrue yield, and store assets securely and seamlessly. You might be integrating with our API in order to consumer some of our services, if you are, you're in the right space, feel free to go through and if you need anything, message david@honeycoin.app (Our CTO).

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Authentication](https://docs.honeycoin.app/docs/authentication.md): This guide will walk you through the process of authenticating your API requests. By following these steps, you'll be able to securely access our services and utilize their full potential.
- [IP Allowlisting](https://docs.honeycoin.app/docs/ip-allowlisting.md): Restrict production payout requests to trusted server IP addresses configured in the HoneyCoin dashboard.
- [View Account Fees](https://docs.honeycoin.app/docs/view-account-fees.md): Learn where to find your account-specific deposit and withdrawal fees in the HoneyCoin dashboard.
- [Supported Countries & Limits](https://docs.honeycoin.app/docs/supported-countries-limits.md): A breakdown of the supported countries and their limits.
- [Mobile Money Operators](https://docs.honeycoin.app/docs/mobile-money-operators.md): Below is a list of the mobile money operators supported by our API, organised by country. To initiate a transaction, you'll need to use the operator code for the intended network.
- [ip-allowlisting-dashboard](https://docs.honeycoin.app/docs/ip-allowlisting-dashboard.md)
- [Info](https://docs.honeycoin.app/docs/info.md): This guide outlines the different methods available to charge your customers and manage incoming payments through the Honeycoin API.
- [Mobile Money Charge](https://docs.honeycoin.app/docs/mobile-money-collections.md): This guide explains the end-to-end flow to charge a customer via mobile money, verify the transaction status, and handle webhook notifications.
- [Bank Transfer](https://docs.honeycoin.app/docs/bank-transfer-1.md): This guide explains the end-to-end flow to charge a customer via bank transfer, verify the transaction status, and handle webhook notifications.
- [Universal Payment SDK](https://docs.honeycoin.app/docs/universal-payment-sdk.md): This guide explains how to use the Universal Payment SDK to accept payments from customers across multiple markets and payment methods through a single, unified endpoint.
- [Card Charge](https://docs.honeycoin.app/docs/card-charges.md): To integrate card payments, follow this guide to initiate charges, handle multi-step authentication (3DS, OTP, PIN, AVS), and verify transaction outcomes.
- [Opay Charge](https://docs.honeycoin.app/docs/opay-charge.md): Use the OPay Charge endpoint to accept NGN payments from customers via OPay.
- [Info](https://docs.honeycoin.app/docs/info-1.md): This guide covers how to disburse funds to recipients globally, including supported payout methods, country coverage, and real-time tracking via our API.
- [Payouts](https://docs.honeycoin.app/docs/payouts-1.md): This guide explains how to implement payouts, verify transaction status, and handle webhook notifications. Payouts allow you to send funds to recipients through mobile money, bank accounts, and other local payment methods.
- [Cross-border Transfer Overview](https://docs.honeycoin.app/docs/cross-border-overview.md): Follow saved identities, document review, collection, and beneficiary payout.
- [Cross-border Enums](https://docs.honeycoin.app/docs/cross-border-enums.md): Display titles and exact API codes for cross-border requests, identities, documents, and sandbox outcomes.
- [Cross-border Senders](https://docs.honeycoin.app/docs/cross-border-senders.md): Create and manage the people or businesses funding cross-border transfers.
- [Cross-border Beneficiaries](https://docs.honeycoin.app/docs/cross-border-beneficiaries.md): Create and reuse recipient identity and payout details before creating a transfer.
- [Cross-border Transfers](https://docs.honeycoin.app/docs/cross-border-transfers.md): Create a transfer with saved identities, satisfy documents, then collect funds and track payout.
- [Cross-border Supporting Documents](https://docs.honeycoin.app/docs/cross-border-documents.md): Upload, replace, submit, and resolve supporting documents before collecting funds.
- [Cross-border Status, Webhooks and Retries](https://docs.honeycoin.app/docs/cross-border-status-webhooks.md): Reconcile request and transaction IDs, handle lifecycle events and recover safely.
- [Info](https://docs.honeycoin.app/docs/info-2.md)
- [Supported Blockchains & Features](https://docs.honeycoin.app/docs/supported-blockchains-features.md): Cryptocurrency settlements and features are available across various blockchains. The table below outlines which features (WaaS, sponsored wallet transfers, Offramp, Onramp) are supported on each network:
- [Offramps](https://docs.honeycoin.app/docs/offramps.md): Our off-ramp API allows you to programmatically convert stablecoins (USDC/USDT) on supported EVM chains into fiat currency, which can be paid out to a bank account or a mobile money wallet. The process involves creating an off-ramp transaction, sending the specified crypto amount to a unique address, and waiting for the fiat payout.
- [Onramps](https://docs.honeycoin.app/docs/onramps.md): This guide explains how to implement the Onramp API to allow users to convert fiat currency into cryptocurrency. The API provides full control over the user experience and payment flow.
- [Onramp SDK](https://docs.honeycoin.app/docs/onramp-sdk.md): This guide explains how to implement the Onramp SDK to allow users to convert fiat currency into cryptocurrency. The SDK provides a pre-built, embeddable widget that handles the entire onramp user journey.
- [Wallets](https://docs.honeycoin.app/docs/wallets.md): This guide explains how to integrate with Honeycoin Wallets. Wallets let you create on-chain addresses, receive funds, send supported tokens, track wallet transactions, and receive wallet webhooks.
- [Escrow & Seller Balance Flows](https://docs.honeycoin.app/docs/escrows.md): The Escrows API provides a secure way to hold funds in escrow for business-to-business (B2B) transactions. It supports charging customers, holding funds, and disbursing payouts or refunds as needed.
- [Testing Collections](https://docs.honeycoin.app/docs/testing-collections.md): Choose the correct sandbox testing guide for hosted Payment SDK or direct collection API integrations.
- [Testing Onramps](https://docs.honeycoin.app/docs/testing-onramps.md): In the Test/Sandbox environment, use the following test accounts to simulate different onramp scenarios.
- [Testing Offramps](https://docs.honeycoin.app/docs/testing-offramps.md): In Test/Sandbox environment, use the following test accounts to simulate different offramp scenarios. All test transactions must use chain: BASE.
- [Testing Wallets](https://docs.honeycoin.app/docs/testing-wallets.md): Test the complete Wallets lifecycle in the sandbox without sending real crypto or broadcasting transactions to a blockchain.
- [Testing the Universal Payment SDK](https://docs.honeycoin.app/docs/testing-payment-sdk.md): Create a sandbox hosted-checkout session and test success, failure, OTP, PIN, 3DS, address-verification, and redirect scenarios.
- [Testing Direct Collection APIs](https://docs.honeycoin.app/docs/testing-direct-collections.md): Test mobile money, bank-transfer, card, and OPay collection endpoints without using the hosted Universal Payment SDK.
- [Testing Payouts](https://docs.honeycoin.app/docs/testing-payouts.md): In Test/Sandbox environment, use the following test accounts to simulate different payout scenarios.
- [Testing Cross-border Transfers](https://docs.honeycoin.app/docs/testing-cross-border-transfers.md): Test beneficiaries, required documents, approval and rejection, collection, payout, and recovery in sandbox.
- [Getting Started](https://docs.honeycoin.app/docs/getting-started-1.md): Our webhook system allows you to receive real-time notifications about various events in your account. Instead of polling our API for updates, webhooks push notifications to your specified endpoint as events occur.
- [Webhook Secrets](https://docs.honeycoin.app/docs/webhook-secrets.md): Set a shared webhook secret in your HoneyCoin dashboard and use it to verify incoming webhook requests.
- [Event Types & Structures](https://docs.honeycoin.app/docs/event-types-structures.md)
- [Transaction Events](https://docs.honeycoin.app/docs/transaction-events.md): Triggered when a transaction's status changes.
- [API Error Handling & Codes](https://docs.honeycoin.app/docs/errors.md): Our API uses standard HTTP status codes to indicate the success or failure of a request. For client-side errors (4xx) and server-side errors (5xx), the response body will contain a JSON object with a specific errorCode and a descriptive message.
- [Transaction Error Codes](https://docs.honeycoin.app/docs/transaction-error-codes.md): Our API normalizes upstream errors to provide consistent, human-readable messages. Below is a reference of the specific error strings returned in the API response and how to handle them.
- [Agent instructions](https://docs.honeycoin.app/docs/agent-instructions.md): Canonical rules every AI agent must follow when generating HoneyCoin integrations. Use this page when planning or building an integration.
- [Documentation access for AI agents](https://docs.honeycoin.app/docs/llms-and-skill.md): Find public API references and retrieve HoneyCoin guides as Markdown.
- [Machine-readable documentation](https://docs.honeycoin.app/docs/machine-readable-manifests.md): Public documentation sources for integration tools and AI agents.
- [MCP servers](https://docs.honeycoin.app/docs/mcp.md): Model Context Protocol servers for HoneyCoin docs and (soon) live API access. Read-only docs MCP is live; product MCP with route validation and payload checking is in development.
- [Prompt examples](https://docs.honeycoin.app/docs/prompt-examples.md): Copy-paste prompts to use HoneyCoin via Cursor, Claude, ChatGPT, or any AI coding assistant. Each prompt is paired with a note on what the agent should produce.

## API Reference
- [Welcome to the Honeycoin API! 👋🏼](https://docs.honeycoin.app/reference/welcome.md): The central hub for Honeycoin's API documentation, providing comprehensive guides and references for building financial solutions.
- [Generate Bearer Token](https://docs.honeycoin.app/reference/generate-bearer-token.md): Generates or retrieves a valid bearer token for a given public key. This token is used to authenticate requests and lasts for 1 hour.
- [Get User](https://docs.honeycoin.app/reference/get-user.md): The endpoint fetches user profile information, including their contact details and configured webhook URLs for both production and sandbox environments. It also includes information about any active wallets associated with the user's account.
- [Get Phone Number Operators](https://docs.honeycoin.app/reference/phone-number-operators.md): Retrieves the mobile money operator details for a given phone number, based on the number, currency, and country provided.
- [Get Transactions](https://docs.honeycoin.app/reference/get-transactions.md): Lists recent transactions for your account. Results are paginated and return up to 3 transactions by default. Pass limit to request up to 10 transactions per call. For status checks on a known transaction, use GET /api/b2b/transactions/{transactionId} with the transaction ID or external reference instead of polling this list endpoint.
- [Get Transaction](https://docs.honeycoin.app/reference/get-transaction.md): Returns one transaction by Honeycoin transaction ID or external reference. The transaction_updated webhook includes a summary amount and currency; for standard collections, these represent the source-side amount collected. Use this lookup for receiving-side amounts, conversion details, and fees. For standard deposits and collections, receiverAmount is the gross amount on the receiving side after any currency conversion; Honeycoin fees are returned separately in fee.feeAmount and fee.currency. When the fee and receiver currencies match, the net amount added to your Honeycoin balance is receiverAmount minus fee.feeAmount. When they differ, treat the received amount and fee as separate currency movements. How much you credit your own customer depends on your fee policy. For a failed off-ramp, status failed confirms the fiat payout did not complete; it does not confirm an on-chain refund. When the failed off-ramp has a deposit txId, use this lookup and treat the automatic refund as complete only when refundTransactionHash is present. Contact support if the hash remains absent.
- [Get Banks 🏦](https://docs.honeycoin.app/reference/get-banks.md): Fetch supported banks for a particular country.
- [Get Branches](https://docs.honeycoin.app/reference/get-branches.md): Get Bank Branches (Conditional on whether or not bank has branches as well)
- [Get Countries 🌍](https://docs.honeycoin.app/reference/get-countries.md): Get all supported countries and methods supported within them.
- [Get Mobile Money Providers](https://docs.honeycoin.app/reference/get-mobile-money-providers.md): This endpoint allows you to get the mobile money providers.
- [Currency Uptime Checker](https://docs.honeycoin.app/reference/currency-uptime-checker.md): Monitor the real-time health status of payment services across different currencies. Use this endpoint to check service availability before initiating transactions or to display the status on your integration's dashboard.
- [Account Resolver](https://docs.honeycoin.app/reference/account-resolver.md): Resolve and verify account details across multiple payment methods and currencies. Supply the `currency` and `method` to retrieve a normalised account name and ID.
- [Mobile Money Charge](https://docs.honeycoin.app/reference/charge-mobile-money.md): Initiates a mobile money charge request for transactions.
- [Bank Transfer](https://docs.honeycoin.app/reference/bank-transfer.md): This endpoint allows you to create temporary virtual bank accounts for accepting payments.
- [Universal Payment SDK](https://docs.honeycoin.app/reference/payment-sdk.md): The Payment SDK endpoint allows you to collect payments from customers in multiple markets all through this single endpoint.
- [Get Payment SDK Methods](https://docs.honeycoin.app/reference/get-payment-sdk-methods.md): This endpoint retrieves a list of available payment methods supported by the payment SDK integration. Developers can use this information to determine which payment options they can present to their users within the payment flow.
- [Validate OTP](https://docs.honeycoin.app/reference/validate-otp.md): This endpoint validates a deposit transaction that requires an OTP (One-Time Password) confirmation. It is typically used for mobile money collections (e.g., XOF) that involve an additional layer of authorization.
- [Refund Deposit](https://docs.honeycoin.app/reference/refund-deposit.md): This API endpoint allows you to initiate a refund for a previously successful mobile money deposit transaction.
- [Card Charge](https://docs.honeycoin.app/reference/card-charge.md): Start a card payment transaction by sending the customer's card details and transaction information.
- [Authorise Charge](https://docs.honeycoin.app/reference/authorise-charge.md): Submit the required authorisation data (3DS, OTP, PIN, or Address) to move the transaction forward.
- [Opay Charge](https://docs.honeycoin.app/reference/opay-charge-ref.md): Accept payments via OPay. Charges are processed asynchronously; some transactions require a redirect to complete authentication before funds are captured.
- [Payouts](https://docs.honeycoin.app/reference/payouts.md): This endpoint is a universal endpoint, below are schemas for different payouts such as mobile money or bank accounts and this endpoint allows you to payout to these destinations through this single endpoint.
- [Create a Cross-border Sender](https://docs.honeycoin.app/reference/create-cross-border-sender.md): Create an individual or business sender.
- [List Cross-border Senders](https://docs.honeycoin.app/reference/get-cross-border-senders.md): List active senders, newest first.
- [Get a Cross-border Sender](https://docs.honeycoin.app/reference/get-cross-border-sender.md): Fetch an active sender belonging to your account by sender ID.
- [Delete a Cross-border Sender](https://docs.honeycoin.app/reference/delete-cross-border-sender.md): Delete a sender from the active sender list.
- [Create a Cross-border Beneficiary](https://docs.honeycoin.app/reference/create-cross-border-beneficiary.md): Register recipient identity and payout instructions.
- [List Cross-border Beneficiaries](https://docs.honeycoin.app/reference/get-cross-border-beneficiaries.md): List active beneficiaries, newest first, with optional type and cursor filters..
- [Get a Cross-border Beneficiary](https://docs.honeycoin.app/reference/get-cross-border-beneficiary.md): Read an active beneficiary belonging to your account..
- [Delete a Cross-border Beneficiary](https://docs.honeycoin.app/reference/delete-cross-border-beneficiary.md): Soft-delete an owned beneficiary.
- [Create a Cross-border Request](https://docs.honeycoin.app/reference/create-cross-border-request.md): Create a transfer with senderId and beneficiaryId.
- [List Cross-border Requests](https://docs.honeycoin.app/reference/get-cross-border-requests.md): List your requests, newest first.
- [Get a Cross-border Request](https://docs.honeycoin.app/reference/get-cross-border-request.md): Fetch a request by its request ID.
- [Upload a Cross-border Supporting Document](https://docs.honeycoin.app/reference/upload-cross-border-document.md): Multipart upload in documents_required or documents_rejected.
- [Submit Cross-border Documents](https://docs.honeycoin.app/reference/submit-cross-border-documents.md): Explicitly submit after every required group is satisfied.
- [Simulate Cross-border Document Review](https://docs.honeycoin.app/reference/submit-sandbox-cross-border-documents.md): Sandbox credentials required.
- [Initiate a Cross-border Charge](https://docs.honeycoin.app/reference/initiate-cross-border-charge.md): Collect the saved quote.senderAmount using the saved chargeDetails.
- [List Cross-border Transactions](https://docs.honeycoin.app/reference/get-cross-border-transactions.md): List a request's deposit and payout transactions, newest first.
- [Get a Cross-border Transaction](https://docs.honeycoin.app/reference/get-cross-border-transaction.md): Retrieve a charge or payout transaction by its transaction ID.
- [Close a Cross-border Request](https://docs.honeycoin.app/reference/close-cross-border-request.md): Close an unpaid request.
- [Create an External Account](https://docs.honeycoin.app/reference/create-external-account.md): External accounts, also known as beneficiaries, are records of accounts where funds can be sent (payouts) or from which funds can be initiated (deposits). This can represent an individual's bank account, a business account, or a mobile money account, depending on the type.
- [Get External Accounts](https://docs.honeycoin.app/reference/get-external-accounts.md)
- [Get External Account](https://docs.honeycoin.app/reference/get-external-account.md)
- [Delete External Account](https://docs.honeycoin.app/reference/delete-external-account.md)
- [Update External Account](https://docs.honeycoin.app/reference/update-external-account.md)
- [Get Onboarding](https://docs.honeycoin.app/reference/get-onboarding.md): Retrieves onboarding information.
- [Get Accounts](https://docs.honeycoin.app/reference/get-accounts.md)
- [Get Account Transactions](https://docs.honeycoin.app/reference/get-account-transactions.md): Retrieves a list of transactions for a specific bank account. Please note, this will not work for customer accounts.
- [Off-Ramp](https://docs.honeycoin.app/reference/crypto-off-ramp.md): The endpoint allows you to send tokens to an escrow address and get the value back in a number of different FIAT currencies.
- [On-ramp](https://docs.honeycoin.app/reference/onramp.md): Convert fiat currency into USDC or USDT through mobile money, bank transfer, or OPay and settle it to an on-chain wallet address.
- [Crypto Charge](https://docs.honeycoin.app/reference/crypto-charge.md): Create a crypto payment request. Returns a unique deposit address for the customer to send funds to. Once funds are detected on-chain, a webhook is fired to your configured endpoint.
- [Generate Address](https://docs.honeycoin.app/reference/generate-address.md): Creates a smart-contract wallet address.
- [Get Addresses](https://docs.honeycoin.app/reference/get-addresses.md): Returns all smart-contract wallets under your account.
- [Get Address](https://docs.honeycoin.app/reference/get-address.md): Returns a single wallet and includes the current balances.
- [Create Subscription](https://docs.honeycoin.app/reference/create-subscription.md): Creates an address activity subscription for a wallet and associates a delivery webhook URL.
- [Get Subscriptions](https://docs.honeycoin.app/reference/get-subscriptions.md): Get all subscriptions.
- [Get Subscription](https://docs.honeycoin.app/reference/get-subscription.md): Get subscription
- [Delete Subscription](https://docs.honeycoin.app/reference/delete-subscription.md): Deletes a subscription
- [Get Webhooks](https://docs.honeycoin.app/reference/get-webhooks-1.md): Returns webhook delivery attempts created from wallet subscriptions.
- [Get Webhook](https://docs.honeycoin.app/reference/get-webhook-1.md): Returns full delivery metadata for a single webhook event.
- [Resend Webhook](https://docs.honeycoin.app/reference/resend-subscriptions-webhook.md): Queues a webhook for another delivery attempt.
- [Get Transactions](https://docs.honeycoin.app/reference/get-wallet-transactions.md): Returns wallet transactions.
- [Get Transaction](https://docs.honeycoin.app/reference/get-wallet-transaction.md): Internal wallet transaction ID.
- [Get Onchain Transaction](https://docs.honeycoin.app/reference/get-onchain-transaction.md): Returns on-chain transaction data without requiring an internal wallet transaction ID.
- [Transfer tokens](https://docs.honeycoin.app/reference/wallet-transfer-tokens.md): Creates and executes an outbound token transfer from one wallet.
- [Get FX Rate 💱](https://docs.honeycoin.app/reference/fx-rates-get-conversion.md): This endpoint retrieves the currency conversion rate and the converted amount from one currency to another.
- [Get Historical Rates 💱](https://docs.honeycoin.app/reference/get-historical-rates.md): This will give you historical BID or ASK rates for a specific pair over the last 30 days.
- [Create Escrow](https://docs.honeycoin.app/reference/create-escrows.md): Creates a new escrow account.
- [Get Escrows](https://docs.honeycoin.app/reference/get-escrows.md): Retrieves a paginated list of escrows for the authenticated user.
- [Get Escrow](https://docs.honeycoin.app/reference/get-escrow.md): Retrieves details of a specific escrow, including current balance.
- [Initiate Charge](https://docs.honeycoin.app/reference/initiate-charge.md): Initiates a charge on the escrow using the predefined charge details.
- [Initiate Payout](https://docs.honeycoin.app/reference/initiate-payout.md): Initiates a payout from the escrow to the receiver. You can specify the amount to payout.
- [Initiate Refund](https://docs.honeycoin.app/reference/initiate-refund.md): Refunds funds from the escrow back to the sender.
- [Get Transactions](https://docs.honeycoin.app/reference/get-transactions-1.md): Retrieves all transactions tied to an escrow account.
- [Create Seller](https://docs.honeycoin.app/reference/create-seller.md): Create a new seller profile for escrow balance tracking
- [Get Seller](https://docs.honeycoin.app/reference/get-seller.md): Retrieve detailed information for a specific seller
- [Get Sellers](https://docs.honeycoin.app/reference/get-sellers.md): Retrieve all sellers associated with the authenticated user
- [Simulate Webhook](https://docs.honeycoin.app/reference/simulate-webhook.md): This endpoint lets you simulate webhook events in the sandbox environment, allowing you to test your webhook handling code without waiting for real events.
- [Get Webhooks](https://docs.honeycoin.app/reference/get-webhooks.md): This api allows for users to fetch their webhooks.
- [Resend Webhook](https://docs.honeycoin.app/reference/resend-webhook.md): Allows a user to resend webhooks.
- [Get Webhook](https://docs.honeycoin.app/reference/get-webhook.md): Fetch a webhook.

## Recipes
- [How to Collect Africell Mobile Money Payments from your Customers in The Gambia (GMD) or DR Congo (CDF)](https://docs.honeycoin.app/recipes/how-to-collect-africell-mobile-money-payments-from-your-customers-in-the-gambia-gmd-or-dr-congo-cdf.md)
- [How to Collect Orange Money Mobile Money Payments from your Customers in Burkina Faso (XOF)](https://docs.honeycoin.app/recipes/how-to-collect-orange-money-mobile-money-payments-from-your-customers-in-burkina-faso-xof.md)
- [How to Collect Orange Money Mobile Money Payments from your Customers in Cote d'Ivoire (XOF)](https://docs.honeycoin.app/recipes/how-to-collect-orange-money-mobile-money-payments-from-your-customers-in-cote-divoire-xof.md)
- [How to Collect OTT Voucher Payments from your Customers in Botswana (BWP)](https://docs.honeycoin.app/recipes/how-to-collect-ott-voucher-payments-from-your-customers-in-botswana-bwp.md)