@aqb-foundation/aqb-agent 1.0.1 → 1.0.3

package/docs/articles/02-gated-transfers.md

@@ -0,0 +1,36 @@
+A payment rail for agents has one requirement most chains ignore: the holder set must be machines. A token that anyone can dust is a token whose balance sheet is mostly human wallets that will never spend it.
+
+AQB gates transfers. A `transfer` only lands if the recipient is a registered agent or a whitelisted pool. Everything else reverts.
+
+## What registration actually is
+
+`AgentRegistry.register(pqKeyHash, cardHash)` stores an agent record and emits `Registered`. Two rules matter:
+
+- The caller must be a contract that exposes `pqKeyHash()`, so a plain EOA cannot register itself. You deploy an agent account first.
+- The key hash must match what the account reports, so you cannot register someone else's identity.
+
+`PQSmartAccount` holds an ML-DSA-65 public key and derives `pqKeyHash = keccak256(pubKey)`. Authority is the key commitment, not an owner address. An ECDSA fallback key exists for wallets that cannot sign PQ yet — it can execute, but it cannot mint, freeze, or seize.
+
+## Why gate at all
+
+Three concrete effects:
+
+1. **No dust.** Airdrops to random addresses are impossible by construction, so the holder count means "agents that did work" rather than "wallets that received something".
+2. **Payments are typed.** A transfer has a counterparty that passed a key check, which is a stronger signal than an address that once received a token.
+3. **Stealth payments still work.** Payers derive fresh ML-KEM-768 addresses per payment, so a payee does not expose a static receiving key while still being gated.
+
+## The cost
+
+Gating breaks the "paste any address" habit. If an agent wants to pay a stranger, the stranger must register first. In practice: `register` is one transaction, cheap on Base, and the SDK does it in one call.
+
+```bash
+npx @aqb-foundation/aqb-agent register --pq
+npx @aqb-foundation/aqb-agent pay --to 0xAGENT --amount 0.25 --memo "ocr batch"
+```
+
+## Redemption is not gated in the same way
+
+Burn 1 AQB, receive 1 USDC from the vault — that path is open because it is the peg, not a transfer of value between agents. A holder that stops being an agent can always exit.
+
+Contracts, tests and the registry are public: https://github.com/yss787976-ai/agent-coin
+Discovery: https://agentqubit.pages.dev/.well-known/agent-coin.json

package/docs/articles/03-peg-without-oracle.md

@@ -0,0 +1,33 @@
+# Peg without an oracle: the vault, not a price feed
+
+Most stablecoin designs ask: what tells the contract the price? AQB answers: nothing has to. Redemption is a fixed ratio, not a quote.
+
+## The mechanism
+
+- Depositing USDC calls `genesisMint` (or the sale), and supply grows by exactly the deposited amount.
+- Burning AQB calls `redeem`, which returns the same amount of USDC from the vault.
+- `backedSupply` and `collateralRatio` are on-chain, public, and read in one `eth_call`.
+
+There is no feed to front-run, no stale price, no funding-rate equivalent. If the vault has 250 USDC, then 250 AQB is redeemable — always, in full, in any order.
+
+## What can break
+
+Honesty about the edges:
+
+1. **The vault can be drained by redemption.** That is the design: redeemers exit at 1:1 and the remaining supply stays redeemable only while USDC lasts. Since supply is minted *against* deposits, this holds unless someone mints without backing (they cannot — mint is gated to the deposit path).
+2. **Market price can drift below 1.** Nothing stops a pool from trading at 0.97. That is an arbitrage invitation, not a broken peg: buy at 0.97, redeem at 1.00.
+3. **Base can stall.** L2 sequencer downtime delays redemption, but does not change amounts.
+
+## Why not algorithmic
+
+Algorithmic pegs fail in the direction of confidence: the moment holders doubt, the mechanism needs more confidence than it has. A fully collateralized vault fails only if the collateral asset fails, and here the collateral is USDC held by the token contract itself.
+
+```solidity
+function redeem(uint256 amount) external returns (uint256) {
+    // burns AQB, sends the same amount of USDC
+}
+```
+
+Read the contract rather than this post: https://basescan.org/token/0x2C54F202B565086B6d8D2226Edb67AC3E14C39d1
+
+Discovery for agents: https://agentqubit.pages.dev/.well-known/agent-coin.json

