@paydlux/agent 0.1.23 → 0.1.24

package/README.md

@@ -7,6 +7,9 @@ real money has already been drained this way.
 
 Paydlux puts the guardrails **on the ledger** instead of in your code.
 
+**Homepage: [paydlux.com](https://paydlux.com)** — product, pricing and the
+live demo. Source: this repo. Docs and setup: below.
+
 ## The Stellar path (primary — no smart contract, no faucet, no gas fight)
 
 There is no contract to audit. The whole mechanism is three native Stellar
@@ -30,6 +33,7 @@ injection cannot talk its way past a signature check.
 stellar/vault.ts     create a 2-of-2 vault, register mandates, settle, revoke
 stellar/gateway.ts   HTTP 402 resource server; serves only after the ledger agrees
 stellar/agent.ts     the buyer side — one class, one method call
+stellar/mcp.ts       the same buyer side as an MCP server, for any agent client
 stellar/desk.ts      approval queue: a human decides, in the clear
 stellar/portal.ts    the page that human looks at
 stellar/policy.ts    daily budget / seller allowlist (the part a ledger can't count)
@@ -75,6 +79,57 @@ What the desk enforces once it is public (`npx tsx stellar/tls-check.ts`, 19 che
 
 No wallet, no faucet, no config.
 
+### MCP server: your agent calls Paydlux instead of a wallet
+
+The buyer side also speaks [Model Context Protocol](https://modelcontextprotocol.io),
+so an agent in Claude, Cursor, LobeHub, Codex or any other MCP client gets Paydlux's
+tools directly — no wallet, no signing library, no payment code in the agent:
+
+```bash
+npx -y @paydlux/agent mcp --file /absolute/path/to/paydlux-vault.json
+```
+
+Add it to the client the same way you add any stdio server:
+
+```json
+{
+  "mcpServers": {
+    "paydlux": {
+      "command": "npx",
+      "args": ["-y", "@paydlux/agent", "mcp", "--file", "/absolute/path/to/paydlux-vault.json"]
+    }
+  }
+}
+```
+
+| tool | what the agent gets |
+|---|---|
+| `paydlux_status` | which vault, which token, live balance, who can sign, how many mandates are live |
+| `paydlux_payment_rules` | the ceiling the human set — plus what the ledger says is already spent today |
+| `paydlux_check_payment` | dry run: would *this* amount to *this* seller pass, and which rule breaks if not |
+| `paydlux_buy` | pay a 402-gated seller. If a human has to approve, the answer is a handle and a status URL |
+| `paydlux_payment_status` | has the human decided yet |
+| `paydlux_recent_payments` | the last payments in/out, with transaction hashes an explorer can check |
+| `paydlux_escrow_status` / `paydlux_pending_escrows` | what is locked in escrow, and who can still take it back |
+
+Two things this server deliberately cannot do:
+
+- **It cannot release money on its own.** It loads the agent key and nothing
+  else — one signer of weight 1 against a release threshold of 2. There is no
+  flag that accepts the principal or approver key, so it cannot be talked into
+  using a key it never holds. A payment the mandate does not cover comes back as
+  `needs_approval`, with the handle and the desk link for the human.
+- **It cannot read a carelessly stored key file.** If the vault file is readable
+  by other users, the server refuses to start until you `chmod 600` it, and no
+  tool result will ever print a secret seed.
+
+Run it with `--read-only` and the two tools that touch money disappear from the
+tool listing entirely — useful for an agent that should report on spend but not
+cause any. `npx tsx stellar/mcp-check.ts` drives the server with a real MCP
+client and asserts all of the above (20 checks, testnet).
+
+Product page, pricing and the hosted demo: **[https://paydlux.com](https://paydlux.com)**.
+
 ### The human key does not live on the seller's machine
 
 The vault needs two signatures. If both keys sit in one process, that is really

package/dist/cli.js

@@ -15,7 +15,7 @@
 // into their bot.
 import { createInterface } from "node:readline/promises";
 import { createServer } from "node:http";
-import { execSync } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, chmodSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
@@ -29,6 +29,7 @@ import { DEMO_HOST, DEMO_ROUTE, startDemo } from "./showcase.js";
 import { DONATE_HOST, DONATE_PORT, startDonate } from "./donate.js";
 import { claimEscrow, pendingEscrows, prepareEscrowRelease, refundEscrow } from "./escrow.js";
 import { describeChallenge } from "./phone.js";
+import { start as startMcp } from "./mcp.js";
 export const VAULT_FILE_DEFAULT = "paydlux-vault.json";
 const arg = (name) => {
     const i = process.argv.indexOf(`--${name}`);
@@ -421,7 +422,7 @@ async function sell() {
             bad(`port ${demoPort} (showcase) is already in use by ${who}.`);
         await startDemo({
             port: demoPort, price, network, vault: vault.address, token: data.token.code,
-            explorer: data.explorer ?? "", gateway: gw,
+            explorer: data.explorer ?? "", gateway: gw, route: uri, payee,
             onKeys: (pubs) => { gw.agentKeys = [pub(keys.agent), ...pubs]; },
         });
         log(`showcase is listening on 127.0.0.1:${demoPort} for https://${DEMO_HOST}`);
@@ -504,6 +505,257 @@ ${flag("donate") ? `  donations  https://${DONATE_HOST}   (they pay YOU from THE
     process.on("SIGINT", bye);
     process.on("SIGTERM", bye);
 }
+/**
+ * paydlux demo — the funder meeting, as one command.
+ *
+ * `sell` is the right command for a seller: it takes flags, and it refuses to
+ * start when anything is off (port taken, budget already spent). That is correct
+ * for a seller and fatal in front of an investor, who is watching a terminal go
+ * red thirty seconds before the money shot.
+ *
+ * This is a preset, not a second implementation. It fixes the two things that
+ * actually break a live demo, then runs the SAME sell() — same mandate, same
+ * desk, same ledger, same phone signature:
+ *
+ *   1. A port already held by Paydlux is not an error. It means the demo is
+ *      already running, so print the links and open the tabs instead of dying.
+ *   2. A daily budget already spent today IS fatal (the mandate would refuse
+ *      every payment), so raise it, save it to the vault file, and say so out
+ *      loud. Raising the *daily* counter is safe: the per-payment ceiling is
+ *      still pinned into the signed transaction hash.
+ *
+ * It then opens the two tabs and prints the runbook, so nobody has to remember
+ * a URL or a portal key while someone is watching.
+ */
+async function demo() {
+    const path = resolve(process.cwd(), arg("file") ?? VAULT_FILE_DEFAULT);
+    if (!existsSync(path))
+        bad(`no vault here. Run:  paydlux setup`);
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    const network = (data.network ?? "testnet");
+    const price = arg("price") ?? data.policy?.defaultPrice ?? "1";
+    const ports = [
+        Number(arg("port") ?? 4021), Number(arg("desk") ?? 4022),
+        Number(arg("demo-port") ?? 4023),
+    ];
+    // The donation door (4024) is deliberately NOT in this list and NOT started
+    // by the demo. It runs against the MAINNET vault, where real people send real
+    // USDC. A demo preset that restarted it would point a public money address at
+    // a testnet vault, and a donation to a testnet account is gone forever.
+    // 1. Something already on those ports? Two different things happened in real
+    // meetings and neither may end in a red error:
+    //   a) the demo IS up and answering — reuse it, just open the tabs;
+    //   b) a leftover Paydlux (a donation door from this morning, a seller that
+    //      lost its tunnel) is squatting on one port — the public URLs then 530
+    //      and `sell` refuses to start. Stop the leftover, say exactly what was
+    //      stopped, and start a clean demo.
+    const live = await surfacesLive();
+    if (live.desk && live.demo && !flag("restart") && await surfacesServe(path)) {
+        const key = data.desk?.portalKey;
+        log("the demo is already running and answering — nothing to start");
+        openUrl(`https://${DEMO_HOST}`);
+        if (key)
+            openUrl(`https://${PUBLIC_HOST}/phone/?k=${key}`);
+        demoCard(`https://${PUBLIC_HOST}`, key, data);
+        return;
+    }
+    if (live.desk && live.demo) {
+        // Answering, but on a different vault. desk.paydlux.com and demo.paydlux.com
+        // are ONE address: a testnet demo and a mainnet demo cannot both be live on
+        // it. Reusing whichever happens to be up is how a founder ends up showing
+        // play money while believing the real vault is on the screen — or the other
+        // way round, with real money moving during a "safe" demo. Stop it, say so,
+        // and start the one that was asked for.
+        log(`something else is answering ${DEMO_HOST} — stopping it so the ${network} demo can take the address`);
+    }
+    await clearDemoPorts(ports);
+    // 2. Budget headroom. `sell` refuses to start when the ledger says today's
+    // budget is gone, and the demo would then die at the worst possible moment.
+    // Seed the counter from the ledger here and lift the ceiling if needed.
+    // NB: `payee` in the vault file is an object ({address, seed}) when `setup`
+    // generated one, and a bare address string when the seller passed --payee.
+    // Reading only the string form silently skips this check — which is exactly
+    // how the demo died once, on "1.00 of the 50 daily budget is already spent".
+    const payeeAddr = typeof data.payee === "string" ? data.payee : data.payee?.address;
+    const daily = Number(data.policy?.dailyBudget ?? 50);
+    if (typeof payeeAddr === "string" && /^G[A-Z2-7]{55}$/.test(payeeAddr)) {
+        try {
+            const vault = await vaultHandle(data, network);
+            const spent = Number(await vault.paidToday(payeeAddr));
+            // Enough headroom for ten more demo payments, whatever the price is.
+            const want = spent + Math.max(10, Math.ceil(Number(price) * 10));
+            if (daily < want) {
+                data.policy = { ...(data.policy ?? {}), savedByOwner: true, dailyBudget: Math.ceil(want) };
+                writeFileSync(path, JSON.stringify(data, null, 2));
+                chmodSync(path, 0o600);
+                log(`today's spend is ${spent.toFixed(2)} of ${daily}; raised the daily budget to ${data.policy.dailyBudget} so the demo has room`);
+                log(`  per-payment ceiling unchanged (${data.policy.maxPerPayment ?? "?"}) — that one is pinned into the signed transaction hash`);
+            }
+        }
+        catch (e) {
+            // Do not block the demo on this check. If the ledger really is
+            // unreachable, sell() will say so plainly before it starts anything.
+            log(`could not pre-check today's spend (${e?.message ?? e}) — starting anyway`);
+        }
+    }
+    // 3. Run the real thing. sell() reads its options from process.argv, so the
+    // preset is expressed there rather than by duplicating the seller's startup.
+    const extra = ["sell", "--split", "--tls", "--showcase",
+        "--price", price, "--route", "/market/data", "--file", path];
+    for (const f of ["max", "daily", "port", "desk", "demo-port", "donate-port"]) {
+        const v = arg(f);
+        if (v !== undefined)
+            extra.push(`--${f}`, v);
+    }
+    process.argv = [process.argv[0], process.argv[1], ...extra];
+    // Open the tabs as soon as the desk actually answers — not before, because a
+    // tab that loads an error page is what a funder remembers. Scheduled rather
+    // than awaited: sell() never returns, it stays up serving payments.
+    const key = data.desk?.portalKey;
+    demoCard(`https://${PUBLIC_HOST}`, key, data);
+    if (!flag("no-open")) {
+        setTimeout(async () => {
+            if (await tunnelLive()) {
+                openUrl(`https://${DEMO_HOST}`);
+                if (key)
+                    openUrl(`https://${PUBLIC_HOST}/phone/?k=${key}`);
+            }
+        }, 1000);
+    }
+    await sell();
+}
+/** Are the public URLs actually answering? A port can be held by a process
+ *  whose tunnel died, which is worse than no process at all: the browser gets
+ *  a Cloudflare 530 and the founder has no idea why. */
+async function surfacesLive() {
+    const get = async (url) => {
+        try {
+            const r = await fetch(url, { signal: AbortSignal.timeout(4000) });
+            return r.status < 500;
+        }
+        catch {
+            return false;
+        }
+    };
+    const [desk, demo] = await Promise.all([
+        get(`https://${PUBLIC_HOST}/healthz`), get(`https://${DEMO_HOST}/`),
+    ]);
+    return { desk, demo };
+}
+/**
+ * Is the Paydlux answering those ports the SAME vault that was asked for?
+ *
+ * The public addresses are singletons: desk.paydlux.com and demo.paydlux.com can
+ * only carry one vault at a time, and the testnet demo and the mainnet demo use
+ * the same two. "It is already running" is therefore not enough — the thing that
+ * is running may be the other network. Answering a funder with play money while
+ * saying it is the real vault (or moving real money during what everyone believes
+ * is a safe demo) is the worst failure this command can have, so the reuse path
+ * checks the vault file of the process actually holding the ports.
+ */
+async function surfacesServe(path) {
+    const want = resolve(process.cwd(), path);
+    for (const port of [Number(arg("desk") ?? 4022), Number(arg("port") ?? 4021)]) {
+        const who = await portHolder(port);
+        const pid = Number((who?.match(/pid (\d+)/) ?? [])[1]);
+        if (!pid)
+            return false;
+        // -ww: a truncated command line would hide the --file argument and make this
+        // say "different vault" about the very demo we are asking to reuse.
+        let cmd = "";
+        try {
+            cmd = execSync(`ps -ww -o command= -p ${pid} 2>/dev/null`, { encoding: "utf8" }).trim();
+        }
+        catch {
+            return false;
+        }
+        const served = (cmd.match(/--file[= ](\S+)/) ?? [])[1] ?? VAULT_FILE_DEFAULT;
+        if (resolve(process.cwd(), served) !== want)
+            return false;
+    }
+    return true;
+}
+/**
+ * Free the demo's ports when a stale Paydlux is squatting on one.
+ *
+ * Only Paydlux processes are touched, and only after saying which one and why.
+ * Anything else on the port is left alone and reported, because killing a
+ * stranger's server to make a demo fit is not our call to make.
+ */
+async function clearDemoPorts(ports) {
+    for (const port of ports) {
+        const who = await portHolder(port);
+        if (!who)
+            continue;
+        if (!/paydlux|cli|tsx|node/i.test(who)) {
+            bad(`port ${port} is held by ${who}, which is not Paydlux.\n  free it, or move the demo: paydlux demo --desk ${port + 100}`);
+        }
+        const pid = Number((who.match(/pid (\d+)/) ?? [])[1]);
+        if (!pid) {
+            log(`port ${port} is held by ${who}; stopping it`);
+            continue;
+        }
+        try {
+            const cmd = execSync(`ps -o command= -p ${pid} 2>/dev/null`, { encoding: "utf8" }).trim();
+            log(`stopping the stale Paydlux on port ${port} (pid ${pid}): ${cmd.slice(0, 90)}`);
+            process.kill(pid, "SIGTERM");
+        }
+        catch { /* already gone */ }
+        // Wait for the port to actually free. SIGTERM to a seller runs its bye()
+        // handler, which takes a moment to close listeners and the tunnel.
+        for (let i = 0; i < 20; i++) {
+            if (!(await portHolder(port)))
+                break;
+            await new Promise((r) => setTimeout(r, 250));
+        }
+        const still = await portHolder(port);
+        if (still) {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { /* gone */ }
+            log(`port ${port} needed a hard stop`);
+        }
+    }
+}
+/** The runbook, printed where the founder is already looking. */
+function demoCard(host, key, data) {
+    const network = data.network ?? "testnet";
+    // The footer used to promise "nothing here costs real money" unconditionally.
+    // On the public network that is a lie, and it is the kind of lie that gets a
+    // founder spending the vault in front of an investor.
+    const real = network !== "testnet";
+    console.log(`
+  ┌── Paydlux demo · the 5-minute script ─────────────────────────────
+  │ 1  https://paydlux.com        "an agent buys from a website"
+  │ 2  https://${DEMO_HOST}      press RUN THE LOOP → 402 → paid
+  │ 3  your iPhone                hold 1.2s. the key never left it
+  │ 4  back on tab 2              step 5 prints the ledger tx hash
+  │ 5  ${host}/rules${key ? `?k=${key}` : ""}   spending limits, categories
+  └───────────────────────────────────────────────────────────────────
+  token ${data.token?.code ?? "?"} · ${network} · ${real
+        ? "REAL MONEY — each approved loop pays out of this vault"
+        : "nothing here costs real money"}
+`);
+}
+/** Open a URL in the default browser. Best-effort: a demo survives it failing. */
+function openUrl(url) {
+    try {
+        const tool = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+        const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+        const p = spawn(tool, args, { stdio: "ignore", detached: true });
+        p.on("error", () => log(`open this yourself: ${url}`));
+        p.unref();
+    }
+    catch {
+        log(`open this yourself: ${url}`);
+    }
+}
+/** The vault handle `sell` uses, shared so the demo checks the same numbers. */
+async function vaultHandle(data, network) {
+    const keys = data.keys ?? {};
+    return StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(keys.principal), approver: keys.approver ? pub(keys.approver) : undefined, agent: pub(keys.agent) }, network);
+}
 /** XLM the vault must hold to exist, versus what it actually has. */
 async function vaultRent(vault) {
     const acc = await vault.horizon.loadAccount(vault.address);
@@ -819,7 +1071,19 @@ async function withdraw() {
         bad("then run this again — approvals from the phone land automatically.");
     }
     console.log(`sending ${want} ${data.token.code} from the vault to ${to} …`);
-    const res = await vault.release(to, String(want), principal, approver, "paydlux withdraw");
+    // A wallet that has never been funded cannot receive a payment — the ledger
+    // answers op_no_destination. For XLM the fix is the createAccount operation,
+    // which costs the same two signatures. For a token there is no fix at all:
+    // that account would need a trustline too, so say so instead of failing cryptically.
+    const exists = await vault.horizon.loadAccount(to).then(() => true).catch(() => false);
+    if (!exists && !vault.isNative) {
+        bad(`${to} has no account on the ledger, so it cannot hold ${data.token.code}.\n  send it XLM from any exchange first, then withdraw again.`);
+    }
+    if (!exists)
+        console.log(`${to} does not exist on the ledger yet — this payment creates it.`);
+    const res = exists
+        ? await vault.release(to, String(want), principal, approver, "paydlux withdraw")
+        : await vault.fund(to, String(want), principal, approver, "paydlux withdraw");
     console.log(`done. tx ${res?.hash}`);
     console.log(`vault now holds ${await vault.balance()} ${data.token.code}`);
 }
@@ -1076,6 +1340,12 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
       in a claimable balance you cannot touch until --release seconds have
       passed, and the buyer can take it back any time before then. You get paid
       by proving delivery before the timer, not by waiting for it.
+  paydlux demo  [--price 1] [--file ./paydlux-vault.json]
+      the funder meeting as one command. Same seller, same desk, same phone
+      signature — but it refuses to fail in front of an audience: if the demo is
+      already running it opens the tabs instead of dying on a taken port, and if
+      today's daily budget is already spent it raises that budget (the
+      per-payment ceiling is untouched) rather than refusing to start.
   paydlux escrow [--release ORD | --refund ESCROW_ID]
       list what is locked for your vault, release one order, or take a buyer's
       money back. Release needs both human keys; on a --split vault it prints
@@ -1095,6 +1365,11 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
   paydlux withdraw --to G… [--all | --amount N]
       take your money back out of the vault. Needs both human keys; the agent
       key can never do this.
+  paydlux mcp   [--file ./paydlux-vault.json] [--read-only]
+      serve Paydlux as an MCP server, so an agent in Claude, Cursor, LobeHub or
+      any other MCP client buys through the mandate instead of holding a wallet.
+      This process loads only the agent key — one of two vault signers — so it
+      cannot release money alone. --read-only drops the tools that touch money.
 
 one file holds it all: ./paydlux-vault.json (0600, never commit it)
 `;
@@ -1240,6 +1515,8 @@ export async function main() {
         return setup();
     if (cmd === "sell")
         return sell();
+    if (cmd === "demo")
+        return demo();
     if (cmd === "donate")
         return donate();
     if (cmd === "status")
@@ -1252,6 +1529,8 @@ export async function main() {
         return usdc();
     if (cmd === "escrow")
         return escrow();
+    if (cmd === "mcp")
+        return startMcp();
     bad(`unknown command "${cmd}".\n\n${HELP}`);
 }
 // Run only when this file is the entry point, so importing it in a test is safe.

package/dist/desk.d.ts

@@ -112,6 +112,15 @@ export declare class ApprovalDesk {
     private seq;
     /** when /rules last saved, so the page can say "saved" without a query flag */
     private rulesSavedAt;
+    /**
+     * When the approver app last polled /queue. The desktop portal reads /list and
+     * the phone reads /queue, so a hit here means a phone is pointed at THIS desk
+     * with THIS link. It is how a Mac can tell "the seller's phone is asleep" from
+     * "the phone is still talking to the desk from the last run" — the second one
+     * makes a live demo look dead, because the parked payment goes to a queue
+     * nobody is looking at.
+     */
+    private lastPhonePollAt;
     private server?;
     cfg: DeskConfig;
     constructor(cfg: DeskConfig);

package/dist/desk.js

@@ -215,6 +215,15 @@ export class ApprovalDesk {
     seq = 0;
     /** when /rules last saved, so the page can say "saved" without a query flag */
     rulesSavedAt = 0;
+    /**
+     * When the approver app last polled /queue. The desktop portal reads /list and
+     * the phone reads /queue, so a hit here means a phone is pointed at THIS desk
+     * with THIS link. It is how a Mac can tell "the seller's phone is asleep" from
+     * "the phone is still talking to the desk from the last run" — the second one
+     * makes a live demo look dead, because the parked payment goes to a queue
+     * nobody is looking at.
+     */
+    lastPhonePollAt = 0;
     server;
     cfg;
     constructor(cfg) { this.cfg = cfg; }
@@ -967,9 +976,30 @@ export class ApprovalDesk {
                     return;
                 }
                 // The approver app's list view. Key-gated like everything else, and it
-                // carries no paid content and no challenge XDR.
-                if (url.pathname === "/queue")
+                // carries no paid content and no challenge XDR. Polling it is also the
+                // proof that a phone is attached to this desk, so note the time.
+                if (url.pathname === "/queue") {
+                    this.lastPhonePollAt = Date.now();
                     return send(200, this.queue());
+                }
+                // "Is the phone actually connected?" for the Mac's demo app. Counts and
+                // public ledger identities only — no payment content, no challenge, no
+                // key material — and still behind the portal key like everything else.
+                if (url.pathname === "/status") {
+                    const all = this.list();
+                    return send(200, {
+                        ok: true,
+                        network: this.cfg.vault.network,
+                        vault: this.cfg.vault.address,
+                        approver: this.cfg.vault.signers.approver,
+                        pending: all.filter((r) => r.status === "pending").length,
+                        awaitingPhone: all.filter((r) => r.status === "awaiting_phone").length,
+                        settled: all.filter((r) => r.status === "settled").length,
+                        phoneSeenSecondsAgo: this.lastPhonePollAt
+                            ? Math.round((Date.now() - this.lastPhonePollAt) / 1000)
+                            : null,
+                    });
+                }
                 // The app fetches the pending transaction by handle rather than asking
                 // the human to paste 400 characters of base64 on a phone.
                 const ch = url.pathname.match(/^\/challenge\/([\w-]+)$/);

package/dist/mcp.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Network } from "./vault.ts";
+import { type Policy } from "./policy.ts";
+type Cfg = {
+    path: string;
+    network: Network;
+    vault: string;
+    token: {
+        code: string;
+        issuer?: string;
+    };
+    payee?: string;
+    policy: Partial<Policy>;
+    /** the only secret this process holds. One of two vault signers. */
+    agentSeed: string;
+    principalPub: string;
+    approverPub?: string;
+    agentPub: string;
+    readOnly: boolean;
+};
+export declare function buildServer(cfg: Cfg): McpServer;
+export declare function start(): Promise<void>;
+export {};

package/dist/mcp.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+// Paydlux as an MCP server: the tools an agent calls when it wants to buy
+// something and a human has to approve the money.
+//
+//   npx -y @paydlux/agent mcp --file paydlux-mainnet.json
+//
+// This is the BUYER side of the protocol, and it is deliberately narrow. The
+// only signing key this process ever loads is the agent key: one of two signers
+// on the vault, weight 1 against a release threshold of 2. It can ask, and it
+// can execute a mandate a human already signed. It cannot release money on its
+// own, and there is no flag here that accepts a principal or approver key at
+// all. The guardrail is the ledger, so this server does not have to be trusted.
+//
+// Why the tool set looks like this: an agent's failure mode is not malice, it
+// is confidence. It will retry a refused payment forever, and it will spend a
+// budget it believes is free. So the read-only tools come first — what the
+// human allowed, what is already spent according to the ledger, whether a
+// specific payment would pass — and the one tool that moves anything returns
+// the handle and the human's link rather than pretending the answer is in.
+import { existsSync, readFileSync, statSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Keypair } from "@stellar/stellar-sdk";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { StellarVault, assetMatches } from "./vault.js";
+import { PaydluxAgent } from "./agent.js";
+import { PolicyEngine } from "./policy.js";
+import { readEscrow, escrowOutcome, pendingEscrows } from "./escrow.js";
+const HOME = "https://paydlux.com";
+function arg(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > -1 ? process.argv[i + 1] : undefined;
+}
+const flag = (name) => process.argv.includes(`--${name}`);
+function pub(seed) { return Keypair.fromSecret(seed).publicKey(); }
+/**
+ * Load the vault file and keep only what the buyer role needs.
+ *
+ * The file also holds the principal and approver seeds — the human's half of
+ * the vault. They are read once, converted to public keys for the ledger's
+ * signer check, and then the parsed object goes out of scope. A process that
+ * never holds the human keys cannot be talked into using them, which is the
+ * whole point of splitting them in the first place.
+ */
+function load(path) {
+    if (!existsSync(path)) {
+        throw new Error(`no vault file at ${path}. Point --file at a paydlux-*.json created by \`paydlux setup\`.`);
+    }
+    // Same stance as the CLI: a key file other users can read is not a key file.
+    const mode = statSync(path).mode & 0o777;
+    if (mode & 0o077) {
+        throw new Error(`${path} is readable by others (${mode.toString(8)}). Run: chmod 600 ${path}`);
+    }
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const keys = raw.keys ?? {};
+    if (!keys.agent)
+        throw new Error(`${path} has no keys.agent — this server buys on the agent key's behalf`);
+    if (!keys.principal)
+        throw new Error(`${path} has no keys.principal — it is not a Paydlux vault file`);
+    if (!raw.vault)
+        throw new Error(`${path} has no vault address`);
+    return {
+        path,
+        network: (raw.network === "public" ? "public" : "testnet"),
+        vault: String(raw.vault),
+        token: { code: String(raw.token?.code ?? "XLM"), issuer: raw.token?.issuer },
+        payee: raw.payee?.address,
+        policy: raw.policy ?? {},
+        agentSeed: String(keys.agent),
+        principalPub: pub(String(keys.principal)),
+        approverPub: keys.approver ? pub(String(keys.approver)) : undefined,
+        agentPub: pub(String(keys.agent)),
+        readOnly: flag("read-only"),
+    };
+}
+// ----------------------------------------------------------------- helpers
+let vaultHandle;
+async function vault(cfg) {
+    if (vaultHandle)
+        return vaultHandle;
+    vaultHandle = await StellarVault.load(cfg.vault, cfg.token.code, cfg.token.issuer, { principal: cfg.principalPub, approver: cfg.approverPub, agent: cfg.agentPub }, cfg.network);
+    if (cfg.token.code === "USDC")
+        vaultHandle.useUsdc();
+    return vaultHandle;
+}
+/**
+ * What left this vault today, straight from the ledger, for every payee.
+ *
+ * StellarVault.paidToday() answers for one payee. An agent asking "how much of
+ * my budget is left" means the total, and the in-RAM PolicyEngine counter resets
+ * on restart — a budget that reads as unspent after a restart is worse than no
+ * budget, so the honest number comes from Horizon. assetMatches is the same
+ * single comparison the rest of the codebase uses, so a native-XLM vault is not
+ * blind to its own money here.
+ */
+async function spentTodayAll(v) {
+    const start = new Date();
+    start.setUTCHours(0, 0, 0, 0);
+    const byPayee = {};
+    let total = 0;
+    let cursor;
+    const base = v.network === "public" ? "https://horizon.stellar.org" : "https://horizon-testnet.stellar.org";
+    for (let page = 0; page < 10; page++) {
+        const url = `${base}/accounts/${v.address}/payments?order=desc&limit=200${cursor ? `&cursor=${cursor}` : ""}`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`ledger payments query failed: ${res.status}`);
+        const recs = (await res.json())?._embedded?.records ?? [];
+        if (!recs.length)
+            break;
+        for (const e of recs) {
+            if (new Date(e.created_at).getTime() < start.getTime())
+                return { total, byPayee };
+            if (e.type !== "payment" && e.type !== "claimable_balance_claim")
+                continue;
+            if (e.from !== v.address)
+                continue; // money leaving the vault only
+            if (!assetMatches(v.token, e))
+                continue; // the vault's own token, incl. XLM
+            total += Number(e.amount);
+            byPayee[e.to] = (byPayee[e.to] ?? 0) + Number(e.amount);
+        }
+        cursor = recs[recs.length - 1].paging_token;
+    }
+    return { total, byPayee };
+}
+async function recentPayments(v, limit) {
+    const base = v.network === "public" ? "https://horizon.stellar.org" : "https://horizon-testnet.stellar.org";
+    const res = await fetch(`${base}/accounts/${v.address}/payments?order=desc&limit=${Math.min(limit, 50)}`);
+    if (!res.ok)
+        throw new Error(`ledger payments query failed: ${res.status}`);
+    return ((await res.json())?._embedded?.records ?? []).map((e) => ({
+        at: e.created_at, type: e.type, from: e.from, to: e.to,
+        amount: e.amount, asset: e.asset_type === "native" ? "XLM" : `${e.asset_code}:${String(e.asset_issuer).slice(0, 6)}…`,
+        transaction: e.transaction_hash,
+    }));
+}
+/**
+ * Last line of defence on output. A Stellar secret seed is an S-prefixed
+ * 56-character base32 string; nothing this server returns has any business
+ * containing one, so if one ever reaches a tool result it is replaced before it
+ * reaches a model's context — and a model's context is a place secrets leak
+ * from, usually by being summarised into a public answer.
+ */
+function redact(s) {
+    return s.replace(/S[A-Z2-7]{55}/g, "[redacted: a secret seed reached an MCP tool result — report this]");
+}
+function text(obj) {
+    return { content: [{ type: "text", text: redact(JSON.stringify(obj, null, 2)) }] };
+}
+function fail(reason, extra = {}) {
+    return { content: [{ type: "text", text: redact(JSON.stringify({ ok: false, reason, ...extra }, null, 2)) }] };
+}
+/** Sellers answer with the payload an agent asked for; keep tool results small. */
+function clip(data, max = 4000) {
+    if (typeof data !== "string")
+        return data;
+    return data.length > max ? `${data.slice(0, max)}… [+${data.length - max} chars]` : data;
+}
+// ------------------------------------------------------------------ server
+function version() {
+    try {
+        return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function buildServer(cfg) {
+    const policy = new PolicyEngine(cfg.policy);
+    const server = new McpServer({ name: "paydlux", version: version() }, {
+        instructions: [
+            "Paydlux is spend-limited payments for AI agents. The money sits in a 2-of-2",
+            "Stellar vault; the agent key is one signer, a human is the other, so an agent",
+            "cannot release funds alone. Read paydlux_payment_rules before buying, check",
+            "paydlux_check_payment for the specific amount, then paydlux_buy. If a buy",
+            "returns needs_approval, tell the human and poll paydlux_payment_status — do not",
+            `retry the purchase, and do not open the desk link yourself. ${HOME}`,
+        ].join("\n"),
+    });
+    // ---------------------------------------------------------------- reading
+    server.registerTool("paydlux_status", {
+        title: "Paydlux vault status",
+        description: "Which vault this agent spends from: network, token, live balance, the XLM rent that keeps the account alive, who can sign, and how many spending mandates are live. Read-only.",
+    }, async () => {
+        const v = await vault(cfg);
+        const signers = await v.signerSummary();
+        const acc = await v.horizon.loadAccount(v.address);
+        const xlm = acc.balances.find((b) => b.asset_type === "native")?.balance ?? "0";
+        const min = ((2 + (acc.subentry_count ?? 0)) * 0.5).toFixed(1);
+        return text({
+            ok: true,
+            network: cfg.network === "public" ? "mainnet (real money)" : "testnet",
+            vault: v.address,
+            token: cfg.token.code,
+            balance: await v.balance(),
+            xlm_rent: { have: xlm, need: min, short: Number(xlm) < Number(min) },
+            thresholds: signers.thresholds,
+            signers: signers.signers.map((s) => ({ weight: s.weight, kind: s.type })),
+            live_mandates: signers.signers.filter((s) => s.type === "preauth-mandate").length,
+            agent_key: cfg.agentPub,
+            explorer: `https://stellar.expert/explorer/${cfg.network === "public" ? "account" : "testnet/account"}/${v.address}`,
+            about: HOME,
+        });
+    });
+    server.registerTool("paydlux_payment_rules", {
+        title: "What the human allowed",
+        description: "The spending mandate as the human set it: per-payment ceiling, daily budget, seller allow/deny lists, category ceilings — plus what has actually been spent today according to the ledger, not this process's memory. Call this before buying.",
+    }, async () => {
+        const v = await vault(cfg);
+        const spent = await spentTodayAll(v);
+        const p = policy.policy;
+        return text({
+            ok: true,
+            token: cfg.token.code,
+            max_per_payment: p.maxPerPayment,
+            daily_budget: p.dailyBudget,
+            spent_today_ledger: Number(spent.total.toFixed(4)),
+            budget_left_today: Number((Number(p.dailyBudget ?? 0) - spent.total).toFixed(4)),
+            paid_to: spent.byPayee,
+            allowlist: p.allowlist?.length ? p.allowlist : "(any seller)",
+            denylist: p.denylist ?? [],
+            categories: p.categories ?? {},
+            payee_categories: p.payeeCategory ?? {},
+            max_live_mandates: p.maxLiveMandates,
+            note: "The ceiling is enforced on the ledger, not here. Refusing you early only saves you a failed transaction.",
+        });
+    });
+    server.registerTool("paydlux_check_payment", {
+        title: "Would this payment be allowed?",
+        description: "Dry-run one payment against the mandate: amount, seller, and anything already approved and waiting. Answers ok plus the headroom left, or which rule it breaks (max_per_payment, daily_budget, allowlist, denylist, category ceiling). No money moves.",
+        inputSchema: {
+            amount: z.number().positive().describe(`How much to pay, in the vault's token (${cfg.token.code})`),
+            payee: z.string().optional().describe("Seller account id (G…, 56 chars). Defaults to the vault's configured payee."),
+            committed: z.number().min(0).optional().describe("Amount already approved and still waiting on a signature, so the ceiling counts promises as well as payments"),
+        },
+    }, async ({ amount, payee, committed }) => {
+        const to = payee ?? cfg.payee;
+        if (!to)
+            return fail("no payee: pass payee, or set payee.address in the vault file");
+        const v = await vault(cfg);
+        const spent = await spentTodayAll(v);
+        // Seed the engine's day counter from the ledger before asking it anything.
+        // Its own counter starts empty in every fresh process, so an unseeded check
+        // would cheerfully approve a payment that blows a budget already spent —
+        // and a restart would reset the ceiling the mandate advertises.
+        policy.seedFromLedger(spent.total);
+        const verdict = policy.check({ amount, payee: to, committed });
+        return text({
+            ok: verdict.ok,
+            amount, payee: to, token: cfg.token.code,
+            rule: verdict.ok ? undefined : verdict.rule,
+            why: verdict.ok ? undefined : verdict.detail,
+            spent_today_ledger: Number(spent.total.toFixed(4)),
+            daily_budget: policy.policy?.dailyBudget,
+            max_per_payment: policy.policy?.maxPerPayment,
+        });
+    });
+    server.registerTool("paydlux_recent_payments", {
+        title: "Recent payments from the vault",
+        description: "The last payments in or out of the vault, straight from the Stellar ledger, with transaction hashes an explorer can verify. Read-only proof of what actually happened.",
+        inputSchema: { limit: z.number().int().min(1).max(50).optional().describe("How many records, default 10") },
+    }, async ({ limit }) => text({ ok: true, payments: await recentPayments(await vault(cfg), limit ?? 10) }));
+    server.registerTool("paydlux_escrow_status", {
+        title: "Escrow state",
+        description: "Look up a locked escrow by claimable-balance id: amount, when the seller can claim it, and until when the buyer can still take it back without the seller. Also reports who claimed it if it is already settled.",
+        inputSchema: { balance_id: z.string().describe("The escrow's claimable balance id (starts with B…)") },
+    }, async ({ balance_id }) => {
+        const e = await readEscrow(cfg.network, balance_id);
+        const outcome = await escrowOutcome(cfg.network, balance_id);
+        if (!e)
+            return text({ ok: true, escrow: null, outcome, note: "no live escrow with that id — it was claimed, refunded, or never existed" });
+        const now = Math.floor(Date.now() / 1000);
+        return text({
+            ok: true,
+            // One timer, two meanings: before releaseAt the buyer can take the money
+            // back alone, after it the seller can claim it alone. There is no separate
+            // refund deadline on the ledger, so do not invent one here.
+            escrow: {
+                balance_id: e.balanceId, amount: e.amount, asset: e.asset,
+                buyer: e.buyer, vault: e.vault, release_at: e.releaseAt,
+                lock_tx: e.txHash, memo: e.memo, claimed: e.claimed,
+            },
+            buyer_can_refund: !e.claimed && now < e.releaseAt,
+            seconds_until_seller_can_claim: Math.max(0, e.releaseAt - now),
+            outcome,
+        });
+    });
+    server.registerTool("paydlux_pending_escrows", {
+        title: "Escrows this vault is part of",
+        description: "Every live escrow the vault is a claimant on, oldest release first, with each one's refund window. Read-only.",
+    }, async () => {
+        const list = await pendingEscrows(cfg.network, cfg.vault);
+        const now = Math.floor(Date.now() / 1000);
+        return text({
+            ok: true, count: list.length,
+            escrows: list.map((e) => ({
+                balance_id: e.balanceId, amount: e.amount, asset: e.asset, buyer: e.buyer,
+                release_at: e.releaseAt, buyer_can_refund: !e.claimed && now < e.releaseAt,
+            })),
+        });
+    });
+    // ---------------------------------------------------------------- buying
+    if (!cfg.readOnly) {
+        server.registerTool("paydlux_buy", {
+            title: "Buy from a 402-gated seller",
+            description: "GET (or POST to) a URL that prices itself with HTTP 402. If the seller runs in approval mode the request is parked for a human: the result carries `handle`, `status_url` and the human's `desk` link — report those to the human and poll paydlux_payment_status. Do NOT retry the buy: a second request creates a second approval. A seller demanding a pre-authorised mandate is refused here, because creating that mandate needs the human's keys, which this server does not hold.",
+            inputSchema: {
+                url: z.string().url().describe("The paid resource, e.g. https://seller.example.com/api/data"),
+                body: z.string().optional().describe("Request body; sends POST instead of GET"),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        }, async ({ url, body }) => {
+            const agent = new PaydluxAgent({
+                agentKey: cfg.agentSeed,
+                network: cfg.network,
+                // The agent must not sit inside one MCP call waiting for a person.
+                approvalTimeoutMs: 5_000, pollMs: 2_000,
+            });
+            // Escrow routes are funded by the buyer's own account, never by the agent
+            // key on a vault. The key is supplied out of band by whoever runs this
+            // server; without it the seller's refusal is reported as-is.
+            const buyerKey = process.env.PAYDLUX_BUYER_SECRET;
+            const res = await agent.get(url, { body, buyerKey });
+            const needsApproval = !res.ok && (res.handle || res.statusUrl);
+            return text({
+                ok: res.ok,
+                status: res.status,
+                data: clip(res.data),
+                tx: res.tx,
+                order: res.order,
+                escrow: res.escrow,
+                needs_approval: needsApproval || undefined,
+                handle: res.handle,
+                status_url: res.statusUrl,
+                desk: res.desk ? `${res.desk} (open this yourself — it needs the human's portal key)` : undefined,
+                reason: res.reason,
+                error: res.error,
+                requirements: res.requirements,
+                next: needsApproval
+                    ? "tell the human to approve on their desk, then call paydlux_payment_status with status_url and handle"
+                    : undefined,
+            });
+        });
+        server.registerTool("paydlux_payment_status", {
+            title: "Did the human approve?",
+            description: "One status check on a parked payment, using the status_url and handle paydlux_buy returned. Polls the seller's gateway, which needs no key. Returns the settled record (with the tx hash) once decided, or the current pending state.",
+            inputSchema: {
+                status_url: z.string().url().describe("The status_url from paydlux_buy — never the desk link"),
+                handle: z.string().describe("The payment handle from paydlux_buy"),
+                wait_seconds: z.number().int().min(0).max(120).optional().describe("Keep polling up to this long inside the call. Default 0 = one check"),
+            },
+        }, async ({ status_url, handle, wait_seconds }) => {
+            const agent = new PaydluxAgent({
+                agentKey: cfg.agentSeed, network: cfg.network,
+                approvalTimeoutMs: (wait_seconds ?? 0) * 1000 + 2_000, pollMs: 2_000,
+            });
+            const rec = wait_seconds ? await agent.waitForApproval({ statusUrl: status_url }, handle)
+                : await fetch(status_url).then((r) => (r.ok ? r.json() : null)).catch(() => null);
+            if (!rec)
+                return text({ ok: true, status: "pending", handle, note: "no decision yet — check again in a few seconds" });
+            return text({ ok: true, decision: rec });
+        });
+    }
+    return server;
+}
+// ------------------------------------------------------------------- main
+export async function start() {
+    const file = resolve(process.cwd(), arg("file") ?? process.env.PAYDLUX_VAULT_FILE ?? "paydlux-vault.json");
+    const cfg = load(file);
+    const server = buildServer(cfg);
+    await server.connect(new StdioServerTransport());
+    // stdout is the JSON-RPC channel. Any human-facing line goes to stderr.
+    console.error(`paydlux mcp: ${cfg.network} vault ${cfg.vault}, token ${cfg.token.code}, tools ${cfg.readOnly ? "read-only" : "read + buy"}. ${HOME}`);
+}
+// Run only when this file is the entry point, so importing it in a check is
+// safe. Compare realpaths, not the invocation string: npm's bin launcher runs
+// this as .../node_modules/.bin/paydlux-mcp, which does not end in .js, so a
+// name-based test silently turns the published command into a no-op.
+const invoked = process.argv[1]
+    ? pathToFileURL(existsSync(process.argv[1]) ? realpathSync(process.argv[1]) : process.argv[1]).href
+    : undefined;
+if (invoked === import.meta.url) {
+    start().catch((e) => { console.error("paydlux mcp failed:", e.message); process.exit(1); });
+}

package/dist/showcase.d.ts

@@ -42,6 +42,20 @@ export interface DemoConfig {
     donateHost?: string;
     /** Called whenever a key is enrolled, so the gateway's accepted set follows. */
     onKeys?: (pubs: string[]) => void;
+    /**
+     * The route the showcase sells (e.g. "/market/data"). /demo/last only reports
+     * settled payments for THIS route, so a seller's private sales never appear
+     * on a public page — a settled demo payment is the proof being shown, not the
+     * seller's order book.
+     */
+    route?: string;
+    /**
+     * The address the seller gets paid at. /demo/last uses it to read the last
+     * real settlement straight off the ledger, so the proof survives a restart of
+     * the demo process — an investor visiting at 3am, with the seller asleep,
+     * still gets a hash that exists on a public explorer.
+     */
+    payee?: string;
 }
 /**
  * Serve the showcase in front of a running gateway.

package/dist/showcase.js

@@ -103,6 +103,43 @@ function demoPayload(cfg) {
         proof: cfg.explorer,
     }, null, 2);
 }
+/**
+ * The last payment this vault really made to the seller, read off the public
+ * ledger. The in-memory desk forgets on restart; the ledger does not, so an
+ * investor who visits while the seller is asleep still reaches a hash they can
+ * open on an explorer instead of a spinner. Cached — one page load should not
+ * hammer horizon, and the answer only moves when a payment settles.
+ */
+let ledgerProof = null;
+let ledgerProofAt = 0;
+async function lastSettledOnLedger(cfg) {
+    if (!cfg.payee)
+        return null;
+    if (ledgerProof && Date.now() - ledgerProofAt < 5 * 60 * 1000)
+        return ledgerProof;
+    const host = cfg.network === "public" ? "horizon.stellar.org" : "horizon-testnet.stellar.org";
+    try {
+        const r = await fetch(`https://${host}/accounts/${cfg.vault}/payments?order=desc&limit=25`, { signal: AbortSignal.timeout(4000) });
+        if (!r.ok)
+            return null;
+        const records = ((await r.json())?._embedded?.records) ?? [];
+        for (const p of records) {
+            // horizon calls the hash `transaction_hash`; a record without one is not a
+            // proof, so it is skipped rather than printed as "undefined".
+            if (p?.to !== cfg.payee || !(Number(p.amount) > 0) || !p.transaction_hash)
+                continue;
+            ledgerProof = {
+                at: Date.parse(p.created_at) || 0,
+                price: String(p.amount),
+                tx: String(p.transaction_hash),
+            };
+            ledgerProofAt = Date.now();
+            return ledgerProof;
+        }
+    }
+    catch { /* no ledger reachable: the page still works, just without the extra proof */ }
+    return null;
+}
 /**
  * Serve the showcase in front of a running gateway.
  *
@@ -193,10 +230,32 @@ export function startDemo(cfg) {
             res.end(JSON.stringify({ ok: true, until: ok.until, vault: cfg.vault }));
             return;
         }
+        // A visitor watching alone cannot finish step 4 — the seller's phone is the
+        // only thing that can sign it, and the seller may be asleep. The loop is
+        // worthless as a demo if it ends at "waiting", so hand them the most recent
+        // payment this route actually settled: a hash they can open on the explorer
+        // without trusting this page. Nothing else about the payment is returned —
+        // a tx hash is already public on the ledger, the buyer and the content are
+        // not.
+        if (p === "/demo/last") {
+            const done = cfg.gateway.desk.list()
+                .filter((r) => r.status === "settled" && r.tx && (!cfg.route || r.uri === cfg.route))
+                .sort((a, b) => b.at - a.at)[0];
+            const proof = done
+                ? { at: done.at, price: done.price, tx: done.tx }
+                : await lastSettledOnLedger(cfg);
+            res.writeHead(200, {
+                "content-type": "application/json",
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+            });
+            res.end(JSON.stringify(proof ?? { none: true }));
+            return;
+        }
         // Everything else belongs to the gateway: the paid route, /pay/status.
         // Only demo paths are exposed here, so pointing the tunnel at this port
         // cannot reach a seller's private routes by guessing a URI.
-        if (!(p === DEMO_ROUTE || p === "/pay/status" || p === "/demo/terms")) {
+        if (!(p === DEMO_ROUTE || p === "/pay/status" || p === "/demo/terms" || p === "/demo/last")) {
             res.writeHead(404, { "content-type": "application/json" });
             res.end(JSON.stringify({ error: "not found", routes: [DEMO_ROUTE] }));
             return;
@@ -244,6 +303,7 @@ h1{font-size:30px;margin:0 0 6px;letter-spacing:-.01em}
 pre{margin:10px 0 0;padding:10px 12px;background:#0f1213;border:1px solid var(--line);border-radius:8px;font:12.5px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre-wrap;word-break:break-word;color:#cfd6d0}
 button{font:inherit;padding:11px 18px;border-radius:9px;border:1px solid var(--gold);background:var(--gold);color:#1a1408;font-weight:600;cursor:pointer;margin:22px 0 0}
 button[disabled]{opacity:.45;cursor:default}
+.note{margin:12px 0 0;color:var(--dim);font-size:14px}
 .door{margin:30px 0 0;border:1px solid var(--line);border-left:3px solid var(--gold);background:#1a1f21;border-radius:10px;padding:18px 20px}
 .door .q{margin:0 0 6px;font-weight:600}
 .door .a{margin:0;color:var(--dim);font-size:15px}
@@ -275,8 +335,8 @@ on a phone, and the ledger settles it. You are about to drive that loop.</p>
   <div class="step" id="s3"><h3><span class="n">3</span>Request the payment</h3>
     <p>The browser signs the request — not the payment — and sends it. The seller parks it for a human.</p>
     <pre id="o3">not run</pre></div>
-  <div class="step" id="s4"><h3><span class="n">4</span>A human decides</h3>
-    <p>The seller sees the exact payment on their phone and holds for 1.2 seconds to approve. Nothing here can skip that.</p>
+  <div class="step" id="s4"><h3><span class="n">4</span>A human decides — and it isn't you</h3>
+    <p>The buyer half ends at step 3. From here the <b>seller</b> decides: the parked payment appears on their phone with the amount, the payee and the deadline, and a person holds the button for 1.2 seconds. The key that signs it never leaves that device, so no code — including this page — can do it for them. The app only checks the queue while it is open on the screen, so a phone in a pocket signs nothing: if nobody is holding it, this step waits. That is the product, not a bug.</p>
     <pre id="o4">not run</pre></div>
   <div class="step" id="s5"><h3><span class="n">5</span>The ledger proves it</h3>
     <p>Same request, now served. The transaction hash is public and verifiable without trusting this page.</p>
@@ -284,6 +344,9 @@ on a phone, and the ledger settles it. You are about to drive that loop.</p>
 </div>
 
 <button id="go">Run the loop</button>
+<p class="note">You are the <b>buyer</b> here. Steps 1–3 happen in your browser. Step 4 happens on the
+seller's phone — if nobody is holding it, this page will show you the last payment this exact loop
+settled, with a hash you can open on the explorer.</p>
 
 <div class="door">
   <p class="q">That was practice. Nothing you just did cost anything.</p>
@@ -312,6 +375,8 @@ function demoScript() {
   const el = (id) => document.getElementById(id);
   const say = (n, txt) => { el("o" + n).textContent = txt; el("s" + n).classList.add("done"); };
   const PAY = "x-payment";
+  let NET = "testnet";   // which explorer the proof links point at
+  let TOKEN = "";        // the token the demo is priced in, for readable amounts
 
   async function main() {
     const btn = el("go"); btn.disabled = true;
@@ -321,6 +386,8 @@ function demoScript() {
     try {
       const r = await fetch(ROUTE, { cache: "no-store" });
       terms = JSON.parse(r.headers.get(PAY) || "null");
+      NET = String((terms && terms.network) || "testnet").replace("stellar:", "");
+      TOKEN = String((terms && terms.token && terms.token.code) || "");
       say(1, "HTTP " + r.status + "\\n" + JSON.stringify(terms, null, 2));
       if (r.status !== 402) { say(1, "HTTP " + r.status + " — this showcase is not asking for payment right now"); return; }
     } catch (e) { say(1, "request failed: " + e); return; }
@@ -352,8 +419,18 @@ function demoScript() {
     say(3, "HTTP 202 — parked as " + (parked.handle || "?") + "\\n" + (parked.reason || ""));
 
     // 4 — wait for a person. The page polls the seller's own status route.
-    say(4, "waiting for the seller's phone…");
+    // Say plainly what is happening: the seller's phone is the only thing that
+    // can sign this, and a visitor on their own laptop cannot make that happen.
+    // Bare silence here reads as a broken demo.
+    say(4, "parked. Now the seller's phone decides — that signature cannot come from this browser.\\nwaiting…");
     const seen = await poll(parked.statusUrl);
+    if (seen.status === "timed out waiting for a human") {
+      el("o4").textContent = "nobody signed, so nothing was paid — exactly as designed.\\n"
+        + "Run the loop again when the seller is at their phone.";
+      await showLast();
+      btn.disabled = false;
+      return;
+    }
     say(4, "status: " + seen.status + (seen.reason ? "\\n" + seen.reason : ""));
     if (seen.status !== "settled" && seen.status !== "paid") { btn.disabled = false; return; }
 
@@ -375,11 +452,29 @@ function demoScript() {
     for (let i = 0; i < 150; i++) {
       const j = await (await fetch(u, { cache: "no-store" })).json();
       if (j.status && j.status !== "pending" && j.status !== "awaiting_phone") return j;
+      // ~16 s with nobody at the phone: show that this loop does settle, instead
+      // of letting a visitor sit on a spinner and conclude the product is fake.
+      if (i === 8) await showLast();
       await new Promise((r) => setTimeout(r, 2000));
     }
     return { status: "timed out waiting for a human" };
   }
 
+  /**
+   * The most recent payment THIS route settled, as a public hash. It is not a
+   * substitute for the live approval — it is labelled as a different payment —
+   * it is the answer to "okay, but has this ever actually happened?".
+   */
+  async function showLast() {
+    try {
+      const last = await (await fetch("/demo/last", { cache: "no-store" })).json();
+      if (!last || !last.tx) return;
+      el("o4").textContent += "\\n\\nthe same loop, settled for real on " + new Date(last.at).toLocaleString()
+        + " (" + Number(last.price) + (TOKEN ? " " + TOKEN : "") + ") — verify it without this page:\\nhttps://stellar.expert/explorer/"
+        + NET + "/transaction/" + last.tx;
+    } catch { /* the demo still works without the extra proof */ }
+  }
+
   el("go").addEventListener("click", main);
 })();`;
 }

package/dist/vault.d.ts

@@ -171,6 +171,19 @@ export declare class StellarVault {
      * so a stolen agent key cannot use it and a stolen phone cannot use it alone.
      */
     release(payee: string, amount: Amount, principal: Keypair, approver: Keypair, memo?: string): Promise<Horizon.HorizonApi.SubmitTransactionResponse>;
+    /**
+     * Create an account that does not exist yet, with a starting balance. Same two
+     * signatures as release(), because it is the vault's money moving.
+     *
+     * This exists because a plain payment to an address that has never been
+     * funded is refused by the ledger (`op_no_destination`) — proven on the mainnet
+     * vault when topping up the demo's agent account. So "send XLM to a brand new
+     * wallet" (the demo agent, a seller's fresh payee, an owner's new cold
+     * account) needs createAccount, not payment. Only XLM can do this: a token
+     * payment to an unfunded account can never work, because that account would
+     * also need a trustline.
+     */
+    fund(destination: string, amount: Amount, principal: Keypair, approver: Keypair, memo?: string): Promise<Horizon.HorizonApi.SubmitTransactionResponse>;
     /**
      * Kill every outstanding mandate at once. Any accepted transaction bumps the
      * vault's sequence, which invalidates all pre-authorized hashes pointing at a

package/dist/vault.js

@@ -395,6 +395,28 @@ export class StellarVault {
             b.addMemo(Memo.text(memo));
         return sub(this.horizon, PASSPHRASE[this.network], b.build(), principal, approver);
     }
+    /**
+     * Create an account that does not exist yet, with a starting balance. Same two
+     * signatures as release(), because it is the vault's money moving.
+     *
+     * This exists because a plain payment to an address that has never been
+     * funded is refused by the ledger (`op_no_destination`) — proven on the mainnet
+     * vault when topping up the demo's agent account. So "send XLM to a brand new
+     * wallet" (the demo agent, a seller's fresh payee, an owner's new cold
+     * account) needs createAccount, not payment. Only XLM can do this: a token
+     * payment to an unfunded account can never work, because that account would
+     * also need a trustline.
+     */
+    async fund(destination, amount, principal, approver, memo) {
+        if (!this.isNative)
+            throw new Error("only XLM can create an account; a token needs a trustline first");
+        const b = (await this.tb(this.address))
+            .addOperation(Operation.createAccount({ destination, startingBalance: amount }))
+            .setTimeout(300);
+        if (memo)
+            b.addMemo(Memo.text(memo));
+        return sub(this.horizon, PASSPHRASE[this.network], b.build(), principal, approver);
+    }
     /**
      * Kill every outstanding mandate at once. Any accepted transaction bumps the
      * vault's sequence, which invalidates all pre-authorized hashes pointing at a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Payments for AI agents that a human approves. Spending mandates enforced on the Stellar ledger: 2-of-2 vault, pre-authorised transaction envelopes, HTTP 402, USDC.",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js dist/mcp.js",
     "test:dist": "npm run build && tsx stellar/dist-check.ts",
     "demo": "node sdk/demo.ts",
     "demo:stellar": "tsx stellar/demo.ts",
@@ -52,6 +52,8 @@
     "test:seed": "DEVELOPER_DIR=/Library/Developer/CommandLineTools /usr/bin/swiftc -target arm64-apple-macosx14.0 ios/PaydluxApprover/Seed.swift ios/PaydluxApprover/Hex.swift ios/Checks/main.swift -o \"$TMPDIR/seedcheck\" && \"$TMPDIR/seedcheck\"",
     "typecheck": "tsc --noEmit",
     "app": "tsx stellar/cli.ts",
+    "mcp": "tsx stellar/mcp.ts",
+    "test:mcp": "tsx stellar/mcp-check.ts",
     "app:mainnet": "tsx stellar/cli.ts setup --mainnet --file paydlux-mainnet.json --token XLM --max 2 --daily 20",
     "fund:check": "tsx stellar/check-address.ts GARPB3CO3JMMED3ETFRSSZXCH2X7UTXW4FNUP3Z7HDMBKAC2H355W4SA",
     "test:showcase": "tsx stellar/showcase-check.ts",
@@ -61,7 +63,13 @@
     "test:donate": "tsx stellar/donate-check.ts",
     "donate:live": "tsx stellar/donate-live.ts",
     "app:mainnet:sell": "tsx stellar/cli.ts sell --file paydlux-mainnet.json --split --tls --price 1 --route /market/data --max 2 --daily 20",
+    "app:mainnet:fund": "bash tools/fund-demo-wallet.sh",
+    "loop:check": "tsx stellar/mainnet-loop-check.ts",
     "app:testnet:sell": "tsx stellar/cli.ts sell --split --tls --showcase --price 1 --route /market/data --max 10 --daily 50",
+    "app:demo": "tsx stellar/cli.ts demo",
+    "app:demo:build": "bash tools/make-demo-app.sh",
+    "app:mainnet:build": "bash tools/make-demo-app.sh --mainnet",
+    "tunnel:service": "bash tools/install-tunnel-service.sh",
     "app:donate": "tsx stellar/cli.ts donate --file paydlux-mainnet.json --tls --price 1",
     "site:qr": "tsx stellar/make-site-qr.ts paydlux-mainnet.json site/qr.svg",
     "address:check": "tsx stellar/check-address.ts",
@@ -93,18 +101,23 @@
     "access": "public"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@stellar/stellar-sdk": "^17.4.0",
-    "qrcode-generator": "^2.0.4"
+    "qrcode-generator": "^2.0.4",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^26.6.6",
     "jsqr": "^1.4.0",
+    "qrcode": "^1.5.4",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "viem": "^2.57.13",
+    "wrangler": "^4.158.0",
     "xrpl": "^5.3.0"
   },
   "bin": {
-    "paydlux": "dist/cli.js"
+    "paydlux": "dist/cli.js",
+    "paydlux-mcp": "dist/mcp.js"
   }
 }