API Reference

Hkchain inherits most of its API surface from the frameworks it is built on, and adds four modules of its own plus an extended ERC-20 interface. This page maps the whole surface and says which document specifies each part; the pages in this section detail the Hkchain-specific half.

The pages in this section

Each page gives the REST path, permissions, parameters and response shape for every method, with an invocation example.

What is Hkchain's own, and what is inherited

Reaching Hkchain queries

Every Hkchain query is a gRPC method with an HTTP mapping, so it is callable two ways against the same node:

• REST — GET {rest}/hkchain/<module>/v1/<path>, JSON in and out. Enum fields arrive as strings and 64-bit integers as decimal strings, which is the standard gRPC-gateway encoding.
• gRPC — service hkchain.<module>.v1.Query, using the protobuf schemas in the repository.

Transactions are submitted the ordinary Cosmos way: build a transaction containing one or more of the messages below, sign it, and broadcast it through the Cosmos REST/gRPC transaction service or CometBFT. Hkchain adds no custom broadcast endpoint.

Module surfaces

The inventory below is the complete set of Hkchain-defined methods, as a one-screen map. Follow the module link for paths, permissions, parameters, response shapes and examples.

hkchain.stablecoin.v1 — HKD supply

• Messages: MsgMint, MsgDistribute, MsgBurn, MsgAckRedemption, MsgPause, MsgUnpause, MsgFreezeAccount, MsgUnfreezeAccount, MsgRegisterDenom, MsgUpdateParams
• Queries: Denoms, Denom, IssuerTreasury, RedemptionRequest, OpenRedemptions, PauseState, Params

hkchain.compliance.v1 — gates, audit trail, delegation

• Messages: MsgUpdateSanctionsList, MsgUpdateRule, MsgReviewFlag, MsgEscalateFlag, MsgCloseFlag, MsgBindSubRole, MsgRevokeSubRole, MsgBindAgentPolicy, MsgUpdateParams
• Queries: AuditLog, Flags, Report, TravelRulePayload, SubRoleBindings, SubRoleParent, AgentPolicy, SanctionsSet, Params, TxTrace, SimulateTrace

TxTrace and SimulateTrace are the two that integrators reach for most: they return, gate by gate, why a transaction was accepted or rejected — the first for a transaction that already ran, the second for one you are about to send.

hkchain.reserve.v1 — proof of reserve

• Messages: MsgSubmitAttestation, MsgCoSignAttestation, MsgRegisterAuditor, MsgRevokeAuditor, MsgUpdateParams
• Queries: LatestAttestation, AttestationForPeriod, ReserveForAddress, DailyStatement, Auditors, Attestations, Params

hkchain.kyc.v1 — identity registry

• Messages: MsgEnroll, MsgUpgradeLevel, MsgBlacklist, MsgWhitelistIssuer, MsgUpdateParams
• Queries: Identity, LevelDistribution, IdentitiesByLevel, Params

The registry holds no personal data. It records an identity level, the VASP an account is bound to, and a reference to off-chain identity records — never the records themselves.

Typed events

State-changing operations emit typed events, declared in proto/hkchain/<module>/v1/events.proto. Events are the intended integration point for indexers and back-office reconciliation: subscribe over the CometBFT WebSocket for live delivery, or read them from a transaction result after the fact.

The mapping is deliberately not one event per message. Build an indexer against the event schemas rather than against the message list, and note four shapes:

• Opposite operations share one event that carries the resulting state. MsgPause and MsgUnpause both emit EventPauseChanged; MsgFreezeAccount and MsgUnfreezeAccount both emit EventAccountFrozen; MsgUpgradeLevel and MsgBlacklist both emit EventLevelChanged.
• Some events have no message behind them at all. A compliance flag (EventFlagEmitted) is raised by a gate while a transaction is being admitted, and the daily reserve statement (EventDailyStatement) is emitted at a block boundary rather than by anyone's transaction.
• MsgUpdateParams emits nothing. Every module exposes this governance parameter setter, and none of them emits an event for it — observe a parameter change through the module's Params query.
• Two schemas are declared but not yet emitted. EventSARFiled and EventTravelRuleAnchored exist in hkchain.compliance.v1 for planned behaviour; nothing in the current chain emits them. Do not build a consumer that waits on either.

There is a fifth shape that catches indexers specifically: one event in hkchain.compliance.v1 fires on every write to a record rather than on its creation. Each module page lists which of its events come from where.

The EVM interface

Each HKD denom visible to the EVM is served by an ERC-20 interface at its own fixed address. It is standard ERC-20 with one departure — the vanilla transfer and transferFrom revert, and two extended methods carry the Travel Rule payload — so that no compliance-free path exists to the same balances.

Addresses are published as chain state; query GET {rest}/cosmos/evm/erc20/v1/token_pairs rather than hard-coding them.

Extended ERC-20 interface has the ABI, the payload encoding, the gas and revert behaviour, and how EVM-originated transfers appear in Cosmos events.