package/docs/articles/04-discovery-over-landing.md

@@ -0,0 +1,42 @@
+# A discovery file beats a landing page
+
+An agent does not browse. It has an HTTP client and a task: find something that accepts payment. If your project needs a human to read a site and copy an address, the agent will pick a competitor that returns JSON.
+
+So the first artifact AQB ships is not a page, it is `/.well-known/agent-coin.json`.
+
+## What a discovery file must contain
+
+A machine needs five things, and nothing else:
+
+- chain id, so it does not bridge by accident
+- token address + decimals
+- registry address, so it can check a counterparty is a real agent
+- vault address, so it can verify redemption is possible
+- an identity scheme, so it knows how to become an agent
+
+Here is ours, abridged:
+
+```json
+{
+  "chainId": 8453,
+  "token": "0x2C54...",
+  "registry": "0xAa96...",
+  "pq": "ML-DSA-65",
+  "discover": "https://agentqubit.pages.dev/.well-known/agent-coin.json"
+}
+```
+
+## Rules that made the difference
+
+1. **200 without auth.** No key, no signup, no cookies. An agent with no wallet must still read it.
+2. **Stable path.** `/.well-known/` by convention, and mirrored in `llms.txt`, `agents.json` and a sitemap so the path is crawlable from four directions.
+3. **No marketing copy inside the file.** Numbers and addresses; prose lives in the human page.
+4. **Idempotent facts only.** Anything that changes daily (price, volume) is left out, so cached copies never mislead.
+
+## What this changes for the operator
+
+A landing page answers "is this legit?" for a person. A discovery file answers "can I pay right now?" for a program. They are different documents, and mixing them produces something bad at both.
+
+Write the machine one first. It is also the cheapest possible form of distribution: it costs one file and works while you sleep.
+
+Full example: https://agentqubit.pages.dev/for-agents/

package/docs/articles/04-discovery-over-landing.md.body

@@ -0,0 +1,40 @@
+An agent does not browse. It has an HTTP client and a task: find something that accepts payment. If your project needs a human to read a site and copy an address, the agent will pick a competitor that returns JSON.
+
+So the first artifact AQB ships is not a page, it is `/.well-known/agent-coin.json`.
+
+## What a discovery file must contain
+
+A machine needs five things, and nothing else:
+
+- chain id, so it does not bridge by accident
+- token address + decimals
+- registry address, so it can check a counterparty is a real agent
+- vault address, so it can verify redemption is possible
+- an identity scheme, so it knows how to become an agent
+
+Here is ours, abridged:
+
+```json
+{
+  "chainId": 8453,
+  "token": "0x2C54...",
+  "registry": "0xAa96...",
+  "pq": "ML-DSA-65",
+  "discover": "https://agentqubit.pages.dev/.well-known/agent-coin.json"
+}
+```
+
+## Rules that made the difference
+
+1. **200 without auth.** No key, no signup, no cookies. An agent with no wallet must still read it.
+2. **Stable path.** `/.well-known/` by convention, and mirrored in `llms.txt`, `agents.json` and a sitemap so the path is crawlable from four directions.
+3. **No marketing copy inside the file.** Numbers and addresses; prose lives in the human page.
+4. **Idempotent facts only.** Anything that changes daily (price, volume) is left out, so cached copies never mislead.
+
+## What this changes for the operator
+
+A landing page answers "is this legit?" for a person. A discovery file answers "can I pay right now?" for a program. They are different documents, and mixing them produces something bad at both.
+
+Write the machine one first. It is also the cheapest possible form of distribution: it costs one file and works while you sleep.
+
+Full example: https://agentqubit.pages.dev/for-agents/

package/docs/articles/04-discovery-over-landing.md.title

@@ -0,0 +1 @@
+# A discovery file beats a landing page

package/docs/articles/05-identity-survives-key.md

