Build on Mainnet with source-checked APIs, CLI tools and application examples. Open live Mainnet stats

Developers / Mainnet handbook

Build on Chipcoin.

From your first API request to an explorer, a wallet or a payment application: a source-checked guide to Chipcoin Mainnet HTTP APIs, CLI tools and wallet integration.

Reviewed 17 November 2026 · Mainnet chipcoin-mainnet-1 · 28 HTTP routes · 70 CLI commands. Sources and scope

01 / Start here

Your first Mainnet request.

No wallet, API key or local node is needed for these public reads. Use a terminal with curl, or the browser example below from an HTTPS application.

bash
API='https://mainnet-api.chipcoinprotocol.com'
curl --fail-with-body --max-time 15 "$API/v1/health"
curl --fail-with-body --max-time 15 "$API/v1/tip"
curl --fail-with-body --max-time 15 "$API/v1/supply"

Verify the chain, not just the address prefix.

/v1/health must report network: mainnet, chain_id: chipcoin-mainnet-1 and genesis hash 00000238ef41c47992581c18fad544b4e24ecf1e79e7ffed629a215def4a337f. Stop if they differ. A CHCQ prefix alone is not proof of a provider's network.

Read a public balance in JavaScript

javascript
const API = "https://mainnet-api.chipcoinprotocol.com";
async function getJson(path) {
  const response = await fetch(API + path, {
    headers: { Accept: "application/json" },
    signal: AbortSignal.timeout(15000)
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${path}`);
  return response.json();
}
async function mainnetBalance(address) {
  const health = await getJson("/v1/health");
  if (health.network !== "mainnet" ||
      health.chain_id !== "chipcoin-mainnet-1" ||
      health.genesis_hash !==
        "00000238ef41c47992581c18fad544b4e24ecf1e79e7ffed629a215def4a337f") {
    throw new Error("Wrong chain: stop before using this provider");
  }
  const balance = await getJson("/v1/address/" + encodeURIComponent(address));
  const amount = balance.spendable_balance_chipbits;
  if (!Number.isSafeInteger(amount) || amount < 0) {
    throw new Error("Unsafe amount: use a lossless JSON parser");
  }
  const bits = BigInt(amount);
  return {
    ...balance,
    spendable_chc: `${bits / 100000000n}.${String(bits % 100000000n).padStart(8, "0")}`
  };
}
// Call mainnetBalance(yourPublicChcqAddress) from your own UI.
// Render values with textContent, never untrusted innerHTML.

Replace the address in your own UI with a real public Mainnet CHCQ address. This function reads data; it does not connect a wallet, authenticate a user or move funds.

02 / Know your chain

Mainnet is not an EVM chain.

Native UTXOs

Transactions spend previous outputs and create recipient outputs. Balances distinguish confirmed, immature and spendable amounts. Do not treat an address history row as an account nonce or contract event.

CHCQ + ML-DSA-44

Mainnet standard payments use CHCQ addresses and ML-DSA-44, signature scheme 10. Use the current Core serializer and signer, not Bitcoin/Ethereum transaction encoding or a legacy CHCC/secp256k1 payment recipe.

Integer units

1 CHC = 100,000,000 chipbits. CLI amounts and fees are integers. Keep accounting in integers or exact decimals; do not calculate payments with floating-point CHC values.

Testnet and mainnet-test-only are different chains. The Testnet Faucet cannot fund Mainnet. Test payment code in an isolated supported test environment first; every Mainnet submission can spend real funds.

03 / Choose your interface

Three surfaces. Different access boundaries.

The table below reflects the current production proxy allowlists, checked on 17 November 2026. An endpoint in Core is not automatically exposed on every public hostname.

Public wallet API

https://mainnet-api.chipcoinprotocol.com

CORS-enabled reads for health, status, tip, supply, addresses and transactions, plus signed transaction submission. No keys or privileged node operations.

Explorer read proxy

https://explorer.chipcoinprotocol.com/api/mainnet

Additional blocks, mempool, public peers and selected rewards reads. GET/OPTIONS only. It is same-origin for the official explorer, not a promised cross-origin browser API: use your own backend for an independent explorer.

Your local node

NODE_URL = your configured loopback HTTP listener.

Full node HTTP reference below. Run a synced Mainnet node using Run a Node. Keep mining, diagnostic and operator surfaces private.

Public access has no documented SLA. Cache reads, bound concurrency and respect HTTP 429. The current wallet proxy limits transaction submissions per IP; limits may change. Never use public endpoints as an unrestricted bulk indexer or depend on permissive CORS from the explorer proxy.

04 / Complete HTTP reference

Every route in the reviewed Core adapter.

Paths are relative to the chosen base URL. “Wallet” means the public wallet API; “explorer” means its read proxy; “local” means your own node. Parameter placeholders are not literal addresses or transaction IDs.

Method and pathAvailable surfaceParameters and behavior
GET /v1/healthWallet + explorer + localNetwork identity: status, network, chain_id, genesis_hash.
GET /v1/statusWallet + explorer + localNode status, height, sync and peers. Read supply separately from /v1/supply.
GET /v1/supplyWallet + explorer + localIssued, circulating, immature and scheduled supply; integer chipbits.
GET /v1/tipWallet + explorer + localCurrent height and block_hash; use with the block API to detect reorgs.
GET /v1/blocksExplorer + locallimit=1..100 (default 20), from_height >= 0 (inclusive; not above tip). Newest first.
GET /v1/blockExplorer + localExactly one of height >= 0 or hash. Includes header and transaction summaries; fetch each tx for inputs/outputs.
GET /v1/tx/<txid>Wallet + explorer + local64-hex txid. location, height, block_hash and transaction; 404 if not found.
POST /v1/tx/submitWallet + explorer + localJSON {raw_hex: signed transaction hex}. No server-side signing; acceptance is not confirmation.
GET /v1/mempoolExplorer + localoffset=0..100000, limit=1..1000 (default 100). Pending transaction diagnostics.
GET /v1/peersLocal onlyoffset=0..100000, limit=1..1000 (default 200). Full peer diagnostics: keep private.
GET /v1/peers/summaryExplorer + localAggregate peer health and counts.
GET /v1/peers/publicExplorer + localPublic bootstrap peer candidates, not a guarantee of live connectivity.
GET /v1/address/<address>Wallet + explorer + localConfirmed, immature and spendable balances, utxo_count and address scheme.
GET /v1/address/<address>/utxosWallet + explorer + localArray: txid, vout, amount_chipbits, coinbase, mature, status and origin_height.
GET /v1/address/<address>/historyWallet + explorer + locallimit=1..100 (default 50), order=asc|desc (default desc). Confirmed history only; no offset/cursor/type filter.
GET /v1/rewards/epochLocal onlyOptional epoch_index and node_id. Detailed reward state.
GET /v1/rewards/assignmentsLocal onlyOptional epoch_index and node_id. Verifier assignments.
GET /v1/rewards/node-statusExplorer + localRequired node_id; optional epoch_index >= 0.
GET /v1/rewards/node-feesExplorer + localCurrent registration and renewal fees. Never hardcode them.
GET /v1/rewards/epoch-summaryExplorer + localRequired epoch_index >= 0. Aggregated reward accounting.
GET /v1/rewards/concentrationLocal onlyOptional epoch_index >= 0. Reward concentration report.
GET /v1/rewards/attestationsLocal onlyOptional epoch_index. Attestation diagnostics.
GET /v1/rewards/attestation-backlogLocal onlyPending attestation workload.
GET /v1/rewards/settlementsExplorer + localOptional epoch_index. Settlement diagnostics.
GET /v1/rewards/settlement-reportExplorer + localOptional epoch_index. Settlement accounting report.
GET /mining/statusLocal onlyLocal mining status only; never expose an unrestricted mining API.
POST /mining/get-block-templateLocal onlyJSON payout_address, miner_id, optional template_mode (default full_block).
POST /mining/submit-blockLocal onlyJSON template_id, serialized_block and miner_id. Consensus-valid blocks only.

Reward-node API boundary

The reward routes in the reference above expose state and diagnostics. Registration, renewal, attestation and settlement transactions use specialized Core CLI/signing workflows; there is no public HTTP endpoint that registers a reward node on your behalf. Check current fees, eligibility and the installed CLI help before any submission.

Core also handles OPTIONS for its API prefixes; public proxies restrict paths and methods separately. This is HTTP JSON, not JSON-RPC. Core errors generally use {"error":{"code":"invalid_request","message":"..."}}; proxy-denied requests can return HTML instead.

Private mining is not a public dApp API.

Mining template and block submission routes are for authorized miners. Their local body requirements are listed above; they must not be exposed by your application frontend. For users who only want to mine, see Pool Mining.

Peer discovery is separate

The bootstrap seed service is not the node API. Its discovery paths include GET /v1/health, GET /v1/peers?network=mainnet and POST /v1/announce. Follow the node's configured seed setup; do not substitute a seed URL for the wallet API or treat peer announcements as authenticated wallet ownership.

05 / Understand the responses

Amounts, rewards and history windows.

Response shapes

  • /v1/blocks, UTXOs, address history and mempool return arrays, not a results wrapper.
  • A block contains transaction summaries. Use /v1/tx/TXID for transaction.inputs, transaction.outputs, metadata and location.
  • Address balances use confirmed_balance_chipbits, immature_balance_chipbits, spendable_balance_chipbits and utxo_count.
  • History uses block_height, txid, incoming_chipbits, outgoing_chipbits and net_chipbits. Change means incoming and outgoing are not simply payment amounts.

Reward classification

Use explicit is_coinbase, reward_types, mining_reward_chipbits and node_reward_chipbits fields when present. Never infer mining from a fixed “50 CHC” amount.

A tx_type: transfer history label is not a complete consensus transaction taxonomy. Inspect the full transaction metadata for specialized reward-node operations. A recent window is not a lifetime total.

Pagination that actually exists

  • Blocks: newest first; the next older page begins at the smallest returned height minus one. Stop at genesis.
  • Address history: limit and order only. No offset, cursor, height filter or type filter in the reviewed HTTP adapter. Raising a limit returns a larger overlapping window, not a new page.
  • Mempool and full peer diagnostics: offset/limit; snapshots may change while paging.
  • Complete history: operate your own reorg-aware indexer. Do not repeatedly scan public address history to reconstruct the chain.

JavaScript numbers cannot represent arbitrary-size integers exactly. Validate amount fields with Number.isSafeInteger before converting to BigInt; use a lossless JSON parser or strings from your own backend for potentially larger values such as cumulative work. Converting an already-rounded number to BigInt does not restore precision.

06 / CLI handbook

Local tools, verified arguments.

Core needs Python 3.11 or newer. Use a vetted Mainnet release and its documented ML-DSA backend, not an unrelated package named “chipcoin”. The commands below are checked against the linked source revision. They do not replace the Mainnet deployment guide.

bash
git clone https://github.com/chipcoin-protocol/chipcoin.git
cd chipcoin
# Reviewed source revision for this handbook; use your vetted release in production.
git checkout 31a2a4d531170cbc51671790bd5c1a492ea5c533
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
chipcoin --network mainnet --help
chipcoin --network mainnet wallet-build --help

--network, --data and --log-level are global options: put them before the command. The database must belong to the selected chain. Do not launch a second node process or a state-changing CLI against a production database; use a stopped node or a consistent backup where appropriate. HTTP reads are preferable for live applications.

Read chain and address data

bash
# Set these to your own paths and public Mainnet address.
DB='/absolute/path/to/your/mainnet-node.sqlite3'
ADDRESS='YOUR_MAINNET_CHCQ_ADDRESS'

chipcoin --network mainnet --data "$DB" status
chipcoin --network mainnet --data "$DB" block --height 1
chipcoin --network mainnet --data "$DB" balance --address "$ADDRESS"
chipcoin --network mainnet --data "$DB" address-history --address "$ADDRESS" --limit 20
chipcoin --network mainnet --data "$DB" reward-summary --address "$ADDRESS"
chipcoin --network mainnet --data "$DB" mining-history --address "$ADDRESS" --limit 20
chipcoin --network mainnet --data "$DB" public-peers

Local database does not mean remote RPC.

Most CLI reads open a local SQLite database; --data is not a URL and a typo can create a new empty database. submit-raw-tx --node-url and wallet-send --node-url are explicit HTTP submission paths. The CLI does not offer a generic remote --rpc-url flag.

Full CLI catalog

All 70 top-level commands are included below for discoverability. Listing a command is not a recommendation to run it on Mainnet: test helpers, legacy registration and state-changing operations are flagged separately.

Read chain and address data 21 commands

Mainnet reads; use the existing node database. Address and reward summaries require --address.

statusNo required command arguments
usage: chipcoin status [-h]

options:
  -h, --help  show this help message and exit
tipNo required command arguments
usage: chipcoin tip [-h]

options:
  -h, --help  show this help message and exit
blockNo required command arguments
usage: chipcoin block [-h] (--height HEIGHT | --hash HASH)

options:
  -h, --help       show this help message and exit
  --height HEIGHT
  --hash HASH
txRequired: txid
usage: chipcoin tx [-h] txid

positional arguments:
  txid

options:
  -h, --help  show this help message and exit
mempoolNo required command arguments
usage: chipcoin mempool [-h]

options:
  -h, --help  show this help message and exit
utxosRequired: --address
usage: chipcoin utxos [-h] --address ADDRESS

options:
  -h, --help         show this help message and exit
  --address ADDRESS
balanceRequired: --address
usage: chipcoin balance [-h] --address ADDRESS

options:
  -h, --help         show this help message and exit
  --address ADDRESS
address-historyRequired: --address
usage: chipcoin address-history [-h] --address ADDRESS [--limit LIMIT]
                                [--ascending]

options:
  -h, --help         show this help message and exit
  --address ADDRESS
  --limit LIMIT
  --ascending
chain-windowRequired: --start, --end
usage: chipcoin chain-window [-h] --start START --end END

options:
  -h, --help     show this help message and exit
  --start START
  --end END
difficultyNo required command arguments
usage: chipcoin difficulty [-h]

options:
  -h, --help  show this help message and exit
retarget-infoNo required command arguments
usage: chipcoin retarget-info [-h]

options:
  -h, --help  show this help message and exit
supplyNo required command arguments
usage: chipcoin supply [-h]

options:
  -h, --help  show this help message and exit
supply-diagnosticsNo required command arguments
usage: chipcoin supply-diagnostics [-h]

options:
  -h, --help  show this help message and exit
economy-summaryNo required command arguments
usage: chipcoin economy-summary [-h]

options:
  -h, --help  show this help message and exit
reward-historyRequired: --address
usage: chipcoin reward-history [-h] --address ADDRESS [--limit LIMIT]
                               [--ascending] [--start-height START_HEIGHT]
                               [--end-height END_HEIGHT]

options:
  -h, --help            show this help message and exit
  --address ADDRESS
  --limit LIMIT
  --ascending
  --start-height START_HEIGHT
  --end-height END_HEIGHT
reward-summaryRequired: --address
usage: chipcoin reward-summary [-h] --address ADDRESS
                               [--start-height START_HEIGHT]
                               [--end-height END_HEIGHT]

options:
  -h, --help            show this help message and exit
  --address ADDRESS
  --start-height START_HEIGHT
  --end-height END_HEIGHT
mining-historyRequired: --address
usage: chipcoin mining-history [-h] --address ADDRESS [--limit LIMIT]
                               [--ascending]

options:
  -h, --help         show this help message and exit
  --address ADDRESS
  --limit LIMIT
  --ascending
node-income-summaryNo required command arguments
usage: chipcoin node-income-summary [-h] [--node-id NODE_ID]
                                    [--address ADDRESS]

options:
  -h, --help         show this help message and exit
  --node-id NODE_ID
  --address ADDRESS
top-minersNo required command arguments
usage: chipcoin top-miners [-h] [--limit LIMIT]

options:
  -h, --help     show this help message and exit
  --limit LIMIT
top-nodesNo required command arguments
usage: chipcoin top-nodes [-h] [--limit LIMIT]

options:
  -h, --help     show this help message and exit
  --limit LIMIT
top-recipientsNo required command arguments
usage: chipcoin top-recipients [-h] [--limit LIMIT]

options:
  -h, --help     show this help message and exit
  --limit LIMIT

The help below each command is extracted from the reviewed Core parser. The installed release's --help remains authoritative.

Node operation and peers 11 commands

Operator commands, not public web endpoints. start/run/sync and peer changes can modify local state.

startNo required command arguments
usage: chipcoin start [-h]

options:
  -h, --help  show this help message and exit
runNo required command arguments
usage: chipcoin run [-h] [--listen-host LISTEN_HOST]
                    [--listen-port LISTEN_PORT] [--http-host HTTP_HOST]
                    [--http-port HTTP_PORT] [--snapshot-file SNAPSHOT_FILE]
                    [--snapshot-reset]
                    [--snapshot-trust-mode {off,warn,enforce}]
                    [--snapshot-trusted-key SNAPSHOT_TRUSTED_KEY]
                    [--snapshot-trusted-keys-file SNAPSHOT_TRUSTED_KEYS_FILE]
                    [--peer PEER] [--peer-source {manual,seed}]
                    [--run-seconds RUN_SECONDS]
                    [--connect-interval-seconds CONNECT_INTERVAL_SECONDS]
                    [--ping-interval-seconds PING_INTERVAL_SECONDS]
                    [--read-timeout-seconds READ_TIMEOUT_SECONDS]
                    [--write-timeout-seconds WRITE_TIMEOUT_SECONDS]
                    [--handshake-timeout-seconds HANDSHAKE_TIMEOUT_SECONDS]
                    [--mempool-relay-interval-seconds MEMPOOL_RELAY_INTERVAL_SECONDS]
                    [--sync-scheduler-interval-seconds SYNC_SCHEDULER_INTERVAL_SECONDS]
                    [--peer-resolution-cache-ttl-seconds PEER_RESOLUTION_CACHE_TTL_SECONDS]
                    [--peer-discovery-enabled PEER_DISCOVERY_ENABLED]
                    [--peerbook-max-size PEERBOOK_MAX_SIZE]
                    [--peer-addr-max-per-message PEER_ADDR_MAX_PER_MESSAGE]
                    [--peer-addr-relay-limit-per-interval PEER_ADDR_RELAY_LIMIT_PER_INTERVAL]
                    [--peer-addr-relay-interval-seconds PEER_ADDR_RELAY_INTERVAL_SECONDS]
                    [--peer-stale-after-seconds PEER_STALE_AFTER_SECONDS]
                    [--peer-retry-backoff-base-seconds PEER_RETRY_BACKOFF_BASE_SECONDS]
                    [--peer-retry-backoff-max-seconds PEER_RETRY_BACKOFF_MAX_SECONDS]
                    [--max-outbound-sessions MAX_OUTBOUND_SESSIONS]
                    [--max-inbound-sessions MAX_INBOUND_SESSIONS]
                    [--max-pending-handshakes MAX_PENDING_HANDSHAKES]
                    [--max-pending-handshakes-per-ip MAX_PENDING_HANDSHAKES_PER_IP]
                    [--max-peer-aliases-per-node-id MAX_PEER_ALIASES_PER_NODE_ID]
                    [--inbound-handshake-rate-limit-per-minute INBOUND_HANDSHAKE_RATE_LIMIT_PER_MINUTE]
                    [--memory-metrics-interval-seconds MEMORY_METRICS_INTERVAL_SECONDS]
                    [--tracemalloc-enabled TRACEMALLOC_ENABLED]
                    [--tracemalloc-top-limit TRACEMALLOC_TOP_LIMIT]
                    [--min-stable-session-seconds MIN_STABLE_SESSION_SECONDS]
                    [--peer-discovery-startup-prefer-persisted PEER_DISCOVERY_STARTUP_PREFER_PERSISTED]
                    [--headers-sync-enabled HEADERS_SYNC_ENABLED]
                    [--headers-max-per-message HEADERS_MAX_PER_MESSAGE]
                    [--block-download-window-size BLOCK_DOWNLOAD_WINDOW_SIZE]
                    [--block-max-inflight-per-peer BLOCK_MAX_INFLIGHT_PER_PEER]
                    [--block-request-timeout-seconds BLOCK_REQUEST_TIMEOUT_SECONDS]
                    [--headers-sync-parallel-peers HEADERS_SYNC_PARALLEL_PEERS]
                    [--headers-sync-start-height-gap-threshold HEADERS_SYNC_START_HEIGHT_GAP_THRESHOLD]
                    [--misbehavior-warning-threshold MISBEHAVIOR_WARNING_THRESHOLD]
                    [--misbehavior-disconnect-threshold MISBEHAVIOR_DISCONNECT_THRESHOLD]
                    [--misbehavior-ban-threshold MISBEHAVIOR_BAN_THRESHOLD]
                    [--misbehavior-ban-duration-seconds MISBEHAVIOR_BAN_DURATION_SECONDS]
                    [--misbehavior-decay-interval-seconds MISBEHAVIOR_DECAY_INTERVAL_SECONDS]
                    [--misbehavior-decay-step MISBEHAVIOR_DECAY_STEP]

options:
  -h, --help            show this help message and exit
  --listen-host LISTEN_HOST
  --listen-port LISTEN_PORT
  --http-host HTTP_HOST
  --http-port HTTP_PORT
  --snapshot-file SNAPSHOT_FILE
                        Optional local snapshot file for fast bootstrap.
  --snapshot-reset      Replace existing local chain state when importing a
                        snapshot.
  --snapshot-trust-mode {off,warn,enforce}
  --snapshot-trusted-key SNAPSHOT_TRUSTED_KEY
                        Trusted Ed25519 signer public key hex for snapshot
                        verification.
  --snapshot-trusted-keys-file SNAPSHOT_TRUSTED_KEYS_FILE
                        Path to a text or JSON file containing trusted Ed25519
                        signer public keys.
  --peer PEER           Outbound peer in host:port form.
  --peer-source {manual,seed}
  --run-seconds RUN_SECONDS
                        Stop automatically after N seconds.
  --connect-interval-seconds CONNECT_INTERVAL_SECONDS
  --ping-interval-seconds PING_INTERVAL_SECONDS
  --read-timeout-seconds READ_TIMEOUT_SECONDS
  --write-timeout-seconds WRITE_TIMEOUT_SECONDS
  --handshake-timeout-seconds HANDSHAKE_TIMEOUT_SECONDS
  --mempool-relay-interval-seconds MEMPOOL_RELAY_INTERVAL_SECONDS
  --sync-scheduler-interval-seconds SYNC_SCHEDULER_INTERVAL_SECONDS
  --peer-resolution-cache-ttl-seconds PEER_RESOLUTION_CACHE_TTL_SECONDS
  --peer-discovery-enabled PEER_DISCOVERY_ENABLED
  --peerbook-max-size PEERBOOK_MAX_SIZE
  --peer-addr-max-per-message PEER_ADDR_MAX_PER_MESSAGE
  --peer-addr-relay-limit-per-interval PEER_ADDR_RELAY_LIMIT_PER_INTERVAL
  --peer-addr-relay-interval-seconds PEER_ADDR_RELAY_INTERVAL_SECONDS
  --peer-stale-after-seconds PEER_STALE_AFTER_SECONDS
  --peer-retry-backoff-base-seconds PEER_RETRY_BACKOFF_BASE_SECONDS
  --peer-retry-backoff-max-seconds PEER_RETRY_BACKOFF_MAX_SECONDS
  --max-outbound-sessions MAX_OUTBOUND_SESSIONS
  --max-inbound-sessions MAX_INBOUND_SESSIONS
  --max-pending-handshakes MAX_PENDING_HANDSHAKES
  --max-pending-handshakes-per-ip MAX_PENDING_HANDSHAKES_PER_IP
  --max-peer-aliases-per-node-id MAX_PEER_ALIASES_PER_NODE_ID
  --inbound-handshake-rate-limit-per-minute INBOUND_HANDSHAKE_RATE_LIMIT_PER_MINUTE
  --memory-metrics-interval-seconds MEMORY_METRICS_INTERVAL_SECONDS
  --tracemalloc-enabled TRACEMALLOC_ENABLED
  --tracemalloc-top-limit TRACEMALLOC_TOP_LIMIT
  --min-stable-session-seconds MIN_STABLE_SESSION_SECONDS
  --peer-discovery-startup-prefer-persisted PEER_DISCOVERY_STARTUP_PREFER_PERSISTED
  --headers-sync-enabled HEADERS_SYNC_ENABLED
  --headers-max-per-message HEADERS_MAX_PER_MESSAGE
  --block-download-window-size BLOCK_DOWNLOAD_WINDOW_SIZE
  --block-max-inflight-per-peer BLOCK_MAX_INFLIGHT_PER_PEER
  --block-request-timeout-seconds BLOCK_REQUEST_TIMEOUT_SECONDS
  --headers-sync-parallel-peers HEADERS_SYNC_PARALLEL_PEERS
  --headers-sync-start-height-gap-threshold HEADERS_SYNC_START_HEIGHT_GAP_THRESHOLD
  --misbehavior-warning-threshold MISBEHAVIOR_WARNING_THRESHOLD
  --misbehavior-disconnect-threshold MISBEHAVIOR_DISCONNECT_THRESHOLD
  --misbehavior-ban-threshold MISBEHAVIOR_BAN_THRESHOLD
  --misbehavior-ban-duration-seconds MISBEHAVIOR_BAN_DURATION_SECONDS
  --misbehavior-decay-interval-seconds MISBEHAVIOR_DECAY_INTERVAL_SECONDS
  --misbehavior-decay-step MISBEHAVIOR_DECAY_STEP
operator-checkNo required command arguments
usage: chipcoin operator-check [-h] [--json] [--reward-node-id REWARD_NODE_ID]
                               [--node-url NODE_URL]
                               [--miner-payout-address MINER_PAYOUT_ADDRESS]
                               [--snapshot-manifest-url SNAPSHOT_MANIFEST_URL]
                               [--request-timeout-seconds REQUEST_TIMEOUT_SECONDS]

options:
  -h, --help            show this help message and exit
  --json                Emit stable machine-readable JSON.
  --reward-node-id REWARD_NODE_ID
                        Require a specific reward node to be registered and
                        eligible.
  --node-url NODE_URL   Optional HTTP node API URL for remote mining template
                        checks.
  --miner-payout-address MINER_PAYOUT_ADDRESS
                        Optional payout address used for mining template
                        checks.
  --snapshot-manifest-url SNAPSHOT_MANIFEST_URL
                        Optional snapshot manifest URL to verify. Defaults to
                        NODE_SNAPSHOT_MANIFEST_URLS when set.
  --request-timeout-seconds REQUEST_TIMEOUT_SECONDS
syncRequired: --peer-data
usage: chipcoin sync [-h] --peer-data PEER_DATA

options:
  -h, --help            show this help message and exit
  --peer-data PEER_DATA
                        Path to a peer SQLite data file.
add-peerRequired: host, port
usage: chipcoin add-peer [-h] host port

positional arguments:
  host
  port

options:
  -h, --help  show this help message and exit
remove-peerRequired: host, port
usage: chipcoin remove-peer [-h] host port

positional arguments:
  host
  port

options:
  -h, --help  show this help message and exit
list-peersNo required command arguments
usage: chipcoin list-peers [-h]

options:
  -h, --help  show this help message and exit
peer-detailRequired: --node-id
usage: chipcoin peer-detail [-h] --node-id NODE_ID

options:
  -h, --help         show this help message and exit
  --node-id NODE_ID
peer-summaryNo required command arguments
usage: chipcoin peer-summary [-h]

options:
  -h, --help  show this help message and exit
public-peersNo required command arguments
usage: chipcoin public-peers [-h] [--diagnostics]

options:
  -h, --help     show this help message and exit
  --diagnostics
peerbook-cleanNo required command arguments
usage: chipcoin peerbook-clean [-h] [--reset-penalties] [--dry-run]

options:
  -h, --help         show this help message and exit
  --reset-penalties
  --dry-run

The help below each command is extracted from the reviewed Core parser. The installed release's --help remains authoritative.

Wallet and transaction tools 8 commands

Local keys only. wallet-generate prints secret material; wallet-import is the legacy private-key import path, not a general Mainnet PQ seed importer. wallet-build signs; wallet-send and submit-raw-tx submit transactions.

wallet-generateRequired: --wallet-file
usage: chipcoin wallet-generate [-h] --wallet-file WALLET_FILE
                                [--scheme {secp256k1,mldsa44}]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --scheme {secp256k1,mldsa44}
wallet-importRequired: --wallet-file
usage: chipcoin wallet-import [-h] --wallet-file WALLET_FILE
                              (--private-key-hex PRIVATE_KEY_HEX | --private-key-file PRIVATE_KEY_FILE | --private-key-stdin)
                              [--quiet]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --private-key-hex PRIVATE_KEY_HEX
  --private-key-file PRIVATE_KEY_FILE
                        Protected file containing one private key in hex;
                        avoid passing key material in argv.
  --private-key-stdin   Read one private key in hex from non-interactive
                        stdin.
  --quiet               Suppress imported private-key JSON output.
wallet-addressRequired: --wallet-file
usage: chipcoin wallet-address [-h] --wallet-file WALLET_FILE

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
wallet-utxosRequired: --wallet-file
usage: chipcoin wallet-utxos [-h] --wallet-file WALLET_FILE

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
wallet-balanceRequired: --wallet-file
usage: chipcoin wallet-balance [-h] --wallet-file WALLET_FILE

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
wallet-buildRequired: --wallet-file, --to, --amount, --fee
usage: chipcoin wallet-build [-h] --wallet-file WALLET_FILE --to TO --amount
                             AMOUNT --fee FEE
                             [--change-address CHANGE_ADDRESS]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --to TO
  --amount AMOUNT
  --fee FEE
  --change-address CHANGE_ADDRESS
wallet-sendRequired: --wallet-file, --to, --amount, --fee
usage: chipcoin wallet-send [-h] --wallet-file WALLET_FILE --to TO --amount
                            AMOUNT --fee FEE [--change-address CHANGE_ADDRESS]
                            [--connect CONNECT] [--node-url NODE_URL]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --to TO
  --amount AMOUNT
  --fee FEE
  --change-address CHANGE_ADDRESS
  --connect CONNECT     Optional node endpoint in host:port form for P2P
                        submission.
  --node-url NODE_URL   Optional node HTTP API base URL for transaction
                        submission.
submit-raw-txRequired: --node-url, raw_hex
usage: chipcoin submit-raw-tx [-h] --node-url NODE_URL raw_hex

positional arguments:
  raw_hex

options:
  -h, --help           show this help message and exit
  --node-url NODE_URL  Node HTTP endpoint, for example http://127.0.0.1:8081

The help below each command is extracted from the reviewed Core parser. The installed release's --help remains authoritative.

Reward-node lifecycle and diagnostics 19 commands

Read diagnostics first. Registration, renewal, attestation and settlement submissions are specialized operator workflows with fees, eligibility rules and cryptographic requirements. Legacy register-node/renew-node are not the Mainnet PQ reward-node registration path.

node-registryNo required command arguments
usage: chipcoin node-registry [-h]

options:
  -h, --help  show this help message and exit
next-winnersNo required command arguments
usage: chipcoin next-winners [-h]

options:
  -h, --help  show this help message and exit
register-nodeRequired: --wallet-file, --node-id, --payout-address
usage: chipcoin register-node [-h] --wallet-file WALLET_FILE --node-id NODE_ID
                              --payout-address PAYOUT_ADDRESS
                              [--connect CONNECT]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --node-id NODE_ID
  --payout-address PAYOUT_ADDRESS
  --connect CONNECT
renew-nodeRequired: --wallet-file, --node-id
usage: chipcoin renew-node [-h] --wallet-file WALLET_FILE --node-id NODE_ID
                           [--connect CONNECT]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --node-id NODE_ID
  --connect CONNECT
register-reward-nodeRequired: --wallet-file, --node-id, --payout-address, --node-pubkey-hex, --declared-host, --declared-port
usage: chipcoin register-reward-node [-h] --wallet-file WALLET_FILE --node-id
                                     NODE_ID --payout-address PAYOUT_ADDRESS
                                     --node-pubkey-hex NODE_PUBKEY_HEX
                                     --declared-host DECLARED_HOST
                                     --declared-port DECLARED_PORT
                                     [--connect CONNECT]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --node-id NODE_ID
  --payout-address PAYOUT_ADDRESS
  --node-pubkey-hex NODE_PUBKEY_HEX
  --declared-host DECLARED_HOST
  --declared-port DECLARED_PORT
  --connect CONNECT
renew-reward-nodeRequired: --wallet-file, --node-id, --declared-host, --declared-port
usage: chipcoin renew-reward-node [-h] --wallet-file WALLET_FILE --node-id
                                  NODE_ID --declared-host DECLARED_HOST
                                  --declared-port DECLARED_PORT
                                  [--connect CONNECT]

options:
  -h, --help            show this help message and exit
  --wallet-file WALLET_FILE
  --node-id NODE_ID
  --declared-host DECLARED_HOST
  --declared-port DECLARED_PORT
  --connect CONNECT
reward-epoch-seedNo required command arguments
usage: chipcoin reward-epoch-seed [-h] [--epoch-index EPOCH_INDEX]

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
reward-epoch-stateNo required command arguments
usage: chipcoin reward-epoch-state [-h] [--epoch-index EPOCH_INDEX]
                                   [--node-id NODE_ID]

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
  --node-id NODE_ID
reward-assignmentsNo required command arguments
usage: chipcoin reward-assignments [-h] [--epoch-index EPOCH_INDEX]
                                   [--node-id NODE_ID]

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
  --node-id NODE_ID
reward-node-statusRequired: --node-id
usage: chipcoin reward-node-status [-h] --node-id NODE_ID
                                   [--epoch-index EPOCH_INDEX]

options:
  -h, --help            show this help message and exit
  --node-id NODE_ID
  --epoch-index EPOCH_INDEX
reward-node-feesNo required command arguments
usage: chipcoin reward-node-fees [-h]

options:
  -h, --help  show this help message and exit
reward-epoch-summaryRequired: --epoch-index
usage: chipcoin reward-epoch-summary [-h] --epoch-index EPOCH_INDEX

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
reward-attestationsNo required command arguments
usage: chipcoin reward-attestations [-h] [--epoch-index EPOCH_INDEX]

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
reward-attestation-backlogNo required command arguments
usage: chipcoin reward-attestation-backlog [-h]

options:
  -h, --help  show this help message and exit
reward-settlementsNo required command arguments
usage: chipcoin reward-settlements [-h] [--epoch-index EPOCH_INDEX]

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
reward-settlement-previewNo required command arguments
usage: chipcoin reward-settlement-preview [-h] [--epoch-index EPOCH_INDEX]

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
reward-settlement-reportNo required command arguments
usage: chipcoin reward-settlement-report [-h] [--epoch-index EPOCH_INDEX]

options:
  -h, --help            show this help message and exit
  --epoch-index EPOCH_INDEX
submit-reward-attestation-bundleRequired: --bundle-file
usage: chipcoin submit-reward-attestation-bundle [-h] --bundle-file
                                                 BUNDLE_FILE
                                                 [--wallet-file WALLET_FILE]
                                                 [--connect CONNECT]

options:
  -h, --help            show this help message and exit
  --bundle-file BUNDLE_FILE
  --wallet-file WALLET_FILE
  --connect CONNECT
submit-reward-settle-epochRequired: --settlement-file
usage: chipcoin submit-reward-settle-epoch [-h] --settlement-file
                                           SETTLEMENT_FILE [--connect CONNECT]

options:
  -h, --help            show this help message and exit
  --settlement-file SETTLEMENT_FILE
  --connect CONNECT

The help below each command is extracted from the reviewed Core parser. The installed release's --help remains authoritative.

Mining and snapshots 5 commands

mine is an external miner client; mine-local-block is a local/testing helper, not a production pool setup. Snapshot import/reset changes chain state: use the Mainnet operator runbook and a separately verified trust anchor.

mineRequired: --miner-address
usage: chipcoin mine [-h] [--node-url NODE_URL] [--run-seconds RUN_SECONDS]
                     [--max-accepted-blocks MAX_ACCEPTED_BLOCKS]
                     --miner-address MINER_ADDRESS [--miner-id MINER_ID]
                     [--polling-interval-seconds POLLING_INTERVAL_SECONDS]
                     [--request-timeout-seconds REQUEST_TIMEOUT_SECONDS]
                     [--nonce-batch-size NONCE_BATCH_SIZE]
                     [--worker-count WORKER_COUNT]
                     [--template-refresh-skew-seconds TEMPLATE_REFRESH_SKEW_SECONDS]
                     [--mining-min-interval-seconds MINING_MIN_INTERVAL_SECONDS]

options:
  -h, --help            show this help message and exit
  --node-url NODE_URL   Mining node HTTP endpoint. Repeat the flag to
                        configure failover nodes.
  --run-seconds RUN_SECONDS
                        Stop automatically after N seconds.
  --max-accepted-blocks MAX_ACCEPTED_BLOCKS
                        Stop after this many accepted blocks. Intended for
                        controlled operations.
  --miner-address MINER_ADDRESS
                        Mining reward payout address.
  --miner-id MINER_ID   Stable miner identifier used in template requests.
  --polling-interval-seconds POLLING_INTERVAL_SECONDS
  --request-timeout-seconds REQUEST_TIMEOUT_SECONDS
  --nonce-batch-size NONCE_BATCH_SIZE
  --worker-count WORKER_COUNT
                        Number of local mining worker processes.
  --template-refresh-skew-seconds TEMPLATE_REFRESH_SKEW_SECONDS
  --mining-min-interval-seconds MINING_MIN_INTERVAL_SECONDS
                        Optional local throttle between mined blocks. Does not
                        change consensus.
mine-local-blockRequired: --payout-address
usage: chipcoin mine-local-block [-h] --payout-address PAYOUT_ADDRESS

options:
  -h, --help            show this help message and exit
  --payout-address PAYOUT_ADDRESS
snapshot-exportRequired: --snapshot-file
usage: chipcoin snapshot-export [-h] --snapshot-file SNAPSHOT_FILE
                                [--snapshot-format {v1,v2,v3}]

options:
  -h, --help            show this help message and exit
  --snapshot-file SNAPSHOT_FILE
  --snapshot-format {v1,v2,v3}
snapshot-importRequired: --snapshot-file
usage: chipcoin snapshot-import [-h] --snapshot-file SNAPSHOT_FILE
                                [--snapshot-reset]
                                [--snapshot-trust-mode {off,warn,enforce}]
                                [--snapshot-trusted-key SNAPSHOT_TRUSTED_KEY]
                                [--snapshot-trusted-keys-file SNAPSHOT_TRUSTED_KEYS_FILE]

options:
  -h, --help            show this help message and exit
  --snapshot-file SNAPSHOT_FILE
  --snapshot-reset
  --snapshot-trust-mode {off,warn,enforce}
  --snapshot-trusted-key SNAPSHOT_TRUSTED_KEY
                        Trusted Ed25519 signer public key hex for snapshot
                        verification.
  --snapshot-trusted-keys-file SNAPSHOT_TRUSTED_KEYS_FILE
                        Path to a text or JSON file containing trusted Ed25519
                        signer public keys.
snapshot-signRequired: --snapshot-file, --private-key-file
usage: chipcoin snapshot-sign [-h] --snapshot-file SNAPSHOT_FILE
                              --private-key-file PRIVATE_KEY_FILE

options:
  -h, --help            show this help message and exit
  --snapshot-file SNAPSHOT_FILE
  --private-key-file PRIVATE_KEY_FILE
                        Protected file containing one raw 32-byte Ed25519
                        private key in hex.

The help below each command is extracted from the reviewed Core parser. The installed release's --help remains authoritative.

PQ diagnostics and isolated test tools 6 commands

pq-operational-readiness can inspect Mainnet with explicit options. verify-pq-activation has its own --network flag defaulting to testnet: pass mainnet after the subcommand too. Smoke, benchmark, rehearsal and audit tools are not production transaction workflows; never aim isolated test tooling at the live database.

pq-smokeNo required command arguments
usage: chipcoin pq-smoke [-h] [--activation-height ACTIVATION_HEIGHT]
                         [--keep-state] [--json] [--verbose]

options:
  -h, --help            show this help message and exit
  --activation-height ACTIVATION_HEIGHT
  --keep-state
  --json
  --verbose
pq-benchmarkNo required command arguments
usage: chipcoin pq-benchmark [-h] [--json] [--quick]

options:
  -h, --help  show this help message and exit
  --json
  --quick
pq-audit-reportNo required command arguments
usage: chipcoin pq-audit-report [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json
pq-dress-rehearsalNo required command arguments
usage: chipcoin pq-dress-rehearsal [-h]
                                   [--activation-height ACTIVATION_HEIGHT]
                                   [--output-json OUTPUT_JSON]
                                   [--output-markdown OUTPUT_MARKDOWN]
                                   [--skip-subprocess-checks]
                                   [--skip-browser-checks] [--json]
                                   [--verbose]

options:
  -h, --help            show this help message and exit
  --activation-height ACTIVATION_HEIGHT
  --output-json OUTPUT_JSON
  --output-markdown OUTPUT_MARKDOWN
  --skip-subprocess-checks
  --skip-browser-checks
  --json
  --verbose
pq-operational-readinessNo required command arguments
usage: chipcoin pq-operational-readiness [-h] [--json] [--html HTML]
                                         [--output OUTPUT]
                                         [--markdown MARKDOWN]
                                         [--output-dir OUTPUT_DIR]
                                         [--api-url API_URL]
                                         [--timeout TIMEOUT] [--no-network]
                                         [--strict] [--compact]
                                         [--config CONFIG]
                                         [--block-interval-window BLOCK_INTERVAL_WINDOW]
                                         [--run-local-checks] [--html-stdout]
                                         [--markdown-stdout] [--verbose]

options:
  -h, --help            show this help message and exit
  --json
  --html HTML
  --output OUTPUT
  --markdown MARKDOWN
  --output-dir OUTPUT_DIR
  --api-url API_URL
  --timeout TIMEOUT
  --no-network
  --strict
  --compact
  --config CONFIG
  --block-interval-window BLOCK_INTERVAL_WINDOW
  --run-local-checks
  --html-stdout
  --markdown-stdout
  --verbose
verify-pq-activationNo required command arguments
usage: chipcoin verify-pq-activation [-h] [--network VERIFY_NETWORK]
                                     [--expected-height EXPECTED_HEIGHT]
                                     [--json]

options:
  -h, --help            show this help message and exit
  --network VERIFY_NETWORK
  --expected-height EXPECTED_HEIGHT
  --json

The help below each command is extracted from the reviewed Core parser. The installed release's --help remains authoritative.

Create a Mainnet PQ wallet, locally

bash
# Local signing machine only. Do not overwrite an existing wallet.
umask 077
chipcoin --network mainnet wallet-generate --scheme mldsa44 \
  --wallet-file ./mainnet-wallet.json > /dev/null
chipcoin --network mainnet wallet-address --wallet-file ./mainnet-wallet.json
# Protect this file and its backups. Never upload it to an API or website.

Secret-output warning: wallet-generate writes a wallet file and prints secret key material to stdout. The example discards stdout, but the file remains highly sensitive. Protect backups, avoid shell tracing and terminal recording, and never run this through a web shell or CI logs. Native signing/backend availability depends on your supported installation.

Reward-node registration requires register-reward-node with a wallet, node ID, payout address, node public key and declared host/port. Renewal requires renew-reward-node with its own required fields. Follow Node Rewards and the installed command's --help; these are not “register any address and earn” APIs.

07 / Transaction lifecycle

Build locally. Review. Submit explicitly.

  1. Verify the Mainnet provider identity and obtain mature, unspent outputs for your CHCQ wallet.
  2. Build and sign with a Mainnet-compatible Core wallet or signer. Keep keys and seeds local; do not invent a transaction encoding.
  3. Review recipient, amount, change, fee, network and every input. wallet-build signs but does not broadcast.
  4. Only after approval, send the signed raw_hex to POST /v1/tx/submit or use submit-raw-tx with an explicit node URL.
  5. Track the txid until it is included in the active chain. An accepted response is mempool acceptance, not irreversible payment.
bash
# EXAMPLE ONLY: signs a real transaction if valid funded inputs are present.
# Use a trusted local Mainnet state and a secured signing environment.
# Amount and fee are INTEGER CHIPBITS, not CHC.
DB='/absolute/path/to/your/mainnet-node.sqlite3'
WALLET='/secure/path/to/mainnet-wallet.json'
RECIPIENT='RECIPIENT_MAINNET_CHCQ_ADDRESS'

chipcoin --network mainnet --data "$DB" wallet-build \
  --wallet-file "$WALLET" --to "$RECIPIENT" \
  --amount 100000000 --fee 10000
# 100000000 chipbits = 1 CHC. Fee 10000 is illustrative, not a fee recommendation.
# Inspect all outputs, change and fee before choosing to broadcast.
bash
# BROADCASTS TO MAINNET. Run only after reviewing your signed transaction.
# Set RAW_HEX to serialized transaction hex produced by a compatible signer.
curl --fail-with-body --max-time 15 \
  'https://mainnet-api.chipcoinprotocol.com/v1/tx/submit' \
  -H 'Content-Type: application/json' \
  --data-binary "{\"raw_hex\":\"$RAW_HEX\"}"

Core accepts at most 200,000 hex characters for submitted raw transactions and a 262,144-byte submission JSON body; intermediaries can impose stricter limits. Validation enforces network consensus, maturity, signatures and fees. Do not split a signed transaction into multiple requests or change it after signing.

If a submission times out, query the same txid before retrying. A retry of the same bytes can encounter an already-known transaction; a newly built payment can cause a double payment. Mempool eviction, reorgs and transaction absence must be handled explicitly.

08 / Wallet and signed sessions

Connect is not authentication. Login is not spending.

The current extension exposes chipcoin_connect, chipcoin_getAddress and chipcoin_signMessage via window.chipcoin.request. Mainnet login uses scheme 10. Its release manifest currently injects the provider only on https://chipcoinprotocol.com/*, not on arbitrary dApp domains.

javascript
// Run on https://chipcoinprotocol.com with the supported extension installed.
// This is the site's existing flow, NOT a cross-origin auth API for other sites.
async function signedMainnetLogin() {
  if (!window.chipcoin?.request) throw new Error("Install/unlock a compatible wallet");
  const { address } = await window.chipcoin.request({ method: "chipcoin_connect" });
  async function post(path, body) {
    const response = await fetch(path, {
      method: "POST",
      credentials: "same-origin",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body)
    });
    const data = await response.json();
    if (!response.ok || !data.ok) throw new Error(data.error_code || "Login failed");
    return data;
  }
  const challenge = await post("/auth/challenge", {
    address, signature_scheme: 10, network: "mainnet"
  });
  const signed = await window.chipcoin.request({
    method: "chipcoin_signMessage",
    params: { message: challenge.message, domain: "chipcoinprotocol.com" }
  });
  if (signed.address !== address || signed.message !== challenge.message ||
      signed.signature_scheme !== 10) throw new Error("Signing response mismatch");
  return post("/auth/verify", {
    challenge_id: challenge.challenge_id,
    address, network: "mainnet",
    signature_scheme: signed.signature_scheme,
    public_key: signed.public_key,
    signature: signed.signature,
    message: challenge.message
  });
}
// User approval is required. Never call this automatically on page load.

The wallet signs the exact canonical challenge, with SHA-256(UTF-8("chipcoin:web-auth:v2:chipcoin-mainnet-1") || 0x00 || UTF-8(message)). The null separator is a real byte. This domain is separate from transaction signing; do not reconstruct or normalize the challenge text.

Backend verification must bind address, public key, signature scheme, network, real origin/domain, expiry and single-use nonce atomically before issuing an opaque secure session. Use HttpOnly/Secure/SameSite cookies, CSRF protection for writes, rate limits and revocation. See Signed Login specification.

For your own application domain

Implement your own audited challenge/session backend and use a wallet release that explicitly supports your origin. Chipcoin's /auth/* endpoints are this site's session API, not a public cross-origin identity service. The provider does not expose signTransaction, sendTransaction, arbitrary-message signing or order signing. Do not repurpose a login signature as approval to trade or spend.

09 / Build something useful

Five realistic application recipes.

Architecture examples are plans for your own application, not claims that an SDK or smart-contract VM exists.

Recipe 1 / Explorer

“I want to build a block explorer.”

Architecture: Mainnet node → backend/indexer → your database and API → browser UI. Poll tip, read block summaries, fetch block details and then full transactions. Expose only the data needed by your frontend; do not publish the whole node API.

python
# Run on YOUR server, with YOUR local node HTTP listener.
# Example: export NODE_URL=http://127.0.0.1:YOUR_CONFIGURED_PORT
import json
import os
from urllib.parse import urlencode
from urllib.request import urlopen

base = os.environ["NODE_URL"].rstrip("/")
def read(path):
    with urlopen(base + path, timeout=15) as response:
        return json.load(response)

health = read("/v1/health")
assert health["network"] == "mainnet"
assert health["chain_id"] == "chipcoin-mainnet-1"
assert health["genesis_hash"] == (
    "00000238ef41c47992581c18fad544b4e24ecf1e79e7ffed629a215def4a337f"
)
tip = read("/v1/tip")
rows = read("/v1/blocks?" + urlencode({
    "limit": 20, "from_height": tip["height"]
}))
for summary in rows:
    block = read("/v1/block?" + urlencode({"height": summary["height"]}))
    print(block["height"], block["block_hash"], block["transaction_count"])

# For the next OLDER page use min(row["height"] for row in rows) - 1.
# Stop at height 0; do not request from_height=-1.
# This is a bounded read example, not a production indexer.
  1. Index confirmed blocks by height and hash, with transaction inputs, outputs and reward classification.
  2. Validate each block's parent hash against the saved active chain. Detect same-height hash changes, find a common ancestor and roll back orphaned rows before replaying.
  3. Maintain your own address index, UTXO view and pagination. Checkpoint atomically; retry bounded reads.
  4. Render Mainnet explorer routes such as #/mainnet/block/HEIGHT, #/mainnet/tx/TXID and #/mainnet/address/ADDRESS according to your frontend router, not as node API paths.

The official explorer proxy is useful for bounded reads, but is not a substitute for your own indexer or a guaranteed bulk ingestion service.

Recipe 2 / Alternative browser wallet or chain browser

“I want an alternative browser interface.”

A read-only chain browser needs address, UTXO, history and tx endpoints plus a reorg-aware backend for full search. A signing wallet additionally needs a locally protected key vault, secure approvals, Mainnet ML-DSA-44 signing and the exact Core transaction serialization.

  • Use the JavaScript balance reader above as a read-only starting point.
  • For an extension wallet, isolate the page provider, content script and signing background; derive the real requesting origin from browser metadata, not message text.
  • Use the public API only for reads and already-signed submissions. Never send a seed, private key or wallet file to it.
  • Handle wallet lock, user rejection, unsupported networks, maturity, change, fees and recovery. Use the upstream browser wallet source as a reference, not an audited turnkey SDK.
Recipe 3 / Payments and membership app

“I want a small application that accepts CHC.”

  1. Create an invoice with an exact integer amount and a unique payout address or a carefully tracked invoice/address mapping.
  2. Use your indexer's confirmed outputs to match recipient and amount. Do not trust a client-supplied txid or a login address alone as payment proof.
  3. Store block hash/height and a unique outpoint (txid, vout); enforce idempotent crediting and your own confirmation policy.
  4. Keep pending, confirmed and reversed states. A reorg can remove a payment; a mempool entry is not a receipt.

Signed login can authorize application settings only where the origin and wallet support it. Application state, permissions and subscriptions live in your backend, not in a Chipcoin smart contract.

Recipe 4 / Reward-node dashboard

“I want a mining or node-operator dashboard.”

For public address activity, use explicit reward amounts from history. For operator details, combine local /v1/rewards/node-status?node_id=..., node fees, epoch summaries and settlement reports. The CLI adds mining-history, reward-summary --address and node-income-summary --node-id.

Keep recent-window totals separate from lifetime indexed totals. A registered node is not automatically eligible, a settlement report is not necessarily a wallet payout, and a public address is not proof of node ownership.

Recipe 5 / Exchange prototype and dApp boundaries

“Can I build a small DEX?”

Not a trustless AMM or arbitrary smart-contract DEX with the interfaces documented here. The reviewed Core has native transfers and specialized reward-node transactions; it does not expose an EVM, contract deployment/execution, token issuance standard, HTLC swap API or an order-signing provider method. Transaction metadata is not executable contract code.

You can build a read-only market board or off-chain matching prototype. If an operator holds funds or manually settles trades, disclose the custody and trust model; it is not a trustless DEX. Do not assume another chain's token can be settled atomically using two independent CHC payments.

A genuine non-custodial exchange would first need separately specified and audited settlement primitives, supported signing/approval flows and a threat model. That is protocol and wallet work, not a missing frontend endpoint. Keep trading experiments isolated; this handbook does not authorize a Mainnet exchange deployment.

10 / Ship responsibly

A production integration checklist.

Correctness and reliability

  • Pin vetted software and record network, chain ID, genesis hash and reviewed source revision.
  • Use timeouts, low-concurrency polling, caching and exponential backoff with jitter. Do not assume every endpoint is cheap.
  • Check HTTP status and content type before parsing JSON. Handle 400 validation, 403 proxy restrictions, 404 absence, 413 payload limits, 429 backoff and transient 5xx.
  • Handle chain reorgs, stale reads, mempool disappearance and interrupted indexer restarts.
  • Use exact units and avoid duplicate credits, duplicate broadcasts and fixed reward/fee assumptions.

Security and tests

  • Keep node diagnostics private; allowlist routes in your own backend and never expose shell commands or database files.
  • Use textContent/escaping for address labels and metadata; validate identifiers before building URLs.
  • Test locked/missing wallets, rejected approvals, replay, wrong origin, expired challenges and network mismatch.
  • Keep secrets out of analytics, logs, error reports, URLs and browser page context.
  • Test reads locally or with mocks. Mainnet build/sign/broadcast examples require separate human approval; do not run them as documentation smoke tests.

Common mistakes: assuming the public API exposes blocks (it does not); treating explorer CORS as universal; using HTTP history as paginated complete history; running reward-summary without --address; forgetting that verify-pq-activation has a separate network option; or treating wallet connect as authenticated ownership.

11 / Source of truth

Reviewed implementation, not guessed endpoints.

Core revision 31a2a4d531170cbc51671790bd5c1a492ea5c533 was inspected on 17 November 2026. Public access boundaries were checked against the deployed Mainnet wallet and explorer proxy configuration. Installed versions and operator policy can change independently.

The HTTP reference covers every route in the reviewed adapter; the CLI catalog includes all top-level parser commands. Use COMMAND --help for its full flags and release-specific behavior. Source availability is not a claim of a public SLA, audited SDK or third-party domain support.