autonomo-sdk 0.1.0 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Autonomo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Autonomo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,106 +1,161 @@
-# Autonomo SDK for TypeScript
-
-One call for AI agents. Say what you need, and the SDK:
-
-1. **Finds the right API** on [Autonomo](https://autonomo.fun), from your words and the kind of input you give
-   (a token or wallet address, a transaction hash, a link).
-2. **Pays for it** with x402 on Robinhood Chain, in USDG or $AUTONOMO, whichever the wallet can afford.
-3. **Pays privately through [Gloam](https://gloam.trade)** when you ask, so the payment doesn't link to your wallet.
-4. **Borrows from a [Borro](https://borro.markets) credit line** when the wallet is short of USDG.
-5. **Keeps to your caps**: a most-per-call and a daily budget, checked before anything is signed.
-6. **Returns the answer and a receipt**: which API, how it was paid, the amount and the transaction link.
-
-```bash
-npm install autonomo-sdk
-```
-
-Full examples for each way to pay: [autonomo.fun/docs/sdk](https://autonomo.fun/docs/sdk).
-
-```ts
-import { Autonomo } from "autonomo-sdk";
-
-const autonomo = new Autonomo({ privateKey: process.env.AUTONOMO_WALLET_KEY });
-
-const { data, receipt } = await autonomo.call("is this token safe", {
-  input: "0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49",
-});
-console.log(data);
-console.log(receipt.route, receipt.amount, receipt.token, receipt.explorer);
-```
-
-Use a **new wallet just for the agent**, holding only what it may spend. A little USDG covers many calls (most APIs
-cost 0.01 USDG). Paying in $AUTONOMO needs a little ETH once, for a Permit2 approval. Node 20 or later.
-
-## Finding APIs without paying
-
-```ts
-const autonomo = new Autonomo(); // no key needed to look
-await autonomo.find("wallet holdings"); // best matches first
-await autonomo.quote("explain this transaction", { input: "0x…" }); // the API, the URL and every price
-```
-
-To skip the search, name the API: `autonomo.call("", { slug: "token-risk", path: "/risk/0x…" })`.
-
-## Limits
-
-```ts
-new Autonomo({
-  privateKey,
-  payWith: "auto", // or "usdg" / "autonomo"
-  limits: {
-    perCall: { usdg: "0.05", autonomo: "5000" }, // the defaults
-    daily: { usdg: "1", autonomo: "10000" }, // per UTC day; Gloam and Borro count as USDG
-  },
-});
-```
-
-A call over a limit is refused before anything is signed, with the reason. Spending is kept in
-`~/.autonomo/spend.json` (shared with the Python SDK); pass `spendStore: memoryStore()` or your own store to change
-that.
-
-## Private payments with Gloam
-
-`private: true` pays from a private Gloam balance through Gloam's own MCP server, `@gloamtrade/mcp`, running on your
-machine with its key and limits in `~/.gloam/agent.env`. The SDK calls its `gloam_fetch_paid` tool; Gloam cashes out
-exactly the price through its relay and calls the API with it. The SDK holds no Gloam keys, and no wallet key is needed.
-See the [SDK guide](https://autonomo.fun/docs/sdk) for the setup and a full example.
-
-```ts
-const autonomo = new Autonomo({
-  gloam: {
-    fetchPaid: async (args) => {
-      const out = await gloam.callTool({ name: "gloam_fetch_paid", arguments: args }); // an MCP client for @gloamtrade/mcp
-      return JSON.parse((out.content as Array<{ text: string }>)[0].text);
-    },
-  },
-});
-await autonomo.call("newest launches", { private: true });
-```
-
-A private call only ever pays through Gloam. If the API doesn't offer it, or Gloam isn't set up, it's refused, never
-sent as a public payment. The price includes Gloam's 0.5% cash-out fee.
-
-## Borrowing with Borro
-
-```ts
-const autonomo = new Autonomo({ privateKey, borro: { account: "0xYourCreditLine" } });
-```
-
-When the wallet can't afford a call, the SDK asks Borro's MCP server to prepare a borrow of just what it's short,
-sends it from the wallet (this needs a little ETH for gas), waits for the USDG and pays. The line needs x402 bills
-turned on; see [Pay with a Borro credit line](https://autonomo.fun/docs/borro). Borro's own daily limit still applies.
-
-## The receipt
-
-| Field | |
-| --- | --- |
-| `api` | The API's slug and name |
-| `route` | `usdg`, `autonomo`, `gloam` or `borro` |
-| `amount`, `token` | What was paid |
-| `payer`, `payTo` | The wallet (or "private (Gloam)") and the API's payment address |
-| `tx`, `explorer` | The payment transaction and its Blockscout link |
-| `borrowTxs`, `approveTx` | Borro borrows and the one-time Permit2 approval, when there were any |
-| `spentToday` | Today's total against the daily budget |
-
-Errors are `AutonomoError` with a `code` such as `cannot_pay`, `over_limit`, `no_private_option` or `payment_refused`.
-If an API fails after a payment is signed, the payment doesn't settle, so you aren't charged.
+# Autonomo SDK for TypeScript
+
+One call for AI agents. Say what you need, and the SDK:
+
+1. **Finds the right API** on [Autonomo](https://autonomo.fun), from your words and the kind of input you give
+   (a token or wallet address, a transaction hash, a link).
+2. **Pays for it** with x402 on Robinhood Chain, in USDG or $AUTONOMO, whichever the wallet can afford.
+3. **Pays privately through [Gloam](https://gloam.trade)** when you ask, so the payment doesn't link to your wallet.
+4. **Borrows from a [Borro](https://borro.markets) credit line** when the wallet is short of USDG.
+5. **Keeps to your caps**: a most-per-call and a daily budget, checked before anything is signed.
+6. **Returns the answer and a receipt**: which API, how it was paid, the amount and the transaction link.
+
+```bash
+npm install autonomo-sdk
+```
+
+Full examples for each way to pay: [autonomo.fun/docs/sdk](https://autonomo.fun/docs/sdk).
+
+```ts
+import { Autonomo } from "autonomo-sdk";
+
+const autonomo = new Autonomo({ privateKey: process.env.AUTONOMO_WALLET_KEY });
+
+const { data, receipt } = await autonomo.call("is this token safe", {
+  input: "0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49",
+});
+console.log(data);
+console.log(receipt.route, receipt.amount, receipt.token, receipt.explorer);
+```
+
+Use a **new wallet just for the agent**, holding only what it may spend. A little USDG covers many calls (most APIs
+cost 0.01 USDG). Paying in $AUTONOMO needs a little ETH once, for a Permit2 approval. Node 20 or later.
+
+## Finding APIs without paying
+
+```ts
+const autonomo = new Autonomo(); // no key needed to look
+await autonomo.find("wallet holdings"); // best matches first
+await autonomo.quote("explain this transaction", { input: "0x…" }); // the API, the URL and every price
+```
+
+To skip the search, name the API: `autonomo.call("", { slug: "token-risk", path: "/risk/0x…" })`.
+
+## From the terminal
+
+The package also installs a command, for people and for agents that run shell commands. `find`, `quote`, `spend` and
+`--dry-run` need no wallet:
+
+```bash
+npx autonomo-sdk find "wallet holdings"
+npx autonomo-sdk risk 0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49 --dry-run   # the price, without paying
+```
+
+To pay, put the agent wallet's key in `AUTONOMO_WALLET_KEY`. It's never taken as a flag, so it stays out of your
+shell history.
+
+```bash
+npx autonomo-sdk risk 0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49
+npx autonomo-sdk call "explain this transaction" 0x… --max 0.02 --daily 0.5 --json
+```
+
+| Command | |
+| --- | --- |
+| `find [words] [input]` | List APIs, best matches first |
+| `quote <words> [input]` | The API a call would use, and its prices |
+| `call <words> [input]` | Find the right API, pay for one call, print the answer |
+| `price [token]`, `launches [n]`, `risk <token>`, `tx <hash>`, `portfolio <wallet>`, `read <link>`, `offers <words>` | Shortcuts for the official APIs |
+| `spend` | Today's spending against your limits |
+
+`--max` and `--daily` set the USDG limits (`--max-autonomo` and `--daily-autonomo` for $AUTONOMO), `--pay-with`
+picks the token and `--borro <credit line>` borrows when the wallet is short. At a terminal it shows the price and
+asks before paying; `--yes` skips the question, and scripts are never asked. The answer goes to stdout and the
+receipt to stderr, so piping into `jq` works, and `--json` prints `{ data, receipt }` as one object. Exit codes: 0
+done, 1 failed, 2 bad usage, 3 over a limit, 4 can't pay, 5 payment refused, 6 no such API.
+
+After `npm install -g autonomo-sdk` the command is `autonomo`. (`npx autonomo` is someone else's package.)
+
+### Paying privately from the terminal
+
+```bash
+npx autonomo-sdk risk 0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49 --private --dry-run   # the private price
+npx autonomo-sdk risk 0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49 --private             # pay from Gloam
+```
+
+`--private` pays from your private Gloam balance, so the payment doesn't link to a wallet. The command starts Gloam's
+own server (`npx -y @gloamtrade/mcp`) on your machine for that one payment and stops it afterwards.
+
+- Set Gloam up once: its key and limits go in `~/.gloam/agent.env` and USDG goes into its private balance (see
+  [Pay privately with Gloam](https://autonomo.fun/docs/sdk#pay-privately-with-gloam)). The command never reads
+  Gloam's key, and Gloam's server is never given `AUTONOMO_WALLET_KEY`.
+- No `AUTONOMO_WALLET_KEY` is needed for private calls.
+- The price includes Gloam's fee and counts against `--max` and `--daily`. It can't be combined with `--pay-with`
+  or `--borro`.
+- Paying can take a few minutes, since Gloam builds the payment's proofs on your machine.
+- If Gloam paid but the API didn't answer, the error prints a payment header: run the same command again with
+  `--retry-header <header>` to get the answer without paying twice.
+
+## Limits
+
+```ts
+new Autonomo({
+  privateKey,
+  payWith: "auto", // or "usdg" / "autonomo"
+  limits: {
+    perCall: { usdg: "0.05", autonomo: "5000" }, // the defaults
+    daily: { usdg: "1", autonomo: "10000" }, // per UTC day; Gloam and Borro count as USDG
+  },
+});
+```
+
+A call over a limit is refused before anything is signed, with the reason. Spending is kept in
+`~/.autonomo/spend.json` (shared with the Python SDK); pass `spendStore: memoryStore()` or your own store to change
+that.
+
+## Private payments with Gloam
+
+`private: true` pays from a private Gloam balance through Gloam's own MCP server, `@gloamtrade/mcp`, running on your
+machine with its key and limits in `~/.gloam/agent.env`. The SDK calls its `gloam_fetch_paid` tool; Gloam cashes out
+exactly the price through its relay and calls the API with it. The SDK holds no Gloam keys, and no wallet key is needed.
+See the [SDK guide](https://autonomo.fun/docs/sdk) for the setup and a full example.
+
+```ts
+const autonomo = new Autonomo({
+  gloam: {
+    fetchPaid: async (args) => {
+      // gloam: an MCP client for @gloamtrade/mcp. A private payment can take a few minutes, so wait up to 5.
+      const out = await gloam.callTool({ name: "gloam_fetch_paid", arguments: args }, undefined, { timeout: 300_000 });
+      return JSON.parse((out.content as Array<{ text: string }>)[0].text);
+    },
+  },
+});
+await autonomo.call("newest launches", { private: true });
+```
+
+A private call only ever pays through Gloam. If the API doesn't offer it, or Gloam isn't set up, it's refused, never
+sent as a public payment. The price includes Gloam's cash-out fee (about 0.0105 USDG for a 0.01 call).
+
+## Borrowing with Borro
+
+```ts
+const autonomo = new Autonomo({ privateKey, borro: { account: "0xYourCreditLine" } });
+```
+
+When the wallet can't afford a call, the SDK asks Borro's MCP server to prepare a borrow of just what it's short,
+sends it from the wallet (this needs a little ETH for gas), waits for the USDG and pays. The line needs x402 bills
+turned on; see [Pay with a Borro credit line](https://autonomo.fun/docs/borro). Borro's own daily limit still applies.
+
+## The receipt
+
+| Field | |
+| --- | --- |
+| `api` | The API's slug and name |
+| `route` | `usdg`, `autonomo`, `gloam` or `borro` |
+| `amount`, `token` | What was paid |
+| `payer`, `payTo` | The wallet (or "private (Gloam)") and the API's payment address |
+| `tx`, `explorer` | The payment transaction and its Blockscout link |
+| `borrowTxs`, `approveTx` | Borro borrows and the one-time Permit2 approval, when there were any |
+| `spentToday` | Today's total against the daily budget |
+
+Errors are `AutonomoError` with a `code` such as `cannot_pay`, `over_limit`, `no_private_option` or `payment_refused`.
+If an API fails after a payment is signed, the payment doesn't settle, so you aren't charged.

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { type GloamSession } from "./gloam.js";
+import { type SpendStore } from "./index.js";
+/** Everything the CLI touches outside itself, so tests can swap it. */
+export type Io = {
+    env: Record<string, string | undefined>;
+    out: (text: string) => void;
+    err: (text: string) => void;
+    /** True when a person is at the terminal, so a paid call asks first. */
+    interactive: boolean;
+    confirm: (question: string) => Promise<boolean>;
+    fetch?: typeof fetch;
+    spendStore?: SpendStore;
+    /** Starts Gloam's server for --private. The default runs `npx -y @gloamtrade/mcp`. */
+    startGloam?: () => Promise<GloamSession>;
+};
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly overLimit: 3;
+    readonly cannotPay: 4;
+    readonly refused: 5;
+    readonly notFound: 6;
+};
+/** Runs one command and returns its exit code. `argv` is what follows the program name. */
+export declare function run(argv: string[], io: Io): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+// Autonomo CLI: the SDK from a terminal, for people and for agents that run shell commands.
+//
+//   npx autonomo-sdk find "wallet holdings"            look, free
+//   npx autonomo-sdk risk 0x… --dry-run                the price, without paying
+//   AUTONOMO_WALLET_KEY=0x… npx autonomo-sdk risk 0x…  pay and print the answer
+//   npx autonomo-sdk risk 0x… --private                pay from a private Gloam balance instead
+//
+// The answer goes to stdout and everything else (the receipt, questions, errors) to stderr, so `autonomo … | jq`
+// works. The wallet key is only ever read from AUTONOMO_WALLET_KEY, never from a flag, so it stays out of shell
+// history. The SDK's per-call cap and daily budget apply to every paid call. With --private the payment is made by
+// Gloam's own server, started on this machine with its own key and limits (see gloam.ts); no wallet key is needed.
+import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { formatUnits } from "viem";
+import { startGloam } from "./gloam.js";
+import { Autonomo, AutonomoError, DEFAULT_LIMITS, TOKENS, VERSION, fileStore } from "./index.js";
+export const EXIT = { ok: 0, failed: 1, usage: 2, overLimit: 3, cannotPay: 4, refused: 5, notFound: 6 };
+const HELP = `Autonomo CLI ${VERSION}: find and pay for APIs on autonomo.fun
+
+Usage
+  autonomo find [words] [input]     List APIs, best matches first. Free.
+  autonomo quote <words> [input]    The API a call would use and its prices. Free.
+  autonomo call <words> [input]     Find the right API, pay for one call, print the answer.
+  autonomo spend                    Today's spending against your limits.
+
+Shortcuts for the official APIs
+  autonomo price [token address]    $AUTONOMO's price, or any launchpad token's
+  autonomo launches [how many]      Newest token launches
+  autonomo risk <token address>     Rug-risk check
+  autonomo tx <transaction hash>    A transaction in plain words
+  autonomo portfolio <wallet>       What a wallet holds
+  autonomo read <https link>        A web page's text
+  autonomo offers <what you need>   Matching offers on Ostrapad
+
+Options
+  --max <usdg>              Most to pay for one call (default ${DEFAULT_LIMITS.perCall.usdg})
+  --daily <usdg>            Most to spend per UTC day (default ${DEFAULT_LIMITS.daily.usdg})
+  --max-autonomo <amount>   The same two limits when paying in $AUTONOMO
+  --daily-autonomo <amount> (defaults ${DEFAULT_LIMITS.perCall.autonomo} and ${DEFAULT_LIMITS.daily.autonomo})
+  --pay-with <token>        usdg, autonomo or auto (default: USDG, then $AUTONOMO)
+  --borro <credit line>     Borrow from this Borro line when the wallet is short of USDG
+  --private                 Pay from your private Gloam balance, so the payment doesn't link to a wallet
+  --retry-header <header>   With --private: finish a call Gloam paid for but the API didn't answer, without paying again
+  --slug <api> --path <p>   With call or quote: use this API and path, skipping the search
+  --dry-run                 Show the price instead of paying
+  --yes                     Don't ask before paying
+  --json                    One JSON object on stdout: { data, receipt }
+  --help, --version
+
+Wallet
+  Set AUTONOMO_WALLET_KEY to the private key of a wallet made just for the agent, holding only what it may spend.
+  find, quote, spend and --dry-run need no wallet.
+
+Private payments
+  --private starts Gloam's own server on this machine (npx @gloamtrade/mcp) and has it pay in USDG. It needs no
+  AUTONOMO_WALLET_KEY: Gloam uses its own key and limits from ~/.gloam/agent.env, and that key is never read by
+  this command. Deposit USDG into Gloam's private balance first. The price includes Gloam's fee, counts against
+  --max and --daily, and paying can take a few minutes. Setup: autonomo.fun/docs/sdk#pay-privately-with-gloam
+
+Exit codes
+  0 done   1 failed   2 bad usage   3 over a limit   4 can't pay   5 payment refused   6 no such API`;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const TX_HASH = /^0x[0-9a-fA-F]{64}$/;
+const AMOUNT = /^\d+(\.\d+)?$/;
+const GLOAM_SETUP = "Gloam needs its own key and limits in ~/.gloam/agent.env: autonomo.fun/docs/sdk#pay-privately-with-gloam";
+class UsageError extends Error {
+}
+const usage = (message) => {
+    throw new UsageError(message);
+};
+/** Each shortcut names its API and builds the path, so nothing is searched. */
+const SHORTCUTS = {
+    price: ([token]) => {
+        if (token === undefined)
+            return { slug: "token-price", path: "/price/autonomo" };
+        if (!ADDRESS.test(token))
+            usage("price takes a token contract address (0x and 40 hex characters), or nothing for $AUTONOMO.");
+        return { slug: "token-lookup", path: `/price/${token}` };
+    },
+    launches: ([count = "10"]) => {
+        if (!/^\d{1,3}$/.test(count) || Number(count) < 1)
+            usage("launches takes how many to show, e.g. autonomo launches 5.");
+        return { slug: "new-launches", path: `/launches?limit=${Number(count)}` };
+    },
+    risk: ([token]) => {
+        if (!token || !ADDRESS.test(token))
+            usage("risk takes a token contract address: autonomo risk 0x…");
+        return { slug: "token-risk", path: `/risk/${token}` };
+    },
+    tx: ([hash]) => {
+        if (!hash || !TX_HASH.test(hash))
+            usage("tx takes a transaction hash (0x and 64 hex characters).");
+        return { slug: "tx-explainer", path: `/tx/${hash}` };
+    },
+    portfolio: ([wallet]) => {
+        if (!wallet || !ADDRESS.test(wallet))
+            usage("portfolio takes a wallet address: autonomo portfolio 0x…");
+        return { slug: "wallet-portfolio", path: `/portfolio/${wallet}` };
+    },
+    read: ([link]) => {
+        if (!link || !/^https:\/\/\S+$/i.test(link))
+            usage("read takes an https:// link.");
+        return { slug: "page-reader", path: `/page?url=${encodeURIComponent(link)}` };
+    },
+    offers: (words) => {
+        const q = words.join(" ").trim();
+        if (!q)
+            usage('offers takes what you need done: autonomo offers "summarize a document"');
+        return { slug: "ostrapad-offer-finder", path: `/offers?q=${encodeURIComponent(q)}` };
+    },
+};
+const price = (api) => {
+    const parts = [api.price.usdg !== undefined && `${api.price.usdg} USDG`, api.price.autonomo !== undefined && `${api.price.autonomo} AUTONOMO`].filter(Boolean);
+    return parts.join(" or ") || "see quote";
+};
+function exitFor(e) {
+    if (e instanceof UsageError)
+        return EXIT.usage;
+    if (!(e instanceof AutonomoError))
+        return EXIT.failed;
+    if (e.code === "over_limit")
+        return EXIT.overLimit;
+    // cannot_pay covers both a limit and an empty wallet; the limit ones say "cap" or "budget".
+    if (e.code === "cannot_pay")
+        return /per-call cap|budget/.test(e.message) && !/the wallet holds/.test(e.message) ? EXIT.overLimit : EXIT.cannotPay;
+    if (e.code === "no_wallet" || e.code === "bad_key" || e.code === "no_gloam" || e.code === "no_private_option")
+        return EXIT.cannotPay;
+    if (e.code === "payment_refused" || e.code === "paid_not_served")
+        return EXIT.refused;
+    if (e.code === "not_found")
+        return EXIT.notFound;
+    return EXIT.failed;
+}
+/** Runs one command and returns its exit code. `argv` is what follows the program name. */
+export async function run(argv, io) {
+    let json = argv.includes("--json");
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                max: { type: "string" },
+                daily: { type: "string" },
+                "max-autonomo": { type: "string" },
+                "daily-autonomo": { type: "string" },
+                "pay-with": { type: "string" },
+                borro: { type: "string" },
+                private: { type: "boolean" },
+                "retry-header": { type: "string" },
+                slug: { type: "string" },
+                path: { type: "string" },
+                "dry-run": { type: "boolean" },
+                yes: { type: "boolean", short: "y" },
+                json: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+                key: { type: "string" },
+                "private-key": { type: "string" },
+            },
+        });
+        json = Boolean(values.json);
+        if (values.key !== undefined || values["private-key"] !== undefined) {
+            usage("The wallet key isn't taken as a flag, so it stays out of your shell history. Set AUTONOMO_WALLET_KEY instead.");
+        }
+        if (values.version)
+            return io.out(VERSION), EXIT.ok;
+        const [command, ...rest] = positionals;
+        if (values.help || command === undefined || command === "help")
+            return io.out(HELP), EXIT.ok;
+        const amount = (flag) => {
+            const v = values[flag];
+            if (v !== undefined && !AMOUNT.test(v))
+                usage(`--${flag} takes an amount in whole tokens, e.g. --${flag} 0.05.`);
+            return v;
+        };
+        const limits = {
+            perCall: { usdg: amount("max") ?? DEFAULT_LIMITS.perCall.usdg, autonomo: amount("max-autonomo") ?? DEFAULT_LIMITS.perCall.autonomo },
+            daily: { usdg: amount("daily") ?? DEFAULT_LIMITS.daily.usdg, autonomo: amount("daily-autonomo") ?? DEFAULT_LIMITS.daily.autonomo },
+        };
+        const payWith = values["pay-with"] ?? "auto";
+        if (payWith !== "usdg" && payWith !== "autonomo" && payWith !== "auto")
+            usage("--pay-with takes usdg, autonomo or auto.");
+        const borro = values.borro ?? io.env.AUTONOMO_BORRO_ACCOUNT;
+        if (borro !== undefined && !ADDRESS.test(borro))
+            usage("--borro takes the credit line's address.");
+        const retryHeader = values["retry-header"];
+        if (values.private && (values["pay-with"] !== undefined || values.borro !== undefined)) {
+            usage("--private pays in USDG from your Gloam balance, so it can't be combined with --pay-with or --borro.");
+        }
+        if (retryHeader !== undefined && !values.private)
+            usage("--retry-header goes with --private: it finishes a call Gloam already paid for.");
+        if (retryHeader !== undefined && !retryHeader.trim())
+            usage("--retry-header takes the paymentHeader from the earlier result.");
+        const store = io.spendStore ?? fileStore();
+        const client = (withWallet) => new Autonomo({
+            privateKey: withWallet ? io.env.AUTONOMO_WALLET_KEY || undefined : undefined,
+            payWith: payWith,
+            limits,
+            borro: borro ? { account: borro } : undefined,
+            spendStore: store,
+            fetch: io.fetch,
+        });
+        const print = (value) => io.out(typeof value === "string" ? value : JSON.stringify(value, null, 2));
+        if (command === "find") {
+            const [words = "", input] = rest;
+            let apis;
+            if (input !== undefined) {
+                apis = await client(false).find(words, input);
+            }
+            else {
+                // Browsing: with no input to fit, show every API whose text matches, including the ones that need an input.
+                const terms = words.toLowerCase().split(/[^a-z0-9$]+/).filter((w) => w.length > 2);
+                const hits = (a) => terms.filter((w) => `${a.slug} ${a.name} ${a.description}`.toLowerCase().includes(w)).length;
+                apis = (await client(false).find()).filter((a) => terms.length === 0 || hits(a) > 0).sort((x, y) => hits(y) - hits(x));
+            }
+            if (json)
+                return print(apis), EXIT.ok;
+            if (apis.length === 0)
+                return io.err(`No API matches "${words}". Run autonomo find to see them all.`), EXIT.notFound;
+            for (const a of apis)
+                io.out(`${a.slug}  ${price(a)}${a.verified ? "  verified" : ""}\n  ${a.name}: ${a.description}\n  ${a.path}`);
+            return EXIT.ok;
+        }
+        if (command === "spend") {
+            const day = new Date().toISOString().slice(0, 10);
+            const spent = await store.get(day);
+            const row = (t) => ({ spent: formatUnits(spent[t] ?? 0n, TOKENS[t].decimals), daily: limits.daily[t], perCall: limits.perCall[t] });
+            const report = { day, wallet: client(true).address, usdg: row("usdg"), autonomo: row("autonomo") };
+            if (json)
+                return print(report), EXIT.ok;
+            io.out(`Today (${day}, UTC)`);
+            io.out(`  USDG      ${report.usdg.spent} of ${report.usdg.daily} spent, up to ${report.usdg.perCall} a call`);
+            io.out(`  AUTONOMO  ${report.autonomo.spent} of ${report.autonomo.daily} spent, up to ${report.autonomo.perCall} a call`);
+            io.out(`  Wallet    ${report.wallet ?? "none set (AUTONOMO_WALLET_KEY)"}`);
+            return EXIT.ok;
+        }
+        // Everything else is a call: a shortcut, or `call` / `quote` with words.
+        let words = "";
+        let opts;
+        const quoteOnly = command === "quote" || Boolean(values["dry-run"]);
+        if (command === "call" || command === "quote") {
+            if (values.slug) {
+                opts = { slug: values.slug, path: values.path, input: rest[0] };
+            }
+            else {
+                if (values.path)
+                    usage("--path needs --slug, the API it belongs to.");
+                if (!rest[0])
+                    usage(`${command} takes what you need in words: autonomo ${command} "is this token safe" 0x…`);
+                if (rest.length > 2)
+                    usage(`Put the words in quotes: autonomo ${command} "is this token safe" 0x…`);
+                words = rest[0];
+                opts = { input: rest[1] };
+            }
+        }
+        else if (Object.hasOwn(SHORTCUTS, command)) {
+            if (values.slug || values.path)
+                usage(`${command} already names its API. Use call with --slug and --path instead.`);
+            opts = SHORTCUTS[command](rest);
+        }
+        else {
+            return usage(`Unknown command "${command}". Run autonomo --help.`);
+        }
+        if (quoteOnly) {
+            const q = await client(false).quote(words, opts);
+            if (json)
+                return print(q), EXIT.ok;
+            io.out(`${q.api.name} (${q.api.slug})\n  ${q.url}`);
+            for (const o of q.offers)
+                io.out(`  ${o.amount} ${o.token}${o.private ? "  private, through Gloam" : ""}`);
+            return EXIT.ok;
+        }
+        if (values.private) {
+            // Gloam's server is only started once a payment is really going to be made, and always stopped afterwards.
+            let session;
+            const gloam = async (notice) => {
+                if (session)
+                    return session;
+                if (!json)
+                    io.err(notice);
+                try {
+                    return (session = await (io.startGloam ?? (() => startGloam(io.env, undefined, VERSION)))());
+                }
+                catch (e) {
+                    throw new AutonomoError(`${e instanceof Error ? e.message : String(e)} ${GLOAM_SETUP}`, "no_gloam");
+                }
+            };
+            try {
+                const autonomo = new Autonomo({
+                    limits,
+                    spendStore: store,
+                    fetch: io.fetch,
+                    gloam: { fetchPaid: async (args) => (await gloam("Paying privately through Gloam. This can take a few minutes…")).fetchPaid(args) },
+                });
+                if (retryHeader !== undefined) {
+                    const q = await autonomo.quote(words, opts);
+                    const r = await (await gloam("Asking Gloam to present the earlier payment…")).fetchPaid({ url: q.url, paymentHeader: retryHeader.trim(), prefer: "gloam-cashout" });
+                    if (r.status !== "ok") {
+                        throw new AutonomoError(`Not answered yet: ${r.message ?? r.error ?? r.code ?? r.status}. Nothing more was paid; try again with the same --retry-header.`, "paid_not_served");
+                    }
+                    let data = r.body ?? "";
+                    try {
+                        data = JSON.parse(String(data));
+                    }
+                    catch {
+                        // Plain text is fine.
+                    }
+                    if (json)
+                        return print({ data, receipt: null }), EXIT.ok;
+                    print(data);
+                    io.err(`Answered by ${q.api.name} with the earlier payment. Nothing more was paid.`);
+                    return EXIT.ok;
+                }
+                if (io.interactive && !values.yes) {
+                    const q = await autonomo.quote(words, opts);
+                    const offer = q.offers.find((o) => o.private);
+                    if (!offer)
+                        throw new AutonomoError(`${q.api.name} doesn't offer private payment.`, "no_private_option");
+                    const question = `${q.api.name} costs ${offer.amount} ${offer.token} privately through Gloam, its fee included. Pay from your Gloam balance? [y/N] `;
+                    if (!(await io.confirm(question)))
+                        return io.err("Not paid."), EXIT.ok;
+                }
+                const { data, receipt } = await autonomo.call(words, { ...opts, private: true });
+                if (json)
+                    return print({ data, receipt }), EXIT.ok;
+                print(data);
+                io.err(`Paid ${receipt.amount} ${receipt.token} privately through Gloam to ${receipt.api.name}. Today: ${receipt.spentToday}.`);
+                if (receipt.explorer)
+                    io.err(receipt.explorer);
+                return EXIT.ok;
+            }
+            finally {
+                await session?.close().catch(() => { });
+            }
+        }
+        const autonomo = client(true);
+        if (!autonomo.address) {
+            throw new AutonomoError("No wallet set. Put the agent wallet's private key in AUTONOMO_WALLET_KEY, or add --dry-run to see the price.", "no_wallet");
+        }
+        if (io.interactive && !values.yes) {
+            const q = await autonomo.quote(words, opts);
+            const prices = q.offers.filter((o) => !o.private).map((o) => `${o.amount} ${o.token}`).join(" or ");
+            if (!(await io.confirm(`${q.api.name} costs ${prices}. Pay from ${autonomo.address}? [y/N] `)))
+                return io.err("Not paid."), EXIT.ok;
+        }
+        const { data, receipt } = await autonomo.call(words, opts);
+        if (json)
+            return print({ data, receipt }), EXIT.ok;
+        print(data);
+        io.err(`Paid ${receipt.amount} ${receipt.token} to ${receipt.api.name}${receipt.route === "borro" ? " on Borro credit" : ""}. Today: ${receipt.spentToday}.`);
+        if (receipt.explorer)
+            io.err(receipt.explorer);
+        return EXIT.ok;
+    }
+    catch (e) {
+        const code = e instanceof AutonomoError ? e.code : e instanceof UsageError || e?.code?.startsWith?.("ERR_PARSE_ARGS") ? "usage" : "failed";
+        const message = e instanceof Error ? e.message : String(e);
+        io.err(json ? JSON.stringify({ error: { code, message } }) : code === "usage" ? `${message}\nRun autonomo --help for the commands.` : message);
+        return code === "usage" ? EXIT.usage : exitFor(e);
+    }
+}
+const isMain = (() => {
+    try {
+        return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain) {
+    const code = await run(process.argv.slice(2), {
+        env: process.env,
+        out: (text) => console.log(text),
+        err: (text) => console.error(text),
+        interactive: Boolean(process.stdin.isTTY && process.stderr.isTTY),
+        confirm: async (question) => {
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            try {
+                return /^y(es)?$/i.test((await rl.question(question)).trim());
+            }
+            finally {
+                rl.close();
+            }
+        },
+    });
+    process.exitCode = code;
+}

package/dist/gloam.d.ts

@@ -0,0 +1,23 @@
+import type { GloamFetchPaid, GloamResult } from "./index.js";
+/** A running Gloam server. */
+export type GloamSession = {
+    /** Pays for one request from the private balance, or presents a payment made earlier (`paymentHeader`). */
+    fetchPaid: (args: Parameters<GloamFetchPaid>[0] | {
+        url: string;
+        paymentHeader: string;
+        prefer: "gloam-cashout";
+    }) => Promise<GloamResult>;
+    close: () => Promise<void>;
+};
+export type GloamServer = {
+    command: string;
+    args: string[];
+};
+/** `npx -y @gloamtrade/mcp`. On Windows npx is a script, so it's started through cmd. */
+export declare const defaultGloamServer: () => GloamServer;
+/** What Gloam's server is started with: everything it may need, but never Autonomo's own wallet key or settings. */
+export declare function gloamEnv(env: Record<string, string | undefined>): Record<string, string>;
+export declare function startGloam(env: Record<string, string | undefined>, server?: GloamServer, version?: string, timeouts?: {
+    start: number;
+    pay: number;
+}): Promise<GloamSession>;

package/dist/gloam.js

@@ -0,0 +1,118 @@
+// Gloam for the CLI's --private: starts Gloam's own MCP server on this machine and calls its paid-fetch tool.
+//
+// The Gloam key never comes near Autonomo's code. Gloam's server reads it, with its own spending limits, from
+// ~/.gloam/agent.env (see autonomo.fun/docs/sdk#pay-privately-with-gloam). This file only speaks the MCP stdio
+// protocol to that server: one JSON-RPC message per line. It is written out here instead of using an MCP client
+// library so `npx autonomo-sdk` stays a small download.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+/** `npx -y @gloamtrade/mcp`. On Windows npx is a script, so it's started through cmd. */
+export const defaultGloamServer = () => process.platform === "win32" ? { command: "cmd", args: ["/c", "npx", "-y", "@gloamtrade/mcp"] } : { command: "npx", args: ["-y", "@gloamtrade/mcp"] };
+// The first run downloads Gloam's server, and a private payment builds its proofs on this machine.
+const START_MS = 120_000;
+const PAY_MS = 300_000;
+/** What Gloam's server is started with: everything it may need, but never Autonomo's own wallet key or settings. */
+export function gloamEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter((e) => e[1] !== undefined && !/^AUTONOMO_/i.test(e[0])));
+}
+export async function startGloam(env, server = defaultGloamServer(), version = "0", timeouts = { start: START_MS, pay: PAY_MS }) {
+    let child;
+    try {
+        child = spawn(server.command, server.args, { env: gloamEnv(env), stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    }
+    catch (e) {
+        throw new Error(`Gloam's server couldn't be started: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // The tail of what the server printed, for when it stops before answering.
+    let tail = "";
+    child.stderr?.on("data", (chunk) => {
+        tail = (tail + chunk.toString("utf8")).slice(-400);
+    });
+    let nextId = 1;
+    let stopped = null;
+    const waiting = new Map();
+    const stop = (why) => {
+        stopped ??= why;
+        for (const w of waiting.values())
+            w.reject(new Error(stopped));
+        waiting.clear();
+    };
+    child.on("error", (e) => stop(`Gloam's server couldn't be started: ${e.message}`));
+    child.on("exit", (code) => stop(`Gloam's server stopped${code === null ? "" : ` (exit ${code})`}${tail.trim() ? `: ${tail.trim().split(/\r?\n/).at(-1)}` : "."}`));
+    // A write to a server that has gone must not crash the CLI: the exit handler reports it.
+    child.stdin?.on("error", () => { });
+    const send = (message) => child.stdin?.write(`${JSON.stringify(message)}\n`);
+    createInterface({ input: child.stdout }).on("line", (line) => {
+        let m;
+        try {
+            m = JSON.parse(line);
+        }
+        catch {
+            return; // Not protocol: a stray log line.
+        }
+        if (m.method !== undefined) {
+            // A request from the server: answer pings, decline anything else. Notifications need no answer.
+            if (m.id !== undefined)
+                send(m.method === "ping" ? { jsonrpc: "2.0", id: m.id, result: {} } : { jsonrpc: "2.0", id: m.id, error: { code: -32601, message: "Not supported" } });
+            return;
+        }
+        const w = m.id !== undefined ? waiting.get(m.id) : undefined;
+        if (!w)
+            return;
+        waiting.delete(m.id);
+        if (m.error)
+            w.reject(new Error(`Gloam: ${m.error.message ?? "request failed"}`));
+        else
+            w.resolve(m.result);
+    });
+    const request = (method, params, ms, what) => new Promise((resolve, reject) => {
+        if (stopped)
+            return reject(new Error(stopped));
+        const id = nextId++;
+        const timer = setTimeout(() => {
+            waiting.delete(id);
+            reject(new Error(`${what} took over ${Math.round(ms / 1000)} seconds.`));
+        }, ms);
+        waiting.set(id, {
+            resolve: (v) => (clearTimeout(timer), resolve(v)),
+            reject: (e) => (clearTimeout(timer), reject(e)),
+        });
+        send({ jsonrpc: "2.0", id, method, params });
+    });
+    const close = async () => {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        const gone = new Promise((resolve) => child.once("exit", () => resolve()));
+        child.stdin?.end(); // An MCP server exits when its input closes.
+        const waited = await Promise.race([gone.then(() => true), new Promise((r) => setTimeout(() => r(false), 3000).unref())]);
+        if (waited)
+            return;
+        // Still there: stop it, and on Windows everything cmd started with it.
+        if (process.platform === "win32" && child.pid)
+            spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => { });
+        else
+            child.kill();
+    };
+    try {
+        await request("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "autonomo-cli", version } }, timeouts.start, "Starting Gloam's server");
+        send({ jsonrpc: "2.0", method: "notifications/initialized" });
+    }
+    catch (e) {
+        await close();
+        throw e;
+    }
+    return {
+        close,
+        fetchPaid: async (args) => {
+            const out = await request("tools/call", { name: "gloam_fetch_paid", arguments: args }, timeouts.pay, "The private payment");
+            const text = out.content?.find((c) => typeof c.text === "string")?.text ?? "";
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                // Gloam answers errors, such as a missing key or an empty balance, in plain words.
+                return { status: "error", message: text.slice(0, 500) || "Gloam gave no answer." };
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { type Hex } from "viem";
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";
 export type TokenName = "usdg" | "autonomo";
 type Token = {
     name: TokenName;
@@ -8,6 +8,16 @@ type Token = {
     decimals: number;
 };
 export declare const TOKENS: Record<TokenName, Token>;
+export declare const DEFAULT_LIMITS: {
+    perCall: {
+        usdg: string;
+        autonomo: string;
+    };
+    daily: {
+        usdg: string;
+        autonomo: string;
+    };
+};
 export type Limits = {
     /** Most to pay for one call, in whole tokens, e.g. { usdg: "0.05" }. */
     perCall?: Partial<Record<TokenName, string>>;
@@ -113,6 +123,7 @@ export declare class AutonomoError extends Error {
 }
 /** Ranks APIs for a query and input: word matches first, then a fitting path, then verified and the track record. */
 export declare function rankApis(apis: Api[], query: string, input?: string): Api[];
+export declare function fileStore(file?: string): SpendStore;
 /** Keeps spending in memory only, for tests or short-lived agents. */
 export declare function memoryStore(): SpendStore;
 export declare class Autonomo {

package/dist/index.js

@@ -15,7 +15,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { createPublicClient, createWalletClient, defineChain, erc20Abi, formatUnits, getAddress, http, maxUint256, parseUnits, toHex, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";
 const NETWORK = "eip155:4663";
 const CHAIN_ID = 4663;
 const EXPLORER = "https://robinhoodchain.blockscout.com";
@@ -26,7 +26,7 @@ export const TOKENS = {
     usdg: { name: "usdg", symbol: "USDG", address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", decimals: 6 },
     autonomo: { name: "autonomo", symbol: "AUTONOMO", address: "0xe83c85e1ead16fcfe85401e2b337fb4fb5b5cc96", decimals: 18 },
 };
-const DEFAULT_LIMITS = {
+export const DEFAULT_LIMITS = {
     perCall: { usdg: "0.05", autonomo: "5000" },
     daily: { usdg: "1", autonomo: "10000" },
 };
@@ -103,7 +103,7 @@ export function rankApis(apis, query, input) {
     return scored.sort((x, y) => y.hits - x.hits || y.trust - x.trust).map((s) => s.a);
 }
 // ---------- Spending ----------
-function fileStore(file = join(homedir(), ".autonomo", "spend.json")) {
+export function fileStore(file = join(homedir(), ".autonomo", "spend.json")) {
     const read = () => {
         try {
             return JSON.parse(readFileSync(file, "utf8"));

package/package.json

@@ -1,47 +1,50 @@
-{
-  "name": "autonomo-sdk",
-  "version": "0.1.0",
-  "description": "One call for AI agents: find the right paid API on Autonomo, pay in USDG or $AUTONOMO (privately through Gloam, or on Borro credit), within spending caps, and get a receipt.",
-  "homepage": "https://autonomo.fun",
-  "author": "Autonomo (https://autonomo.fun)",
-  "license": "MIT",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsc -p .",
-    "test": "node --test test/*.test.mjs"
-  },
-  "keywords": [
-    "x402",
-    "autonomo",
-    "ai-agents",
-    "robinhood-chain",
-    "usdg",
-    "payments",
-    "gloam",
-    "borro"
-  ],
-  "dependencies": {
-    "viem": "2.57.12"
-  },
-  "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.1",
-    "@types/node": "26.6.5",
-    "typescript": "7.0.2"
-  }
-}
+{
+  "name": "autonomo-sdk",
+  "version": "0.1.2",
+  "description": "One call for AI agents: find the right paid API on Autonomo, pay in USDG or $AUTONOMO (privately through Gloam, or on Borro credit), within spending caps, and get a receipt.",
+  "homepage": "https://autonomo.fun",
+  "author": "Autonomo (https://autonomo.fun)",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "x402",
+    "autonomo",
+    "ai-agents",
+    "robinhood-chain",
+    "usdg",
+    "payments",
+    "gloam",
+    "borro"
+  ],
+  "dependencies": {
+    "viem": "2.57.12"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2"
+  },
+  "bin": {
+    "autonomo": "dist/cli.js"
+  }
+}