Getting started

This page takes you from "I have a network URL" to a confirmed query and a transaction you understand the outcome of. It assumes you have read the Developers overview — endpoints, chain identity and denominations are defined there and used without re-introduction here.

Throughout, $REST stands for the Cosmos REST base URL of the network you are connected to.

Local development node

For a node you started yourself, keep the default localhost endpoints:

export CHAIN_ID=hkchain_262144-1
export EVM_CHAIN_ID=262144
export REST=http://localhost:1317
export GRPC=localhost:9090
export RPC=http://localhost:26657
export RPC_WS=ws://localhost:26657/websocket
export EVM_RPC=http://localhost:8545
export EVM_WS=ws://localhost:8546

Hosted public testnet

To target the hosted public testnet instead, use:

export CHAIN_ID=hkchaintest_2026-1
export EVM_CHAIN_ID=2026
export REST=https://api.hkchains.net
export RPC=https://rpc.hkchains.net
export RPC_WS=wss://rpc.hkchains.net/websocket
export EVM_RPC=https://evm.hkchains.net
export WEB=https://hkchains.net
export DASHBOARD=https://hkchains.net/dashboard
export EXPLORER=https://hkchains.net/explorer
export DOCS=https://hkchains.net/docs
export PORTAL=https://portal.hkchains.net

These are testnet services: assets have no monetary value and the network may be reset. Do not substitute these URLs into a local deployment unless you intend to switch that client from the local chain to the hosted testnet.

1. Confirm which network you reached

Do this before anything else. Chain identity is per network, and every signature you produce commits to it — signing against the wrong chain ID produces a transaction that is not merely rejected but unverifiable.

curl -s "$REST/cosmos/base/tendermint/v1beta1/node_info" \
  | grep -o '"network":"[^"]*"'

Expect hkchaintest_2026-1 from the public testnet, or hkchain_262144-1 from a default local node. Confirm the EVM side independently:

curl -s -X POST "$EVM_RPC" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

The public testnet returns 0x7ea (2026); a default local node returns 0x40000 (262144). If the Cosmos and EVM identities disagree you are talking to two different networks.

2. Read state

Every Hkchain query is a plain GET returning JSON. Three calls tell you most of what you need about a network.

Which stablecoins exist, and who issues them:

curl -s "$REST/hkchain/stablecoin/v1/denoms"

What an account holds — the standard Cosmos bank query, no Hkchain specifics:

curl -s "$REST/cosmos/bank/v1beta1/balances/hkchain1..."

Amounts come back as integer strings in the base unit: "150000" of hkd.hsbc is HKD 1,500.00, and ahkc is 18 decimals below one HKC.

Whether an account may transact in stablecoin at all:

curl -s "$REST/hkchain/kyc/v1/identity/hkchain1..."

A 404 here means the address has no identity record. That is the single most common reason an otherwise well-formed stablecoin transfer is rejected, so it is worth checking both the sender and the recipient before building anything.

3. Get an account that can transact

Two independent prerequisites, and a test network provides both through an onboarding portal rather than through the chain:

The portal exposes POST /faucet/native, POST /faucet/hkd and /kyc/apply. On the public testnet its base URL is https://portal.hkchains.net (the $PORTAL value above). The identity application proves you control the address by asking your wallet to sign a challenge — no private key ever leaves it.

Identity itself stays off chain. What the chain stores is the outcome: a level, the VASP an account is bound to, and a reference to records held elsewhere. See Accounts and keys.

4. Ask the chain before you send

Hkchain can tell you, gate by gate, what it would do with a transaction that does not exist yet. Build and sign the transaction as usual, then post the bytes to the simulation endpoint instead of the broadcast endpoint:

curl -s -X POST "$REST/hkchain/compliance/v1/simulate_trace" \
  -H 'Content-Type: application/json' \
  -d '{"tx_bytes":"<base64 signed tx>"}'

The response is one row per compliance gate — its name, whether it blocks or only flags, PASS / FAIL / FLAGGED, and on failure a readable reason — plus a top-level accepted. Nothing is written; the run happens on a discarded copy of state.

Use it as a pre-flight check in any integration that would otherwise learn about a rejection from a failed broadcast. It takes a Cosmos transaction — if you are transferring through the EVM interface instead, the equivalent pre-flight is a read-only eth_call of the same method, which runs the same gates and returns the revert reason. Errors and rejections covers reading either output.

5. Send, and confirm

The three steps are covered one page each, in order:

1. Building and signing a transaction — including the Travel Rule payload a stablecoin transfer must carry.
2. Broadcasting and confirmation — what a response code means at each stage, and when a transaction is actually final.
3. Events and indexing — reading the result, and subscribing to future ones.

If you want the whole picture before the mechanics, Transaction lifecycle traces one transfer from your process to a committed block.

Running a node yourself

The repository ships a single-command local network: make localnet resets a node home, writes a one-validator genesis, and starts the node in the foreground with all four interfaces listening. It is the fastest way to get an environment where you control every account.

Genesis seeding is opt-in through environment flags on that script, because a useful demo needs a cast — an issuer, auditors, identities at several levels, and an agent sub-key — that a bare chain has no way to invent. Read the header comment of scripts/localnet.sh for the current set.

Tooling: REST first

The hkchaind binary is a full node and a client: hkchaind query <module> <rpc> and hkchaind tx <module> <msg> subcommands are generated from the module schemas, and hkchaind tx_trace --hash <hash> prints the gate trace for a transaction.

One caveat worth knowing before you build tooling on the CLI. Generated subcommands for messages carrying a Coin, Timestamp, Duration or Any field fail at flag-merge time — a Cosmos SDK-wide limitation of command generation, not something specific to this chain. The rule of thumb is that any operation naming an amount or a period is affected: minting, distributing, burning, acknowledging a redemption, submitting a reserve attestation, and the compliance report query all fall in that set.

Every one of those messages is fully usable over REST and gRPC — only the generated command is unavailable. Prefer REST for anything you automate, and treat the CLI as an interactive tool.

Where to go next

• Accounts and keys — key type, the two address encodings, and how identity attaches to an account.
• API Reference — the complete query, message and event inventory.
• Attach a Travel Rule payload — the exact payload shape and the tier boundary.