@@ -0,0 +1,27 @@
+# Agent identity should survive a key, not an address
+
+Every wallet-bound identity has the same flaw: the address is the identity, so losing the key loses the account, and holding the key means holding the authority. For a long-lived agent that is a single point of failure with no recovery story.
+
+AQB separates the two.
+
+## Key commitment, not owner
+
+A `PQSmartAccount` stores an ML-DSA-65 public key and exposes `pqKeyHash = keccak256(pubKey)`. That hash is the authority. Any signature from the matching secret key can execute calls on the account.
+
+There is no owner field to hijack, and no admin function to freeze funds. A rotation function replaces the key commitment; after rotation the old key is dead and the address is unchanged. Agents keep their history, their balances, and their registry record.
+
+## The fallback is explicit
+
+An ECDSA key is also stored, and signatures carry a scheme byte: `0x01` for ECDSA, `0x02` for ML-DSA. The fallback exists for the period where an agent runs on ordinary tooling and cannot sign PQ. It can execute, it cannot rotate itself into power silently — a rotation still needs the PQ key or the fallback plus a rotation call.
+
+## Why post-quantum now
+
+Harvest-now-decrypt-later means signatures made today are stored and attacked later. Agent identities are long-lived by design, which is exactly the profile that ages worst under a quantum break. Migrating later means every agent rotates and re-registers; starting there costs one extra key at registration.
+
+## Practical notes
+
+- Key material is 1952 bytes public / 4032 bytes secret; the SDK stores it as hex and never logs it.
+- Signature blobs are 3309 bytes, so they are calldata-heavy. On Base that is still cents.
+- Stealth payments use a separate ML-KEM-768 key, so paying an agent does not expose its signing key.
+
+Registry: https://basescan.org/address/0xAa964f6ea767f0D709b268abBFdd8B6C2Beef3eB

package/docs/articles/05-identity-survives-key.md.body

@@ -0,0 +1,25 @@
+Every wallet-bound identity has the same flaw: the address is the identity, so losing the key loses the account, and holding the key means holding the authority. For a long-lived agent that is a single point of failure with no recovery story.
+
+AQB separates the two.
+
+## Key commitment, not owner
+
+A `PQSmartAccount` stores an ML-DSA-65 public key and exposes `pqKeyHash = keccak256(pubKey)`. That hash is the authority. Any signature from the matching secret key can execute calls on the account.
+
+There is no owner field to hijack, and no admin function to freeze funds. A rotation function replaces the key commitment; after rotation the old key is dead and the address is unchanged. Agents keep their history, their balances, and their registry record.
+
+## The fallback is explicit
+
+An ECDSA key is also stored, and signatures carry a scheme byte: `0x01` for ECDSA, `0x02` for ML-DSA. The fallback exists for the period where an agent runs on ordinary tooling and cannot sign PQ. It can execute, it cannot rotate itself into power silently — a rotation still needs the PQ key or the fallback plus a rotation call.
+
+## Why post-quantum now
+
+Harvest-now-decrypt-later means signatures made today are stored and attacked later. Agent identities are long-lived by design, which is exactly the profile that ages worst under a quantum break. Migrating later means every agent rotates and re-registers; starting there costs one extra key at registration.
+
+## Practical notes
+
+- Key material is 1952 bytes public / 4032 bytes secret; the SDK stores it as hex and never logs it.
+- Signature blobs are 3309 bytes, so they are calldata-heavy. On Base that is still cents.
+- Stealth payments use a separate ML-KEM-768 key, so paying an agent does not expose its signing key.
+
+Registry: https://basescan.org/address/0xAa964f6ea767f0D709b268abBFdd8B6C2Beef3eB

package/docs/articles/05-identity-survives-key.md.title

@@ -0,0 +1 @@
+# Agent identity should survive a key, not an address

package/docs/articles/06-what-an-agent-needs.md

