stellar-tollbooth 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# stellar-tollbooth
+
+**Give your coding agent a Stellar wallet.**
+
+An MCP server that holds a wallet. When your agent calls a paid tool, it settles in XLM
+over [x402](https://developers.stellar.org/docs/build/agentic-payments/x402) on Stellar —
+around three seconds, network fee sponsored by the facilitator. No card, no signup, no API key.
+
+> **Testnet only.** This handles a Stellar secret key. Use throwaway testnet accounts.
+
+## Install
+
+```bash
+claude mcp add tollbooth \
+  --env STELLAR_SECRET_KEY=S... \
+  --env TOLLBOOTH_API=https://tollbooth-equinox.vercel.app \
+  -- npx -y stellar-tollbooth
+```
+
+Or get a funded wallet and register it in one step:
+
+```bash
+curl -fsSL https://tollbooth-equinox.vercel.app/install.sh | bash
+```
+
+## Tools
+
+| tool | price | |
+|---|---|---|
+| `wallet_balance` | free | address, balance, remaining budget |
+| `test_payment` | 0.01 XLM | smallest real payment — proves the wallet works |
+| `raven_search` | 0.05 XLM | Stellar ecosystem search |
+| `raven_execute` | 0.25 XLM | composed sandboxed queries |
+| `pay_and_fetch` | varies | pay **any** x402 URL |
+
+Every paid result carries a receipt — amount, measured settlement time, tx hash, explorer link.
+
+## Configuration
+
+| env | default | |
+|---|---|---|
+| `STELLAR_SECRET_KEY` | — | **required**; the agent's wallet |
+| `TOLLBOOTH_API` | `http://localhost:3000` | the paid API |
+| `STELLAR_NETWORK` | `stellar:testnet` | CAIP-2 network id |
+| `TOLLBOOTH_SESSION_BUDGET` | `5` | cumulative XLM cap for the process |
+| `TOLLBOOTH_MAX_PER_CALL` | `5000000` | per-payment cap, atomic units (0.5 XLM) |
+
+Two caps, because they do different jobs: x402's own `spendControls` limits each
+*individual* payment, so an agent in a loop could still drain a wallet one capped payment
+at a time. `TOLLBOOTH_SESSION_BUDGET` is the cumulative ceiling.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ADDRESS, API, BudgetExceeded, NETWORK, agentHeaders, balanceXlm, paidPost, payingFetch, remainingXlm, spentXlm, } from "./wallet.js";
+const PRICES = { ping: 0.01, search: 0.05, execute: 0.25 };
+const explorer = (tx) => `https://stellar.expert/explorer/testnet/tx/${tx}`;
+/**
+ * The receipt is rendered into the TOOL RESULT, not just logged.
+ *
+ * This is deliberate and load-bearing for the live demo: stderr from an MCP server is
+ * not reliably surfaced by every client, but tool result content always renders in the
+ * transcript. The payment has to be visible on screen or the whole premise is invisible.
+ */
+function receiptBlock(r) {
+    return [
+        "",
+        "  ┌─ paid via x402 on Stellar ─────────────",
+        `  │ amount     ${r.priceXlm} XLM`,
+        `  │ settled    ${(r.settledMs / 1000).toFixed(1)}s`,
+        `  │ network    ${NETWORK}  (fees sponsored)`,
+        r.txHash ? `  │ tx         ${r.txHash.slice(0, 16)}…` : "  │ tx         (pending)",
+        r.txHash ? `  │ explorer   ${explorer(r.txHash)}` : "  │",
+        `  │ spent      ${spentXlm().toFixed(4)} XLM this session · ${remainingXlm().toFixed(4)} left`,
+        "  └────────────────────────────────────────",
+    ].join("\n");
+}
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+/** Free precheck, so an unlinked attendee is never charged for a call that must fail. */
+async function linkStatus() {
+    try {
+        const r = await fetch(`${API}/api/link-status?agent=${ADDRESS}`);
+        return (await r.json());
+    }
+    catch {
+        return { linked: true, linkUrl: `${API}/auth/start?agent=${ADDRESS}` }; // don't block on a probe failure
+    }
+}
+const needsLink = (s) => text(`Your raven account isn't linked to this wallet yet, so nothing was charged.\n\n` +
+    `Link it once (opens raven sign-in):\n  ${s.linkUrl}\n\nThen run this tool again.`);
+async function runPaid(path, body, priceXlm, label) {
+    const status = await linkStatus();
+    if (!status.linked)
+        return needsLink(status);
+    try {
+        const { ok, status: code, json, receipt } = await paidPost(path, body, priceXlm);
+        if (!ok) {
+            if (code === 409)
+                return needsLink(json);
+            return text(`${label} failed (HTTP ${code}): ${JSON.stringify(json)}`);
+        }
+        const payload = "result" in json ? json.result : json;
+        return text(`${JSON.stringify(payload, null, 2)}\n${receiptBlock(receipt)}`);
+    }
+    catch (e) {
+        if (e instanceof BudgetExceeded)
+            return text(`Payment refused by local spend cap.\n\n${e.message}`);
+        return text(`${label} failed: ${e.message}`);
+    }
+}
+const server = new McpServer({ name: "tollbooth", version: "0.1.0" });
+server.registerTool("wallet_balance", {
+    title: "Agent wallet balance",
+    description: "Show this agent's own Stellar wallet address, XLM balance and remaining spend budget. Free.",
+    inputSchema: {},
+}, async () => {
+    const bal = await balanceXlm().catch((e) => `unavailable (${e.message})`);
+    return text([
+        `address    ${ADDRESS}`,
+        `balance    ${bal} XLM`,
+        `network    ${NETWORK}`,
+        `spent      ${spentXlm().toFixed(4)} XLM this session`,
+        `remaining  ${remainingXlm().toFixed(4)} XLM of session budget`,
+    ].join("\n"));
+});
+server.registerTool("raven_search", {
+    title: "Search the Stellar ecosystem (paid)",
+    description: `Search Stellar ecosystem knowledge via raven: operations, skills, projects, repos and docs. ` +
+        `Costs ${PRICES.search} XLM per call, paid automatically from this agent's wallet over x402.`,
+    inputSchema: { query: z.string().describe("What to search for"), limit: z.number().optional() },
+}, async ({ query, limit }) => runPaid("/paid/raven/search", { query, limit }, PRICES.search, "raven_search"));
+server.registerTool("raven_execute", {
+    title: "Run composed Stellar queries (paid)",
+    description: `Run a sandboxed JavaScript script composing raven operations (Promise.all across services, ` +
+        `then follow-up calls). Costs ${PRICES.execute} XLM per call, paid automatically over x402.`,
+    inputSchema: { code: z.string().describe("Sandboxed JS script to run against raven services") },
+}, async ({ code }) => runPaid("/paid/raven/execute", { code }, PRICES.execute, "raven_execute"));
+server.registerTool("test_payment", {
+    title: "Test that this agent can pay",
+    description: `Make the smallest real payment on the system (${PRICES.ping} XLM) to prove this ` +
+        `agent's wallet works end to end. Needs no raven account. Use this first if payments fail.`,
+    inputSchema: {},
+}, async () => {
+    try {
+        const { ok, status, json, receipt } = await paidPost("/paid/demo/ping", {}, PRICES.ping);
+        if (!ok)
+            return text(`test_payment failed (HTTP ${status}): ${JSON.stringify(json)}`);
+        return text(`${json.message ?? "paid"}\n${receiptBlock(receipt)}`);
+    }
+    catch (e) {
+        if (e instanceof BudgetExceeded)
+            return text(`Payment refused by local spend cap.\n\n${e.message}`);
+        return text(`test_payment failed: ${e.message}`);
+    }
+});
+server.registerTool("pay_and_fetch", {
+    title: "Pay any x402 URL",
+    description: "Fetch ANY x402-protected URL, paying automatically in XLM from this agent's wallet. " +
+        "The generic primitive: point it at your own paid endpoint to test it.",
+    inputSchema: {
+        url: z.string().describe("An x402-protected URL"),
+        method: z.enum(["GET", "POST"]).optional(),
+        body: z.string().optional().describe("JSON string body for POST"),
+    },
+}, async ({ url, method = "GET", body }) => {
+    const t0 = Date.now();
+    try {
+        // Identity headers go ONLY to our own API. Sending a signed wallet assertion to
+        // an arbitrary third-party URL would leak this agent's address for no reason.
+        const own = url.startsWith(API);
+        const path = own ? new URL(url).pathname : "";
+        const res = await payingFetch(url, {
+            method,
+            headers: {
+                ...(body ? { "Content-Type": "application/json" } : {}),
+                ...(own ? agentHeaders(path) : {}),
+            },
+            ...(body ? { body } : {}),
+        });
+        const txt = await res.text();
+        const raw = res.headers.get("payment-response") ?? res.headers.get("x-payment-response");
+        let txHash;
+        if (raw) {
+            try {
+                txHash = JSON.parse(Buffer.from(raw, "base64").toString()).transaction;
+            }
+            catch { }
+        }
+        const settledMs = Date.now() - t0;
+        const paid = Boolean(txHash);
+        return text(`HTTP ${res.status}\n${txt.slice(0, 4000)}` +
+            (paid ? receiptBlock({ priceXlm: 0, ms: settledMs, txHash, settledMs }) : `\n(no payment was required)`));
+    }
+    catch (e) {
+        return text(`pay_and_fetch failed: ${e.message}`);
+    }
+});
+await server.connect(new StdioServerTransport());
+console.error(`[tollbooth] ready · agent ${ADDRESS} · api ${API}`);

