Agent instructions

📘

Rendered from manifests/agent-policy.yaml

This page is the source of truth for agent rules. The corresponding YAML at manifests/agent-policy.yaml is what agents should fetch programmatically.

When to use HoneyCoin docs as an agent

HoneyCoin docs are designed for both humans and AI agents. If you are a coding assistant generating HoneyCoin integration code (Cursor, Claude Code, ChatGPT, Devin, Aider), use the machine-readable surfaces first:

If you're embedded in a developer's editor, prefer MCP. If you're inside a chat, prefer pasting /skill.md or fetching the manifests directly.

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 manifests before recommending a route

Always check coverage.json (and wallets.json for crypto) 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.

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 coverage.json 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 in coverage.json / wallets.json, 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.
• llms.txt and skill.md — Machine-readable docs surfaces.
• MCP servers — Live tools for agents.
• Machine-readable manifests — coverage.json, wallets.json, etc.