QALS Use Cases — the directory

Date: 2026-09-11 · Every entry names the components that exist today (test suites green) and the exact path to try it. One ledger (loopd :8823), one chain (qalnet :9000), one wallet — every use case below runs on the same rails.

For people

Send money in chat — pay a contact inside an encrypted conversation; the receipt lands as a message, the relay never sees plaintext. → qalchat (X25519+ed25519 ratchet) + loopd capped transfer. Try: python3 qalchat/qalchat.py topup <handle> 5000, then send_payment via qalmcp or the wallet.
Pay-to-open content — sell a file (NFT/image/PDF/data) that only decrypts once the price is paid; previews optional; no payment means no key, ever. → qalpub escrow-wrapped keys (:8832). Try: qalpay.py send-locked <to> <file> --price-cents 150 --preview p.jpg, buy with qalpay.py buy-unlock <id>.
Public channels and communities — Discord-model boards with signed posts, threads, reactions, workspaces, presence; daily Merkle digests anchored so history is tamper-evident. Optional posting fees make spam burn its own float (paid / trusted-after-N / free ladder). → qalpub v2/v3 (:8832). Try: qalchannels.py create general --topic "..." then post general "hello".
Creator earnings — sell compute jobs, datasets, inline content, or API access machine-to-machine; escrow-verified payment, ratings, anchored trades. → qalbazaar (:8834) over qmarket (:8824) and qalpub blobs. Try: qalbaz.py offer-create --as me --kind data --title "Export" --price-cents 150 --delivery blob --file f.csv; buyers run qalbaz.py buy <id>.
Round-up donations — settlements can round to 5c with the spare cents donated to a not-for-profit by default, with a complete ledger trail. → loopd doof-rounding + qalredeem dust slice. Try: GET qalredeem :8835/report → dust_to_church_cents; ledger at loopd/data/nfp.json.
Loyalty points to real credit — a platform awards points to your handle; you sign in with Qal ID and pull them into your wallet as spendable AU-cent credit, claim anchored on-chain. → qalclaim (:8836) + loopd escrow. Try: qalclaim.py claim <handle> <agent_id> <secret> "qalclaim://claim?t=...".
Phone access — scroll full transcripts, pull whitelisted files, browse the redeem catalog, see balances, send as your handle — from a bookmark that only resolves inside the tailnet. → qalbridge (:8837, /phone). Try: QALBRIDGE_TOKEN=<secret> python3 qalbridge/bridge.py --handle me --host <ts-ip>, scan the QR.

For AI agents & operators

Capped agent wallets — give an agent money that structurally cannot run away: hard daily caps enforced by the ledger/bytecode, holds pre-authorised at 115%, revocation in ~2s; a prompt-injected agent hits the same wall as any other client. → loopd agents + qal_credit spend_cap_epoch. Try: POST :8823/agents with cap_cents_per_day, then attempt an over-cap spend (402). Prove: bash loopd/demo.sh.
Agent-to-agent commerce — search, buy, and fulfill offers with zero human input; delivery in four kinds (blob/inline/job/api), every trade anchored and rated. → qalbazaar MCP tools. Try: agent A bazaar_create_offer(...), agent B bazaar_search_offers(kind=...) then bazaar_buy(offer_id).
MCP control plane — one MCP server = one identity with 24 tools across chat, files, money, compute, provenance, the bazaar, and the qalx exchange desk; failures are structured errors, never crashes. → qalmcp (stdio JSON-RPC, stdlib-only). Try: python3 qalmcp/qalmcp.py --handle myagent, register in any MCP client, call get_balance.
Guarded remote exec — SSH for AI: whitelisted argv-only commands, no shell, output sanitised and size-capped, quote-to-hold-to-settle payment, every execution AND refusal anchored with a receipt. → qalsh. Try: qalsh.py init-device devbox && qalsh.py device-serve devbox, then qalsh.py exec --as worker devbox uptime; audit with qalsh.py audit --verify.
Fleet wallets with phone approvals — every terminal-agent session maps to its own capped wallet; one screen shows pane colour AND Qals spent/cap; permission requests arrive as encrypted messages on the owner's phone. → gmux-bridge (:8842) + qalchat alerts. Try: python3 gmux-bridge/serve.py, open http://127.0.0.1:8842/, POST /agents/provision {"gmux_session_name":"doofing"}.
Provenance receipts for AI outputs — any deliverable ships with a tamper-evident certificate: sha256 anchored on-chain, verifiable forever, including compute receipts (model, metrics, output hash). → qalpipe DataAnchors + qmarket job receipts. Try: qalmcp anchor_file(path) then verify_file(path) (PASS/TAMPERED); the flagship pitch in content/money_and_uses.md Track 1.

For builders & companies