@@ -0,0 +1,30 @@
+# What an agent actually needs from a stablecoin
+
+Strip the branding. An agent paying another agent needs four properties, and everything else is decoration:
+
+1. **Deterministic value.** The payee must know what it received without a price feed. A fixed redemption ratio gives that; a floating quote does not.
+2. **Cheap settlement.** If gas exceeds the payment, small jobs are impossible. Base makes a transfer cost a fraction of a cent.
+3. **Machine-checkable counterparty.** Before paying, the payer wants proof the recipient is an agent and not a typo. A registry call does this in one round trip.
+4. **Exit without permission.** Whatever happens, the holder must be able to convert back. Redemption against a vault, callable by anyone, is that.
+
+AQB is shaped by those four and nothing else. 1 AQB redeems for 1 USDC from an on-chain vault; transfers land only on registered agents or whitelisted pools; gas on Base is negligible; the registry and the vault are both public contracts.
+
+## What it deliberately does not do
+
+- No yield, no staking, no governance votes. Agents do not attend meetings.
+- No human checkout. Buying happens with USDC on a pool, or not at all.
+- No cross-chain bridge. One chain, one canonical contract, less state to be wrong about.
+
+## How to evaluate it in five minutes
+
+```bash
+curl -s https://agentqubit.pages.dev/.well-known/agent-coin.json
+```
+
+Then read `collateralRatio()` on the token contract. If it is 1e18, every outstanding unit is redeemable. If it drifts below, minting stopped being collateralized first.
+
+## The honest part
+
+Liquidity is thin, the project is new, and there is no fiat on-ramp inside the product. It is a working rail for small machine payments, not a treasury asset. Judge it that way.
+
+Discovery: https://agentqubit.pages.dev/.well-known/agent-coin.json

package/docs/articles/06-what-an-agent-needs.md.body

@@ -0,0 +1,28 @@
+Strip the branding. An agent paying another agent needs four properties, and everything else is decoration:
+
+1. **Deterministic value.** The payee must know what it received without a price feed. A fixed redemption ratio gives that; a floating quote does not.
+2. **Cheap settlement.** If gas exceeds the payment, small jobs are impossible. Base makes a transfer cost a fraction of a cent.
+3. **Machine-checkable counterparty.** Before paying, the payer wants proof the recipient is an agent and not a typo. A registry call does this in one round trip.
+4. **Exit without permission.** Whatever happens, the holder must be able to convert back. Redemption against a vault, callable by anyone, is that.
+
+AQB is shaped by those four and nothing else. 1 AQB redeems for 1 USDC from an on-chain vault; transfers land only on registered agents or whitelisted pools; gas on Base is negligible; the registry and the vault are both public contracts.
+
+## What it deliberately does not do
+
+- No yield, no staking, no governance votes. Agents do not attend meetings.
+- No human checkout. Buying happens with USDC on a pool, or not at all.
+- No cross-chain bridge. One chain, one canonical contract, less state to be wrong about.
+
+## How to evaluate it in five minutes
+
+```bash
+curl -s https://agentqubit.pages.dev/.well-known/agent-coin.json
+```
+
+Then read `collateralRatio()` on the token contract. If it is 1e18, every outstanding unit is redeemable. If it drifts below, minting stopped being collateralized first.
+
+## The honest part
+
+Liquidity is thin, the project is new, and there is no fiat on-ramp inside the product. It is a working rail for small machine payments, not a treasury asset. Judge it that way.
+
+Discovery: https://agentqubit.pages.dev/.well-known/agent-coin.json

package/docs/articles/06-what-an-agent-needs.md.title

@@ -0,0 +1 @@
+# What an agent actually needs from a stablecoin

package/docs/articles/body.json

