Integration patterns

Five shapes of integration, and what each one actually has to get right. The mechanics are on the preceding pages; this is about which of them apply to you and where the design pressure is.

The two decisions everyone makes

Which path. The Cosmos path and the EVM path reach the same balances, and the supported stablecoin transfer on each — MsgSend on one side, transferWithTravelRule on the other — reaches the same gates. For moving stablecoin, then, this is mostly a tooling decision. Where the paths genuinely differ in capability is on the read side: the Hkchain module queries in the first row below exist only over Cosmos REST and gRPC.

You can mix: read over REST, transfer over the EVM interface. One key works on both sides. What does differ is where a compliance rejection appears — a broadcast response on one side, a mined transaction's receipt on the other — so error handling is per path even when the rules are not. Transaction lifecycle has the comparison.

Who holds the key. A custodial integration signs for its users and owns the consequences. A non-custodial one hands an unsigned transaction to a wallet. The compliance model does not change either way — the gates evaluate the account, not who operated it — but the identity question does: a custodial service is typically the VASP for its users, and its own identity record is what the Travel Rule payload describes.

Wallet

Present balances, send transfers, show the user why something failed.

• Normalise addresses at the boundary. One key, two encodings — pick one for storage and convert at the edges.
• Look up the recipient's identity before building the transfer. A missing identity record is the most common rejection, and the only one you can catch entirely client-side.
• Read the sender's registered tier and use it. Do not choose a tier from the amount; the amount only decides whether the registered tier is sufficient.
• Surface raw_log. It is written to be read by a person.
• Keep the native balance visible. A user with stablecoin and no ahkc cannot transact, and nothing about the transfer explains why.

Merchant or payee

Accept a payment, and know when it is yours.

• Give each payment a unique reference and confirm by transaction hash, not by watching a balance. Balances do not attribute.
• Confirm the execution verdict, not the broadcast verdict. Admission and success are different answers — see Broadcasting and confirmation.
• Subscribe rather than poll once you have more than a handful of payments in flight, and backfill by transaction search after any disconnect. Have a terminal path for a hash that never resolves — an admitted transaction can be dropped from a mempool without any notification.
• Check which denom arrived. Each issuer's stablecoin is its own denom and they are not interchangeable at the protocol level; accepting hkd.hsbc is not accepting every HKD stablecoin.
• Finality is instant. There is no confirmation depth to wait for — a transaction with a height is final.

Agent or automated payer

A machine that spends on someone's behalf — the case the delegated-key model exists for.

• Bind an agent sub-key rather than sharing the principal's key. The envelope is enforced by the chain: a per-transaction cap, a 24-hour spend cap, and a revocation that takes effect at the next block.
• Build the Travel Rule payload from the parent's identity. The agent has no identity record of its own, and a payload describing the agent fails the registry checks.
• Send with MsgSend. That is what the agent allowlist is written for, and the gate's enforcement covers the message shapes it recognises rather than every message the chain accepts — so the allowlist is a contract to build inside, not a fence to lean on.
• Expect cap rejections as normal operation, not as errors to retry. The 24-hour window is a fixed period anchored at the agent's first spend, not a sliding one, so capacity returns all at once at the turnover rather than trickling back. Read window_start before showing a user when they can spend again.
• Track sequence locally. An automated payer submitting concurrently will collide with itself otherwise; the collision is sdk code 32, not a signature problem.
• Pre-flight when a rejection is expensive — simulate_trace for a Cosmos transaction, a read-only eth_call for the EVM interface. The gate trace tells you which cap you are about to hit.

Indexer or reconciliation service

Build a durable view of what the chain did.

• Index on events, not on messages. The mapping is not one-to-one: opposite operations share an event, some events have no message behind them, and parameter changes emit nothing. Events and indexing has the three cases.
• Parse attribute values as JSON. Typed-event attributes are JSON-encoded, so strings arrive quoted.
• Treat the stream as lossy and the search as authoritative. Subscriptions drop; record the last processed height and backfill.
• Backfill block events separately. Transaction search only finds what a transaction emitted; the daily reserve statement is emitted at a block boundary with no transaction behind it, so a search-only reconnect drops it silently. Recover it from the reserve state query instead.
• Count a transfer once. One movement leaves several traces of itself — an ERC-20 log if it came through the EVM interface, the bank module's transfer event, an ethereum_tx event, message.sender in both hex and Bech32. Pick one and ignore the rest. There is no Hkchain typed event for an ordinary transfer, so do not wait for one.
• Do not index gate traces. They are per-node, in-memory, and time-bounded. The durable compliance record is the audit log and the flags.
• Resolve delegated signers to their parent before attributing activity. Compliance flags and audit entries record the signing key, not the parent, so a delegated payment otherwise appears to come from an unknown account.

Regulator-facing or compliance tooling

Read-only by design. Every supervisory surface on this chain observes; none of them signs.

The queries that matter are the ones assembled at read time rather than stored: the audit log, the flag queue, the reserve attestations and daily statements, and the identity level distribution. The API Reference inventories them.

Two properties to build on rather than around:

• The audit log is append-only. A report is a view over it, not a snapshot, so re-running a report over the same period gives the same answer plus anything that arrived since.
• Reserve attestations require two signatures. An issuer submits, a registered auditor co-signs, and only then is the attestation final. A single-signature attestation is a real state — pending — and should be displayed as such rather than filtered out.

Things that surprise people

Collected from the failure modes above, in the order they usually bite:

1. A successful broadcast is not a successful transaction.
2. Gas is ahkc; a stablecoin balance alone cannot pay for anything.
3. The plain ERC-20 transfer reverts by design.
4. A native transfer passes no gate at all — the perimeter is the stablecoin, not the chain.
5. The gates inspect a fixed set of message shapes. Moving a stablecoin balance some other way is not inspected, so build on the supported shapes rather than expecting the chain to stop everything else.
6. Tier comes from the sender's identity level, not from the amount.
7. Each issuer's stablecoin is a separate denom.
8. A delegated key is evaluated as its parent, but recorded as itself.
9. Gate traces expire; the audit log does not.
10. On the EVM path a compliance rejection is a revert inside a mined transaction, not a rejected submission — and the receipt says status: 0x0 without saying why.

Where to go next

• API Reference — the complete surface.
• Use cases — the same patterns as end-to-end business flows, with every actor's step shown.