agents.md

HoneyCoin Agent Capabilities Manifest

This document describes what AI agents and automated systems can do with the HoneyCoin API programmatically. Last updated: 2026-04-11 Source: Real API documentation at https://docs.honeycoin.app

Overview

HoneyCoin provides a full REST API that enables AI agents and automated workflows to execute payouts, collect payments, perform crypto on/off ramps, check FX rates, query transactions, and more — all programmatically without human intervention.

API Base URLs

Environment Base URL
Production (B2B/Fiat) https://api-v2.honeycoin.app/api/b2b
Production (Crypto) https://crypto.honeycoin.app/api
Sandbox (B2B/Fiat) https://api-v2.honeycoin.app/api/sandbox/b2b
Sandbox (Crypto) https://crypto.honeycoin.app/api/sandbox

Authentication

HoneyCoin uses a two-step authentication flow:

Step 1: Get Your Keys

  1. Log in to dashboard: https://b2b.honeycoin.app/login
  2. Navigate to Developers → API Keys
  3. Copy your Public Key and API Key (format: HC_yyyyyyyyyyyyyyyyyyyyyyyy)

Step 2: Generate a Bearer Token

POST https://api-v2.honeycoin.app/api/b2b/auth/generate-bearer-token

Headers:
  api-key: YOUR_API_KEY
  Content-Type: application/json

Body:
  {"publicKey": "YOUR_PUBLIC_KEY"}

Response:
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....",
  "expiresAt": 1752085041
}

Step 3: Use Token in All Requests

Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/json

Important: Bearer tokens expire after 2 hours. Your application must refresh tokens automatically.

Capabilities

1. Send Payouts (Cross-Border Payments)

Send funds to mobile money wallets, bank accounts, or M-Pesa Paybill/Till numbers.

Mobile Money Payout Example:

{
  "amount": 100,
  "currency": "KES",
  "country": "KE",
  "externalReference": "unique_ref_001",
  "payoutMethod": {
    "accountName": "John Doe",
    "accountNumber": "254719624552",
    "code": "mpesa"
  },
  "destination": "MoMo"
}

Bank Account Payout Example:

{
  "amount": 100,
  "currency": "KES",
  "country": "KE",
  "externalReference": "unique_ref_002",
  "payoutMethod": {
    "accountName": "John Doe",
    "accountNumber": "1280179878793",
    "code": "1243"
  },
  "destination": "Bank Account"
}

Paybill Payout Example:

{
  "amount": 100,
  "currency": "KES",
  "country": "KE",
  "externalReference": "unique_ref_003",
  "payoutMethod": {
    "accountName": "John Doe",
    "accountNumber": "12345677890",
    "businessNumber": "123456"
  },
  "destination": "Paybill"
}

Payout Coverage (14+ Countries):

Country Supported Methods
Kenya Mobile Money (M-Pesa, Airtel), Bank, Paybill, Till
Uganda Mobile Money (MTN, Airtel)
Tanzania Mobile Money (Airtel, Tigo, Halopesa), Bank
Rwanda Mobile Money (MTN, Airtel)
Nigeria Bank Transfer
Ghana Mobile Money (MTN, Airtel, Vodacom), Bank
Ethiopia Mobile Money (CBE, Telebirr)
Malawi Mobile Money (TNM, Airtel), Bank
Cameroon Mobile Money (MTN, Orange)
Zambia Mobile Money (MTN, Airtel, Zamtel)
Sierra Leone Mobile Money
Senegal Mobile Money
Benin Mobile Money
Gambia Mobile Money (Africell, Qcell, Wave)

Transaction Limits (Kenya example):

Processing times:

2. Collect Payments

Accept payments from customers via multiple methods.

Bank Transfer Collection

{
  "amount": 1000,
  "email": "customer@example.com",
  "externalReference": "deposit_001",
  "currency": "KES"
}

Universal Payment SDK