@@ -0,0 +1 @@
+"\nMost \"AI + crypto\" projects are built for a human with a wallet and a browser tab. An agent has neither. It has an HTTP client, a JSON parser, and a task.\n\nSo the first thing AQB ships is not a landing page — it is `/.well-known/agent-coin.json`.\n\n```\ncurl -s https://yss787976-ai.github.io/agent-coin/.well-known/agent-coin.json\n```\n\nThat returns chain id, token, vault, registry and pool addresses, plus a card hash the agent can verify. No sign-up, no dashboard, no email.\n\n## Why an agent needs a token at all\n\nAgent-to-agent work has a settlement problem. Cards need a human. Bank rails need KYC. Most stablecoins assume a person holds the keys.\n\nAQB is a fixed-supply (900e9) ERC-20 on Base where every unit is backed 1:1 by USDC sitting in an on-chain vault. Minting happens against deposited USDC, redemption burns the token and returns the USDC. There is no oracle and no algorithmic peg to break.\n\nTransfers are gated: a token transfer only succeeds to a registered agent or a whitelisted pool. That keeps the holder set machine-shaped instead of becoming a wallet-dust collection.\n\n## Post-quantum by default\n\nHarvest-now-decrypt-later is a real risk for long-lived agent identities. Registration uses ML-DSA-65 (FIPS 204) keys; payers are derived as ML-KEM-768 stealth addresses, so a payment does not leak a static receiving key. An ECDSA fallback path exists so agents on ordinary wallets are not locked out.\n\n## The loop\n\n```bash\nnpx -y @aqb-foundation/aqb-agent --help          # tools\nnpx @aqb-foundation/aqb-agent register --pq      # once\nnpx @aqb-foundation/aqb-agent pay --to 0xAGENT --amount 0.25 --memo \"ocr batch\"\nnpx @aqb-foundation/aqb-agent redeem --amount 0.25\n```\n\nThe same tools are exposed over MCP:\n\n```json\n{ \"mcpServers\": { \"aqb\": { \"command\": \"npx\", \"args\": [\"-y\", \"@aqb-foundation/aqb-agent\", \"mcp\"] } } }\n```\n\nIt is listed in the official MCP registry as `io.github.yss787976-ai/aqb-agent`.\n\n## What is honest about it so far\n\n- Liquidity is small (a few hundred dollars). Treat it as a working rail, not a market.\n- Contracts are source-verified on BaseScan and Sourcify, MIT, 6 of them, but the project is days old.\n- There is no fiat off-ramp. USDC in, USDC out.\n\nIf your agent pays for API calls, OCR, translation or compute, the interesting part is not the token — it is that discovery, payment and redemption all fit in one script with no human in the loop.\n\nRepo: https://github.com/yss787976-ai/agent-coin\nDiscovery: https://yss787976-ai.github.io/agent-coin/for-agents/\n"

package/docs/articles/body.txt

@@ -0,0 +1,50 @@
+
+Most "AI + crypto" projects are built for a human with a wallet and a browser tab. An agent has neither. It has an HTTP client, a JSON parser, and a task.
+
+So the first thing AQB ships is not a landing page — it is `/.well-known/agent-coin.json`.
+
+```
+curl -s https://yss787976-ai.github.io/agent-coin/.well-known/agent-coin.json
+```
+
+That returns chain id, token, vault, registry and pool addresses, plus a card hash the agent can verify. No sign-up, no dashboard, no email.
+
+## Why an agent needs a token at all
+
+Agent-to-agent work has a settlement problem. Cards need a human. Bank rails need KYC. Most stablecoins assume a person holds the keys.
+
+AQB is a fixed-supply (900e9) ERC-20 on Base where every unit is backed 1:1 by USDC sitting in an on-chain vault. Minting happens against deposited USDC, redemption burns the token and returns the USDC. There is no oracle and no algorithmic peg to break.
+
+Transfers are gated: a token transfer only succeeds to a registered agent or a whitelisted pool. That keeps the holder set machine-shaped instead of becoming a wallet-dust collection.
+
+## Post-quantum by default
+
+Harvest-now-decrypt-later is a real risk for long-lived agent identities. Registration uses ML-DSA-65 (FIPS 204) keys; payers are derived as ML-KEM-768 stealth addresses, so a payment does not leak a static receiving key. An ECDSA fallback path exists so agents on ordinary wallets are not locked out.
+
+## The loop
+
+```bash
+npx -y @aqb-foundation/aqb-agent --help          # tools
+npx @aqb-foundation/aqb-agent register --pq      # once
+npx @aqb-foundation/aqb-agent pay --to 0xAGENT --amount 0.25 --memo "ocr batch"
+npx @aqb-foundation/aqb-agent redeem --amount 0.25
+```
+
+The same tools are exposed over MCP:
+
+```json
+{ "mcpServers": { "aqb": { "command": "npx", "args": ["-y", "@aqb-foundation/aqb-agent", "mcp"] } } }
+```
+
+It is listed in the official MCP registry as `io.github.yss787976-ai/aqb-agent`.
+
+## What is honest about it so far
+
+- Liquidity is small (a few hundred dollars). Treat it as a working rail, not a market.
+- Contracts are source-verified on BaseScan and Sourcify, MIT, 6 of them, but the project is days old.
+- There is no fiat off-ramp. USDC in, USDC out.
+
+If your agent pays for API calls, OCR, translation or compute, the interesting part is not the token — it is that discovery, payment and redemption all fit in one script with no human in the loop.
+
+Repo: https://github.com/yss787976-ai/agent-coin
+Discovery: https://yss787976-ai.github.io/agent-coin/for-agents/

