BitKuruş — Exchange Integration Guide

Audience: exchange operations & engineering teams integrating BK$ for deposits, withdrawals, and balance reconciliation. For general wallet development see wallet-integration.md; this document covers the parts that are specific to running an exchange-side hot/cold wallet.

0. Model summary — read this first

• BK$ is a UTXO-style ledger (like Bitcoin), not an account/nonce model (not like Ethereum). A balance is the sum of a wallet's active tokens (UTXOs).
• Addresses are 64-char lowercase hex Ed25519 public keys. There is no HD/BIP-32 derivation and no destination-tag/memo system — each deposit address is a distinct Ed25519 keypair the exchange must generate and custody.
• Finality is not confirmation-count based. A submitted transaction returns 202 accepted; you poll until it is committed. There is no reorg — once committed, a transaction does not revert.

1. Generating deposit addresses

Generate an Ed25519 keypair per user (or a pooled model with internal attribution) client-side or in your HSM. The public key (64-hex) is the deposit address. The private key stays in your custody system; BitKuruş never sees it.

Because there is no memo/tag, use a unique address per user for clean attribution, or a pooled address with your own off-ledger mapping.

2. Detecting deposits

Poll or subscribe per address:

• GET /api/wallet/{pubkey} → current balance and active tokens (UTXOs).
• GET /api/wallet/{pubkey}/activity → receive/spend history for reconciliation.
• Real-time: Laravel Reverb/Echo websocket notifications (public/bitkurus/wallet-notify.js, config/reverb.php).

Credit a deposit only after the funding transaction is committed (GET /api/tx/{id} → status: committed).

3. Processing withdrawals

A withdrawal is a client-signed transfer. Steps:

1. Select UTXOs for the withdrawal amount from your hot wallet's active tokens (GET /api/wallet/{pubkey}).
2. Plan merge/split. BK$ transfers consume whole tokens and mint new ones (value-conserving). You typically merge inputs then pay. The reference implementation is public/bitkurus/wallet.js (planWalletTransfer, submitPaymentAfterMerge).
3. Sign the canonical-JSON transaction with the address's Ed25519 key.
4. Submit to POST /api/tx/submit → expect 202 accepted.
5. Wait for peer quorum after a merge before spending the merged output — correct signing alone is not enough; see wallet-integration.md §5–6.
6. Poll GET /api/tx/{id} until committed, then mark the withdrawal done.

Operational caution: the UTXO + post-merge-quorum flow is more involved than an account-model coin. Budget engineering time for the merge-then-pay planner and the quorum wait. Test end-to-end against a testnet node first (see the run-a-node docs).

4. Fees & commission

• The user-paid fee_amount (inputs − outputs) is burned. Size your change output accordingly.
• A validator commission (~0.02%) is minted network-side and does not come out of your outputs. See TOKENOMICS.md.

5. Balance reconciliation & proof-of-reserves

• GET /api/ledger/export returns a byte-identical canonical snapshot with a canonical_hash. Pull it from two nodes and diff the hash to confirm the federation agrees.
• Sum your controlled addresses' active tokens for an internal reserve figure; cross-check against GET /api/supply/*.
• The open-source bitkurus-ledger-verifier re-verifies every signature and cross-checks nodes for you.

6. Running your own node (recommended)

For independent verification, run a read-only observer node that mirrors the network without being a validator (docker-compose.observer.yml; see /run-a-node). This lets you serve deposit/withdrawal queries from infrastructure you control rather than trusting a third-party endpoint.

Note: becoming a validator is permissioned — validators are manually allowlisted by existing operators via an out-of-band handshake. An observer node needs only to be listed as a peer to receive replication.

7. Endpoint quick reference

8. Pre-listing checklist

• Observer node running on exchange-controlled infra.
• Deposit address generation + custody wired to your HSM/KMS.
• Deposit detection crediting only on committed.
• Withdrawal signer implements merge-then-pay + post-merge quorum wait.
• Reconciliation job diffing canonical_hash across ≥2 nodes.
• Reviewed TOKENOMICS.md, THREAT_MODEL.md, and compliance.md.