{
  "amount": 5000,
  "chargeCurrency": "KES",
  "walletCurrency": "USD",
  "externalReference": "sdk_deposit_001",
  "customerId": "customer_abc",
  "successRedirectUrl": "https://yourapp.com/success",
  "cancelRedirectUrl": "https://yourapp.com/cancel",
  "failureRedirectUrl": "https://yourapp.com/failure"
}

Collections Coverage (20+ Countries): Kenya, Uganda, Tanzania, Rwanda, Nigeria, Ghana, Ivory Coast, Cameroon, Zambia, Sierra Leone, Senegal, Benin, Gambia, Ethiopia, Malawi, Liberia, Burkina Faso, Botswana, Mali

Refund a Deposit

{
  "refundReason": "Customer requested refund",
  "externalReference": "refund_001"
}

3. Crypto On-Ramp (Fiat → USDC/USDT)

Convert fiat currency into cryptocurrency on any supported EVM blockchain.

Mobile Money Onramp Example:

{
  "senderAmount": 5000,
  "senderCurrency": "KES",
  "receiverCurrency": "USDC",
  "chain": "base",
  "receiverAddress": "0xbac726e1df4dd58ca13bf6b9f23664df5d07d2fe",
  "method": "momo",
  "chargeDetails": {
    "phoneNumber": "254719624551",
    "momoOperatorId": "mpesa"
  },
  "externalReference": "onramp_user_001",
  "email": "user@example.com"
}

Response:

{
  "success": true,
  "data": {
    "transactionId": "y47aWLwUE2NW7duNNbiM"
  }
}

4. Crypto Off-Ramp (USDC/USDT → Fiat)

Convert USDC/USDT on any supported EVM chain into fiat currency delivered to mobile money or bank account.

Mobile Money Offramp Example:

{
  "amount": 5000,
  "currency": "KES",
  "country": "KE",
  "chain": "base",
  "destination": "MoMo",
  "externalReference": "offramp_001",
  "payoutMethod": {
    "accountName": "John Doe",
    "accountNumber": "254712345678",
    "code": "mpesa"
  }
}

Response includes:

Webhook on completion:

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "zQQvoWnhYED3yXYEo7y7",
    "status": "successful",
    "type": "offramp",
    "externalReference": "offramp_001",
    "method": "momo",
    "depositAddress": "0x318aa0c46120bb214f7da0d53183d0b1c9be7047",
    "txId": "0xc3acfde7f212fcb902045119ee41299249ca153fc5c2730b0e8adba749846b53"
  },
  "timestamp": "2025-08-18T10:40:38.922Z"
}

5. Get FX Rates

6. Query Transaction History

Query Parameters:

GET /api/b2b/transactions?currency=KES&type=withdrew&status=successful&startDate=2026-01-01

7. Get Supported Banks

8. Get Mobile Money Operators

Operator Codes:

Webhooks

Configure webhook URLs in your dashboard at https://b2b.honeycoin.app.

Delivery characteristics:

Webhook payload example:

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "abc123",
    "status": "successful",
    "type": "payout",
    "externalReference": "your_ref"
  },
  "timestamp": "2026-04-11T10:40:38.922Z"
}

Best practice: Keep webhook handlers lightweight; offload processing to background jobs to avoid timeout failures.

Error Handling

HTTP Status Error Code Description
403 USER_NOT_ONBOARDED Account not fully onboarded/approved
409 DUPLICATE_EXTERNAL_REFERENCE externalReference already used — must be unique
422 INSUFFICIENT_FUNDS Wallet balance too low
503 FX_RATE_UNAVAILABLE FX rate temporarily unavailable — safe to retry
500 INTERNAL_SERVER_ERROR Unexpected server error
403 CURRENCY_NOT_ENABLED Currency not enabled on your account
422 MOMO_CODE_REQUIRED Mobile money operator code required
422 DEBIT_CURRENCY_NOT_SUPPORTED Invalid debit/payout currency combination

Error response format:

{
  "success": false,
  "message": "External reference already in use.",
  "errorCode": "DUPLICATE_EXTERNAL_REFERENCE"
}

Use Cases for AI Agents

Supported Integrations

Developer Resources