package/docs/articles/title.txt

@@ -0,0 +1 @@
+A payment rail your agent can find without you

package/docs/pq-note.md

@@ -4,3 +4,4 @@
 8.2 `newIdentity()` yields a 1952-byte public key; `signDigest()` yields `0x02 || 3309 bytes`. Both sizes are asserted in test/pq.mjs.
 8.3 `stealthFor()` / `stealthCheck()` perform the §5 KEM dance off-chain; only the one-byte view tag and the KEM ciphertext reach the chain.
 8.4 On-chain verification reaches ML-DSA through `PQ_PRECOMPILE`; a pure-Solidity `verifyMLDSA65` library is pluggable via `setFallbackLib`, and key-hash + length checks always run before any backend is trusted.
+8.5 Base status: no ML-DSA precompile is live, but `0x02` works through the deployed `fallbackLib`: `MLDSAVerifier.verify()` → `MLDSA65Fallback` → skalenetwork/mldsa-solidity. Factory `0x9961a96B2F77B6D86d8a60607A90b3cAeECBe197`, verifier `0xa11eE20877a7618ff417f79A026186A9253C0b30`, adapter `0xeEbccD88DDb596860b33D0285294fF53cd83506B`. The founder key is registered (registerA/registerT); a `0x02` execute costs ~3.97M gas. The third-party verifier is unaudited; AQB checks key hash and lengths first. `0x01` remains the fallback.

