autonomo-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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.) Private
+Gloam payments aren't in the command yet; use the SDK for those.
+
+## 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,24 @@
+#!/usr/bin/env node
+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;
+};
+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,305 @@
+#!/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
+//
+// 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.
+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 { 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
+  --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.
+
+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+)?$/;
+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")
+        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" },
+                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 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;
+        }
+        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;
+}