Pay for APIs in one call with the SDK

Install

npm install autonomo-sdk

pip install autonomo-sdk

TypeScript needs Node 20 or later, Python 3.10 or later. The Python SDK is also on PyPI as autonomo; either way, you import it from autonomo. Make a new wallet just for your agent and keep only what it may spend in it. Most APIs cost 0.01 USDG, so 1 USDG is about 100 calls. Paying in $AUTONOMO needs a little ETH once, for a Permit2 approval.

Pay from the agent's wallet

The usual way. The SDK pays in USDG if the wallet has enough, and otherwise in $AUTONOMO. Set payWith (pay_with in Python) to "usdg" or "autonomo" to use only one.

// Pay from the agent's own wallet: USDG first, then $AUTONOMO.
import { Autonomo } from "autonomo-sdk";

const autonomo = new Autonomo({
  privateKey: process.env.AUTONOMO_WALLET_KEY,
  limits: { perCall: { usdg: "0.02" }, daily: { usdg: "0.50" } },
});

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);

"""Pay from the agent's own wallet: USDG first, then $AUTONOMO."""
import os

from autonomo import Autonomo

autonomo = Autonomo(
    private_key=os.environ["AUTONOMO_WALLET_KEY"],
    per_call={"usdg": "0.02"},
    daily={"usdg": "0.50"},
)

result = autonomo.call("is this token safe", input="0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49")
print(result.data)
print(result.receipt.route, result.receipt.amount, result.receipt.token, result.receipt.explorer)

Pay privately with Gloam

With private: true (private=True), the call is paid from a private Gloam balance, so it doesn't link back to your wallet. The SDK hands the payment to Gloam's own MCP server, @gloamtrade/mcp, running on your machine: Gloam cashes out exactly the price through its relay and calls the API with it. The SDK never sees your Gloam key, and your agent's own wallet key isn't needed.

GLOAM_NETWORK=robinhood-mainnet
GLOAM_AGENT_PRIVATE_KEY=0x…
GLOAM_LIMIT_NETWORK=robinhood-mainnet
GLOAM_LIMIT_ASSETS=USDG
GLOAM_LIMIT_MAX_PER_PAYMENT=0.05
GLOAM_LIMIT_MAX_PER_DAY=1
GLOAM_LIMIT_RECIPIENTS=any

// Pay privately from a Gloam balance, through Gloam's own MCP server running on this machine.
// It reads its key and limits from ~/.gloam/agent.env (GLOAM_NETWORK=robinhood-mainnet).
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { Autonomo } from "autonomo-sdk";

const gloam = new Client({ name: "my-agent", version: "1.0.0" });
await gloam.connect(new StdioClientTransport({ command: "npx", args: ["-y", "@gloamtrade/mcp"] }));

const autonomo = new Autonomo({
  gloam: {
    fetchPaid: async (args) => {
      const out = await gloam.callTool({ name: "gloam_fetch_paid", arguments: args });
      return JSON.parse((out.content as Array<{ text: string }>)[0].text);
    },
  },
});

const { data, receipt } = await autonomo.call("newest launches", { private: true });
console.log(data);
console.log(receipt.route, receipt.amount, receipt.explorer); // "gloam", the price plus Gloam's fee, the cash-out
await gloam.close();

"""Pay privately from a Gloam balance, through Gloam's own MCP server running on this machine.
It reads its key and limits from ~/.gloam/agent.env (GLOAM_NETWORK=robinhood-mainnet). Needs `pip install mcp`."""
import asyncio
import json

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from autonomo import Autonomo


async def main():
    server = StdioServerParameters(command="npx", args=["-y", "@gloamtrade/mcp"])
    async with stdio_client(server) as (read, write), ClientSession(read, write) as gloam:
        await gloam.initialize()
        loop = asyncio.get_running_loop()

        def fetch_paid(args):
            out = asyncio.run_coroutine_threadsafe(gloam.call_tool("gloam_fetch_paid", args), loop).result()
            return json.loads(out.content[0].text)

        autonomo = Autonomo(gloam_fetch_paid=fetch_paid)
        result = await asyncio.to_thread(autonomo.call, "newest launches", private=True)
        print(result.data)
        print(result.receipt.route, result.receipt.amount, result.receipt.explorer)


asyncio.run(main())

• A private call is only ever paid through Gloam. If the API doesn't offer it, the call is refused, never paid publicly.
• The price includes Gloam's 0.5% cash-out fee, so 0.01 USDG becomes about 0.0101.
• What stays public: the amount, the API's payment address and the time. What stays private: which wallet paid.
• On Windows, start the server with command: "cmd" and args: ["/c", "npx", "-y", "@gloamtrade/mcp"].

Borrow with a Borro credit line

Set a Borro credit line, and when the wallet can't afford a call, the SDK borrows just what it's short and pays in the same call. It asks Borro's MCP server for the borrow, sends it from the wallet, waits for the USDG to arrive, then pays as usual.

// Borrow what the wallet is short from a Borro credit line, then pay.
import { Autonomo } from "autonomo-sdk";

const autonomo = new Autonomo({
  privateKey: process.env.AUTONOMO_WALLET_KEY,
  payWith: "usdg",
  borro: { account: process.env.BORRO_CREDIT_LINE! },
});

const { data, receipt } = await autonomo.call("explain this transaction", {
  input: "0x0f1635d41a8fbbde7d61ad39e045e067780b921329112c16955bc26ad3423041",
});
console.log(data);
console.log(receipt.route, receipt.borrowTxs, receipt.explorer); // "borro" when it borrowed, "usdg" when it didn't need to

"""Borrow what the wallet is short from a Borro credit line, then pay."""
import os

from autonomo import Autonomo

autonomo = Autonomo(
    private_key=os.environ["AUTONOMO_WALLET_KEY"],
    pay_with="usdg",
    borro_account=os.environ["BORRO_CREDIT_LINE"],
)

result = autonomo.call("explain this transaction", input="0x0f1635d41a8fbbde7d61ad39e045e067780b921329112c16955bc26ad3423041")
print(result.data)
print(result.receipt.route, result.receipt.borrow_txs, result.receipt.explorer)

• Open the line at borro.markets/app with Let the agent pay its x402 bills ticked, for this agent's wallet. Borro's daily limit applies on top of the SDK's.
• The wallet needs a little ETH for the borrow transaction's gas.
• The receipt's route is borro when it borrowed, with the borrow transaction, or usdg when the wallet already had enough.
• Repaying the line is between you and Borro.

Limits

Every route checks both before anything is signed or sent. Set your own when you create the client:

Today's spending is kept in ~/.autonomo/spend.json, shared by the TypeScript and Python SDKs. For a server with many agents, pass your own spendStore (spend_store).

The receipt

Python uses snake_case for the same fields: pay_to, borrow_txs, approve_tx, spent_today.

Look before paying

find lists the APIs that match a request, and quote shows the API a call would use and every price, including the private one. Both are free and need no wallet. To skip the search, name the API with slug and path.

When a call isn't paid

Errors are an AutonomoError with a code and a plain reason, for example "the wallet holds 0 USDG, the call costs 0.01".