package/dist/wallet.js

@@ -0,0 +1,84 @@
+import { Keypair, Horizon } from "@stellar/stellar-sdk";
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { createEd25519Signer } from "@x402/stellar";
+import { ExactStellarScheme } from "@x402/stellar/exact/client";
+export const NETWORK = (process.env.STELLAR_NETWORK ?? "stellar:testnet");
+export const NATIVE_SAC = process.env.NATIVE_SAC ?? "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC";
+export const API = (process.env.TOLLBOOTH_API ?? "http://localhost:3000").replace(/\/$/, "");
+export const HORIZON = process.env.HORIZON_URL ?? "https://horizon-testnet.stellar.org";
+/** Per-payment ceiling, in atomic XLM units (7dp). */
+const MAX_PER_CALL = process.env.TOLLBOOTH_MAX_PER_CALL ?? "5000000"; // 0.5 XLM
+/** Cumulative ceiling for this process, in XLM. */
+const SESSION_BUDGET = Number(process.env.TOLLBOOTH_SESSION_BUDGET ?? 5);
+const secret = process.env.STELLAR_SECRET_KEY ?? "";
+if (!secret) {
+    console.error("[tollbooth] STELLAR_SECRET_KEY is not set. Run the installer to mint a funded testnet wallet.");
+    process.exit(1);
+}
+export const keypair = Keypair.fromSecret(secret);
+export const ADDRESS = keypair.publicKey();
+export class BudgetExceeded extends Error {
+}
+let spent = 0;
+export const spentXlm = () => spent;
+export const remainingXlm = () => Math.max(0, SESSION_BUDGET - spent);
+/**
+ * x402's own spendControls caps each INDIVIDUAL payment, not the total. An agent in a
+ * loop would happily drain a wallet one capped payment at a time, so the cumulative
+ * budget below is enforced here as well.
+ */
+function assertBudget(priceXlm) {
+    if (spent + priceXlm > SESSION_BUDGET) {
+        throw new BudgetExceeded(`session budget exhausted: spent ${spent.toFixed(4)} of ${SESSION_BUDGET} XLM; ` +
+            `this call needs ${priceXlm}. Raise TOLLBOOTH_SESSION_BUDGET to continue.`);
+    }
+}
+const signer = createEd25519Signer(secret, NETWORK);
+export const payingFetch = wrapFetchWithPaymentFromConfig(fetch, {
+    schemes: [{ network: NETWORK, client: new ExactStellarScheme(signer) }],
+    spendControls: {
+        // Native XLM is NOT one of x402's "default assets" (those are USDC only), so it
+        // must be opted in explicitly or the client refuses before any network call.
+        // maxAmountPerPayment is ATOMIC units here, not a "$1" string.
+        allowedAssets: [{ network: NETWORK, asset: NATIVE_SAC, maxAmountPerPayment: MAX_PER_CALL }],
+    },
+});
+/** Identity headers. Must match the server's challenge format in lib/identity.ts. */
+export function agentHeaders(path) {
+    const ts = String(Date.now());
+    const msg = `tollbooth:${ADDRESS}:${ts}:${path}`;
+    return {
+        "x-agent": ADDRESS,
+        "x-agent-ts": ts,
+        "x-agent-sig": Buffer.from(keypair.sign(Buffer.from(msg, "utf8"))).toString("base64"),
+    };
+}
+/** POST to a paid tollbooth route: budget check, pay, settle, return body + receipt. */
+export async function paidPost(path, body, priceXlm) {
+    assertBudget(priceXlm);
+    const t0 = Date.now();
+    const res = await payingFetch(`${API}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...agentHeaders(path) },
+        body: JSON.stringify(body),
+    });
+    const settledMs = Date.now() - t0;
+    const json = (await res.json().catch(() => ({})));
+    let txHash;
+    const raw = res.headers.get("payment-response") ?? res.headers.get("x-payment-response");
+    if (raw) {
+        try {
+            txHash = JSON.parse(Buffer.from(raw, "base64").toString()).transaction;
+        }
+        catch {
+            /* receipt is a nicety, never fail the call over it */
+        }
+    }
+    if (res.ok)
+        spent += priceXlm;
+    return { ok: res.ok, status: res.status, json, receipt: { priceXlm, ms: settledMs, txHash, settledMs } };
+}
+export async function balanceXlm() {
+    const acct = await new Horizon.Server(HORIZON).loadAccount(ADDRESS);
+    return acct.balances.find((b) => b.asset_type === "native")?.balance ?? "0";
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "stellar-tollbooth",
+  "version": "0.1.0",
+  "description": "Give your coding agent a Stellar wallet. Paid MCP tools settled in XLM over x402.",
+  "type": "module",
+  "bin": {
+    "tollbooth": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@stellar/stellar-sdk": "^17.1.0",
+    "@x402/core": "^2.26.0",
+    "@x402/fetch": "^2.26.0",
+    "@x402/stellar": "^2.26.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT",
+  "author": "Wlad Mendes",
+  "keywords": [
+    "mcp",
+    "stellar",
+    "x402",
+    "agent",
+    "payments",
+    "soroban",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wmendes/tollbooth.git"
+  }
+}