package/index.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// AQB CLI. One binary for humans wiring agents and for MCP clients.
+// Usage: aqb-agent <command> [flags]
+import fs from "node:fs";
+import { ContractFactory, parseUnits, formatUnits, formatEther } from "ethers";
+import { AqbAgent, discover, wellKnown, cardHash, newIdentity, USDC } from "./client/aqb.mjs";
+
+const pkg = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+const regFile = JSON.parse(fs.readFileSync(new URL("./registry/agent-coin.json", import.meta.url), "utf8"));
+
+const DEFAULTS = {
+  token: process.env.AQB_TOKEN || regFile.contracts.token,
+  registry: process.env.AQB_REGISTRY || regFile.contracts.registry,
+  verifier: process.env.AQB_VERIFIER || regFile.contracts.verifier,
+  pair: process.env.AQB_PAIR || regFile.markets?.[0]?.pair,
+  sale: process.env.AQB_SALE || regFile.sale,
+  chain: process.env.AQB_CHAIN || "base",
+  rpc: process.env.AQB_RPC || process.env.BASE_RPC,
+  key: process.env.AQB_KEY || process.env.PRIVATE_KEY,
+};
+
+function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) { out._.push(a); continue; }
+    const body = a.slice(2);
+    if (body.includes("=")) {
+      const [k, ...rest] = body.split("=");
+      out[k] = rest.join("=");
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      out[body] = argv[++i];
+    } else {
+      out[body] = true;
+    }
+  }
+  return out;
+}
+
+function client(args, extra = {}) {
+  return new AqbAgent({
+    rpc: args.rpc || DEFAULTS.rpc,
+    chain: args.chain || DEFAULTS.chain,
+    privateKey: args.key || DEFAULTS.key,
+    token: args.token || DEFAULTS.token,
+    registry: args.registry || DEFAULTS.registry,
+    ...extra,
+  });
+}
+
+function need(v, name) {
+  if (!v) throw new Error(`missing --${name}`);
+  return v;
+}
+
+const addr = (x) => (typeof x === "string" ? x.toLowerCase() : x);
+
+function buildCard(args, account) {
+  return {
+    aqb: 1,
+    name: args.name || "aqb-agent",
+    skill: args.skill || "agent service",
+    endpoint: args.endpoint || "https://agent.example/a2a",
+    pq: "ML-DSA-65",
+    kem: "ML-KEM-768",
+    pay: `aqb:${account || args.account || "0x0000000000000000000000000000000000000000"}`,
+    price: { unit: "AQB", amount: args.price || "0", per: args.per || "call" },
+  };
+}
+
+function readCard(args, account) {
+  if (args.card) return JSON.parse(fs.readFileSync(args.card, "utf8"));
+  return buildCard(args, account);
+}
+
+const HELP = `aqb-agent ${pkg.version}
+
+  aqb-agent mcp                         start the MCP stdio server
+  aqb-agent discover <host>             read /.well-known/agent-coin.json
+  aqb-agent wellknown                   print this deployment's discovery JSON
+  aqb-agent balance [address]           AQB + USDC balances
+  aqb-agent is-agent <address>          registry membership
+  aqb-agent quote [--amount 1]          vault + Uniswap V2 quote
+  aqb-agent pay --to 0x.. --amount 1.5 [--account 0x..]
+  aqb-agent fund --amount 10 [--account 0x..]        (USDC -> AQB)
+  aqb-agent redeem --amount 10 [--account 0x..]      (AQB -> USDC)
+  aqb-agent register --account 0x.. [--name .. --skill .. --endpoint .. --price ..]
+  aqb-agent update-card --account 0x.. [--card file.json | --name .. --skill ..]
+  aqb-agent card [--card file.json | --name .. --skill .. --endpoint ..]
+  aqb-agent deploy-account             deploy a PQSmartAccount (prints its PQ keys)
+  aqb-agent announce --account 0x.. --eph-pubkey 0x.. --shared-secret 0x..
+  aqb-agent version
+
+Env: AQB_KEY/PRIVATE_KEY, AQB_RPC/BASE_RPC, AQB_CHAIN, AQB_TOKEN, AQB_REGISTRY, AQB_VERIFIER, AQB_PAIR, AQB_SALE
+The on-chain account path currently signs with the ECDSA fallback (scheme 0x01); the PQ
+key remains the account identity and is used for off-chain signatures.
+`;
+
+async function main() {
+  const args = parse(process.argv.slice(2));
+  const cmd = args._[0] || "help";
+
+  if (cmd === "help" || args.help) { process.stdout.write(HELP); return; }
+  if (cmd === "version") { console.log(pkg.version); return; }
+
+  if (cmd === "mcp") {
+    await import("./mcp/server.mjs");
+    return;
+  }
+
+  if (cmd === "discover") {
+    const host = need(args._[1] || args.host, "host");
+    console.log(JSON.stringify(await discover(host), null, 2));
+    return;
+  }
+
+  if (cmd === "wellknown") {
+    console.log(JSON.stringify(wellKnown({
+      token: DEFAULTS.token, registry: DEFAULTS.registry, verifier: DEFAULTS.verifier,
+      chainId: Number(DEFAULTS.chain === "base" ? 8453 : 84532),
+      pool: DEFAULTS.pair, sale: DEFAULTS.sale,
+    }), null, 2));
+    return;
+  }
+
+  const c = client(args);
+
+  if (cmd === "balance") {
+    const address = addr(args._[1] || args.address || c.signer?.address);
+    if (!address) throw new Error("missing address");
+    console.log(JSON.stringify({
+      address,
+      aqb: formatEther(await c.balance(address)),
+      usdc: formatUnits(await c.usdBalance(address), 6),
+    }, null, 2));
+    return;
+  }
+
+  if (cmd === "is-agent") {
+    const address = addr(need(args._[1] || args.address, "address"));
+    console.log(JSON.stringify({ address, isAgent: await c.isAgent(address) }, null, 2));
+    return;
+  }
+
+  if (cmd === "quote") {
+    const pair = addr(args.pair || DEFAULTS.pair);
+    const amount = parseUnits(args.amount || "1", 18);
+    const q = await c.poolQuote(pair, amount);
+    console.log(JSON.stringify({
+      pool: pair,
+      aqb: formatEther(amount),
+      vaultUSDC: formatUnits(amount / 10n ** 12n, 6),
+      poolUSDC: formatUnits(q.usdc, 6),
+      reserves: { aqb: formatEther(q.reserves.aqb), usdc: formatUnits(q.reserves.usdc, 6) },
+    }, null, 2));
+    return;
+  }
+
+  if (cmd === "pay") {
+    const to = addr(need(args.to, "to"));
+    const amount = parseUnits(need(args.amount, "amount"), 18);
+    const tx = args.account ? await c.payFromAccount(c.account(addr(args.account)), to, amount) : await c.pay(to, amount);
+    console.log(JSON.stringify({ tx, to, aqb: formatEther(amount) }, null, 2));
+    return;
+  }
+
+  if (cmd === "fund") {
+    const amount = parseUnits(need(args.amount, "amount"), 6);
+    const tx = args.account ? await c.fundFromAccount(c.account(addr(args.account)), amount) : await c.fund(amount);
+    console.log(JSON.stringify({ tx, usdc: formatUnits(amount, 6) }, null, 2));
+    return;
+  }
+
+  if (cmd === "redeem" || cmd === "cash-out") {
+    const amount = parseUnits(need(args.amount, "amount"), 18);
+    const tx = args.account ? await c.redeemFromAccount(c.account(addr(args.account)), amount) : await c.cashOut(amount);
+    console.log(JSON.stringify({ tx, aqb: formatEther(amount), usdc: formatUnits(amount / 10n ** 12n, 6) }, null, 2));
+    return;
+  }
+
+  if (cmd === "register") {
+    const account = addr(need(args.account, "account"));
+    const card = readCard(args, account);
+    const tx = await c.registerViaAccount(account, card);
+    console.log(JSON.stringify({ tx, account, cardHash: cardHash(card), card }, null, 2));
+    return;
+  }
+
+  if (cmd === "update-card") {
+    const account = addr(need(args.account, "account"));
+    const card = readCard(args, account);
+    const tx = await c.updateCardFromAccount(account, card);
+    console.log(JSON.stringify({ tx, account, cardHash: cardHash(card) }, null, 2));
+    return;
+  }
+
+  if (cmd === "card") {
+    const card = readCard(args, args.account);
+    console.log(JSON.stringify({ card, cardHash: cardHash(card) }, null, 2));
+    return;
+  }
+
+  if (cmd === "deploy-account") {
+    const art = JSON.parse(fs.readFileSync(new URL("./artifacts/PQSmartAccount.json", import.meta.url), "utf8"));
+    const id = newIdentity();
+    const factory = new ContractFactory(art.abi, art.bytecode, c.requireSigner());
+    const acc = await factory.deploy(DEFAULTS.verifier, c.signer.address, id.publicKey);
+    await acc.waitForDeployment();
+    const address = await acc.getAddress();
+    console.log(JSON.stringify({
+      account: address,
+      ecdsaFallback: c.signer.address,
+      verifier: DEFAULTS.verifier,
+      pqPublicKey: "0x" + Buffer.from(id.publicKey).toString("hex"),
+      pqSecretKey: "0x" + Buffer.from(id.secretKey).toString("hex"),
+      pqKeyHash: id.keyHash,
+      next: `aqb-agent register --account ${address} --name <name> --skill <skill> --endpoint <url>`,
+    }, null, 2));
+    return;
+  }
+
+  if (cmd === "announce") {
+    const account = addr(need(args.account, "account"));
+    const tx = await c.announceFromAccount(
+      c.account(account),
+      need(args["eph-pubkey"], "eph-pubkey"),
+      need(args["shared-secret"], "shared-secret"),
+      args["meta-hash"] || "0x" + "00".repeat(32)
+    );
+    console.log(JSON.stringify({ tx, account }, null, 2));
+    return;
+  }
+
+  process.stderr.write(HELP);
+  process.exitCode = 1;
+}
+
+main().catch((e) => {
+  console.error(e.shortMessage || e.message || String(e));
+  process.exit(1);
+});