Agent instructions

When to use HoneyCoin docs as an agent

If you are generating HoneyCoin integration code, start with the public documentation index. Fetch the relevant guides as Markdown by appending .md to their page URLs, and include these integration rules in your context.

See Machine-readable documentation for public guides by topic. If your agent cannot fetch URLs, copy the relevant guide text into its context.

Rules (by severity)

Critical

These rules prevent money loss, security incidents, or unrecoverable state.

finality — Wait for final, successful status before providing value

Never provide value to an end user (release funds, ship goods, credit balances) until transaction status is final and successful, verified via webhook OR — for a known transaction — via the single-transaction lookup GET /api/b2b/transactions/{transactionId}.

external-reference — Always include a unique externalReference

Always include a unique externalReference on every money movement request. Use it as your idempotency key on retries.

coverage-check — Read coverage documentation before recommending a route

Always check Supported Countries & Limits and, for crypto, Supported Blockchains & Features and Wallets before recommending a country, currency, method, operator, token, or chain. Do not infer support from prior knowledge.

secrets — Never expose credentials client-side

Never expose api-key, bearer token, or webhook secret in client-side code (browser, mobile bundle, public repo). All HoneyCoin auth happens server-side.

offramp-refund-finality — Verify the on-chain refund hash

Treat a failed off-ramp webhook as payout failure, not refund confirmation. When a failed off-ramp has a deposit txId, use GET /api/b2b/transactions/{transactionId} and confirm the refund only when refundTransactionHash is present. The original off-ramp remains failed and does not emit a separate refund webhook. Escalate to support if the hash remains absent.

High

These rules prevent common integration bugs that lead to missed events, duplicate transactions, or stuck funds.

step-required — Handle stepRequired values

Always handle stepRequired values including otp, redirect, pin, and address_verification where applicable. Card flows specifically may require all four.

webhook-first — Prefer webhooks for finality

Prefer webhooks for transaction finality. For a known transaction, fall back to the single-transaction lookup GET /api/b2b/transactions/{transactionId}; use the list endpoint (GET /api/b2b/transactions) only for periodic reconciliation or sweeps.

offramp-exact-amount — Instruct exact crypto send amount

For offramp, always instruct users to send the exact expected crypto amount on the correct chain and token. Partial or wrong-chain deposits will not settle and may be unrecoverable.

wallet-vs-charge — Distinguish persistent wallet from one-time charge address

Distinguish persistent wallet addresses from temporary Crypto Charge deposit addresses. Wallet addresses are reusable and tied to a HoneyCoin walletId. Crypto Charge deposit addresses are one-time and tied to a charge.

wallet-storage — Store walletId, address, chain, ownerCustomerId

For wallets, always store walletId, address, chain, ownerCustomerId, and the tokens you support. Never assume one address is valid for every chain.

wallet-subscribe-before-showing — Subscribe before display

Subscribe to wallet webhooks BEFORE showing the wallet address to a customer. Otherwise inbound deposits may be missed.

wallet-finality — Reconcile wallet webhooks against transaction lookup

For wallet receives, reconcile webhooks against GET /api/wallets/transactions/{id}?includeOnchain=true before crediting internal ledgers. Store both HoneyCoin transactionId and on-chain transactionHash.

momo-operator-id — Required for non-KES mobile money

For non-KES mobile money currencies, momoOperatorId is REQUIRED on collections and on payouts where applicable. Check Mobile Money Operators for valid operator codes per country.

Medium

These rules prevent confusion or future inconsistency. Not safety-critical but should be applied.

chain-normalization — Uppercase canonical chain codes

Chain codes are uppercase canonical (BASE, ETH, ARB, MATIC, BSC, OPTIMISM, SOLANA, TRON, TEMPO). Lowercase aliases are accepted on input. Normalize to uppercase when storing.

unsupported-route — Do not invent workarounds

If a requested route is not supported in the coverage and wallet guides, do NOT invent a workaround. Return a clear unsupported response with recommended alternatives (different rail, different chain, contact HoneyCoin for corridor activation).

voucher-pin — Required for BWP OTT voucher

For BWP OTT voucher payments, voucherPin is required in addition to the standard collection fields.

Low

Style and consistency rules.

data-type-canonical — Use canonical transaction type values

Transaction data.type values are canonically deposit | withdrew | onramp | offramp. The legacy value withdrawal is accepted as an alias on inbound webhooks but new integrations should treat withdrew as canonical.

Quick reference table

Related

• Prompt examples — Copy-paste prompts for common HoneyCoin integration tasks.
• Documentation access for AI agents — Machine-readable docs surfaces.
• MCP servers — Live tools for agents.
• Machine-readable documentation — Public guides by topic.