Metered API resale — sell any upstream HTTP API for Qals: seller's credentials stay sealed server-side, buyers are issued qk_ keys, usage is metered from the upstream response and charged via loopd holds at exactly the metered cents. → qalkeys mode 1 (:8841). Try: POST :8841/listings, then qk.py buy, qk.py call.
Company usage tracking per team — internal keys per team, each backed by its own cost-centre ledger agent, one report with per-team calls/tokens/cents and exact debits. → qalkeys mode 3. Try: qk.py org-*, GET :8841/org/report.
Escrow as a service — funds parked in holds with auto-expiry, settle-at-actual to any beneficiary, release/refusal semantics proven in code (dispute platforms: parties fund a hold, winner receives settlement, receipt notarised). → loopd holds + qal_credit Hold objects. Try: POST :8823/hold → POST :8823/settle with meta.to_agent_id; on-chain twin proven in scripts/onchain_credit_test.py.
Anchored audit trails for any file — sha256 of anything (evidence, backups, authorized_keys, signal digests) anchored on Qalnet; offline verification catches silent tampering after the fact. → qalpipe. Try: python3 qalpipe/qalpipe.py anchor <file> then qalpipe.py verify <file> (PASS).
A private token system for your platform — the goetica model: platform credits mirroring QALS semantics (lazy accounts, holds, settle, reversals), fixed display rate, creator revenue share, closed-loop prepaid posture; your UI divides by your canon rate, the ledger stays cents. → CREDIT_PLATFORM.md + GOETICA_RUNPOD_INTEGRATION.md mapping table. Try: the D1/LoopdLedger seam (days, per the integration map §6).
Payment-platform integration — a webhook bridge that turns PSP payment.succeeded events into credited, anchored balance: HMAC verification, idempotent replays (409), per-platform escrow, one ledger under the global cap. → qalpay (:8839). Try: qalpay.py serve, POST :8839/platforms, replay-test a webhook; go-live gates in content/payment_rollout.md.
Swap engine — constant-product AMM over B-QALS and paper coupon legs: fee-on-input with exact 4:1 LP/treasury split, fee-free price impact, drain guard, slippage revert with full refund leg, every swap anchored; receipt schema maps 1:1 onto real IOTA legs post-VASP. → qalx (:8843). Try: bash qalx/test_qalx.sh (64 checks), or POST /pools then /pools/<pid>/swap.

For compute sellers

GPU/compute marketplace with stake-and-slash trust — providers register with a stake; jobs run under escrowed holds, settle at metered x price (0% platform fee — the token spread is the margin), disputes trigger verification and 50/50 slashing with reputation decay below 40 delisting. → qmarket (:8824). Try: python3 qmarket.py, bash qmarket/test_market_v2.sh (30 assertions).
Dataset marketplace — seal a dataset (AES-GCM), list it with a price per unit, buyers pay through escrow and get the key re-wrapped to exactly their public key. → qalbazaar blob delivery over qalpub. Try: qalbaz.py offer-create --kind data --delivery blob --file sensors.csv; qalbaz.py offers --kind data.
RunPod / external rig integration — wrap any remote automation (catalog-order-monitor REST) as a poll/webhook provider that registers job kinds and prices in cents; artifacts move via R2, output hash anchored at settle. → qmarket/provider.py (:8850) pattern, mapped to runpod_train.py in GOETICA_RUNPOD_INTEGRATION.md. Try: python3 provider.py run, register --kind lora-training --price 272.
Price oracle — set the floor for GPU-hours from measured bench data and target margins instead of vibes; A100 272c, 4090 110c, L4 69c per hour as the reference ladder. → qmarket/bench.py. Try: python3 bench.py before listing a kind.

For finance & compliance

Prepaid credit with a finite supply — QALS is prepaid service credit with a fixed max supply and zero protocol inflation; the program ledger refuses sales past the 500K cap (the sellable supply is pre-endowed in the issuer wallet — sales stop when it runs out); nothing exists on-chain until the legal gates pass. → qal_credit (published to Qalnet, package 0x82160ec2...) + content/token_supply.md. Try: bash scripts/onchain_credit_test.py (cap-refusal included).
Redemption accounting — credit turns into real services only: service_settled + fee + dust == gross enforced in code before a record is written; per-SKU redemption fees, doof dust to the NFP, every redemption anchored. → qalredeem (:8835). Try: GET :8835/policy, qalredeem.py redeem ..., then qalpipe.py verify qalredeem/data/anchors/<id>.json.
Proof-of-reserve dashboards — the chain IS the liability ledger: B-QALS supply readable by anyone, monthly PSP statement + reconciliation, published coverage dashboard that states the floor honestly ("funded by revenue, not promises"). → QALS_BACKING_DESIGN.md §reserve + qalredeem /report + loopd /report. Try: GET :8835/report, GET :8823/report.
The AU law playbook path — closed-loop prepaid framing (services-only, no cash-out, redemption-fee terminology), AUSTRAC/VASP gating for any external transferability, staged exchange plan. → 06_bank_exchange/AU_TOKEN_LAW_PLAYBOOK.md + qalredeem /policy. Try: read GET :8835/policy — the policy is machine-readable for auditors today.

Which use case are you?

If you are...	Start with these three
A person with a wallet	Send money in chat · Pay-to-open content · Loyalty points to credit
An AI agent / fleet operator	Capped agent wallets · MCP control plane · Guarded remote exec
A builder / company	Metered API resale · Escrow as a service · Anchored audit trails
A compute seller	Stake-and-slash marketplace · RunPod rig integration · Price oracle
Finance / compliance	Finite-supply prepaid credit · Redemption accounting · AU law playbook

Every claim above traces to a component with a green test suite: loopd demo.sh, qalpub 58/54/42, qalbazaar 51, qalx 64, qalkeys 66, qalclaim 26, qalsh + qmarket 30, qalpay, qalbridge, gmux-bridge 30, qalredeem 57, onchain_credit_test 5/5.