# 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 |

- **API Documentation:** https://docs.honeycoin.app
- **API Reference:** https://docs.honeycoin.app/reference/welcome
- **Dashboard:** https://b2b.honeycoin.app
- **Contact for access:** api@honeycoin.app

---

## 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

```bash
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.

- **Method:** POST
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/fiat/payout`
- **Supported destinations:** Mobile Money (MoMo), Bank Account, Paybill, Till, External Account

**Mobile Money Payout Example:**
```json
{
  "amount": 100,
  "currency": "KES",
  "country": "KE",
  "externalReference": "unique_ref_001",
  "payoutMethod": {
    "accountName": "John Doe",
    "accountNumber": "254719624552",
    "code": "mpesa"
  },
  "destination": "MoMo"
}
```

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

**Paybill Payout Example:**
```json
{
  "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):**
- Mobile Money: KES 10 – 250,000
- Bank Transfer: KES 10 – 999,999
- Paybill/Till: KES 10 – 250,000

**Processing times:**
- Mobile Money: 1–5 minutes
- Bank Transfers: 1–24 hours
- Paybill/Till: 1–5 minutes

### 2. Collect Payments

Accept payments from customers via multiple methods.

#### Bank Transfer Collection
- **Method:** POST
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/fiat/deposit/bank-transfer`
- Creates a temporary virtual bank account for the customer to pay into

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

#### Universal Payment SDK
- **Method:** POST
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/fiat/payment-sdk`
- Unified endpoint for mobile money, bank, and local payment methods across multiple markets

```json
{
  "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
- **Method:** POST
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/fiat/deposit/{transactionId}/refund`
- Only applicable to mobile money deposits

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

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

Convert fiat currency into cryptocurrency on any supported EVM blockchain.

- **Method:** POST
- **Endpoint:** `https://crypto.honeycoin.app/api/minting/onramp`
- **Supported chains:** ETH, ARB, BASE, MATIC, BSC, OPTIMISM
- **Supported crypto:** USDC, USDT

**Mobile Money Onramp Example:**
```json
{
  "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:**
```json
{
  "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.

- **Method:** POST
- **Endpoint:** `https://crypto.honeycoin.app/api/minting/offramp`
- **Supported chains:** ETH, ARB, BASE, MATIC, BSC, OPTIMISM
- **Important:** Generates a deposit address valid for 1 hour; exact amount must be sent

**Mobile Money Offramp Example:**
```json
{
  "amount": 5000,
  "currency": "KES",
  "country": "KE",
  "chain": "base",
  "destination": "MoMo",
  "externalReference": "offramp_001",
  "payoutMethod": {
    "accountName": "John Doe",
    "accountNumber": "254712345678",
    "code": "mpesa"
  }
}
```

**Response includes:**
- Unique deposit address (valid 1 hour)
- Exact `expectedAmount` of USDC/USDT to send

**Webhook on completion:**
```json
{
  "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

- **Method:** GET
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/utilities/rates/historical`
- Query historical and current FX rates between any two supported currencies

### 6. Query Transaction History

- **Method:** GET
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/transactions`
- Returns up to 50 transactions per call with cursor-based pagination

**Query Parameters:**
- `currency` — e.g. KES (defaults to KES)
- `type` — e.g. withdrew, deposited
- `externalReference` — match your reference
- `startDate` — format YYYY-MM-DD
- `endDate` — format YYYY-MM-DD
- `status` — pending, failed, or successful
- `transactionId` — cursor for pagination

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

### 7. Get Supported Banks

- **Method:** GET
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/utilities/banks?country=KE`
- Returns bank codes for use in bank transfer payouts and collections

### 8. Get Mobile Money Operators

- **Method:** GET
- **Endpoint:** `https://api-v2.honeycoin.app/api/b2b/utilities/momo/providers`
- Returns operator codes by country

**Operator Codes:**
- Kenya: `mpesa`, `airtel`
- Uganda: `mtn`, `airtel`
- Tanzania: `airtel`, `tigo`, `halopesa`, `vodacom` (collections only)
- Ghana: `mtn`, `airtel`, `vodacom`
- Rwanda: `mtn`, `airtel`
- Cameroon: `mtn`, `orange`
- Zambia: `mtn`, `airtel`, `zamtel`
- Ethiopia: `cbe`, `telebirr`
- Gambia: `africell`, `qcell`, `wave`
- Malawi: `tnm`, `airtel`

---

## Webhooks

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

**Delivery characteristics:**
- Timeout: 15 seconds
- Retries: Up to 3 times with exponential backoff (5s → 15s → 45s)
- Event type: `transaction_updated`

**Webhook payload example:**
```json
{
  "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:**
```json
{
  "success": false,
  "message": "External reference already in use.",
  "errorCode": "DUPLICATE_EXTERNAL_REFERENCE"
}
```

---

## Use Cases for AI Agents

- **Automated payroll** — Agent reads payroll data, calls POST /fiat/payout for each employee in 14+ African countries
- **Cross-border supplier payments** — Agent initiates bank or mobile money payouts on invoice approval
- **Crypto portfolio management** — Agent monitors on-chain positions and executes off-ramps to fiat when needed
- **DApp fiat gateway** — Agent triggers onramp to convert user fiat to USDC/USDT for on-chain use
- **Reconciliation bot** — Agent queries transaction history with date filters and cross-references internal records
- **Collections automation** — Agent creates bank transfer deposit accounts for incoming invoices
- **Real-time FX monitoring** — Agent watches rates and triggers swaps when favorable
- **Agent network top-ups** — Agent initiates mobile money payouts to field agents across multiple countries

---

## Supported Integrations

- ERP systems (via REST API)
- Accounting software (via webhook + transaction query)
- HR/Payroll platforms (via payout API)
- E-commerce platforms (via collections API)
- DeFi protocols (via on/off ramp endpoints)
- Custom AI agents (OpenAI, Anthropic, Google, etc.)

---

## Developer Resources

- **Full API Docs:** https://docs.honeycoin.app
- **API Reference:** https://docs.honeycoin.app/reference/welcome
- **Authentication Guide:** https://docs.honeycoin.app/docs/authentication
- **Collections Guide:** https://docs.honeycoin.app/docs/info
- **Payouts Guide:** https://docs.honeycoin.app/docs/info-1
- **On/Off Ramps Guide:** https://docs.honeycoin.app/docs/info-2
- **Webhooks Guide:** https://docs.honeycoin.app/docs/getting-started-1
- **Supported Countries & Limits:** https://docs.honeycoin.app/docs/supported-countries-limits
- **Mobile Money Operators:** https://docs.honeycoin.app/docs/mobile-money-operators
- **Error Codes:** https://docs.honeycoin.app/docs/errors
- **Dashboard:** https://b2b.honeycoin.app
- **Contact:** api@honeycoin.app | sales@honeycoin.app