@tallyforagents/sdk

The official TypeScript SDK for Tally — give AI agents USDC wallets and scoped programmable spending on Base.

Tally is non-custodial: you hold your wallet, you set the spending rules, and you grant any external agent scoped permission to send. Tally never custodies funds and never runs the agent.

Public preview on Base Sepolia today. Base mainnet support is on the way — join the waitlist.

Install

npm install @tallyforagents/sdk
# or
pnpm add @tallyforagents/sdk
# or
yarn add @tallyforagents/sdk

Targets Node 18+ and uses the platform's native fetch — zero runtime dependencies.

Quickstart

import { Tally } from "@tallyforagents/sdk";

const tally = new Tally({
  apiKey: process.env.TALLY_API_KEY!, // tly_test_… or tly_live_…
});

// Register (or update) an agent
await tally.agents.upsert({
  id: "research-bot",
});

// Send a payment from one of your wallets
const payment = await tally.payments.create({
  agent: "research-bot",
  wallet: "wlt_…",
  to: "0xRecipient…",
  amount_usdc: "1.50",
});

console.log(payment.tx_hash);

Get an API key from the Tally dashboard → API keys. Test-mode keys (tly_test_…) send on Base Sepolia; live-mode keys (tly_live_…) target Base mainnet once that's enabled on your account.

What's in the box

| Resource | Methods | |---|---| | tally.agents | upsert, list, get | | tally.payments | create, get | | tally.webhooks | verifySignature (HMAC-SHA256, Stripe-style t=…,v1=… header) |

Typed errors map server responses to exception classes:

import {
  TallyError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ConflictError,
} from "@tallyforagents/sdk";

More method wrappers (wallets.*, permissions.*, payments.list, agents.delete, webhooks.list/create/revoke) are on the roadmap — see the changelog.

Full docs

Concepts, guides, and the complete API reference live at https://www.tallyforagents.com/docs:

• Quickstart — first payment in under five minutes
• Build a paying agent — OpenAI function-calling end-to-end example
• Handling failures — error codes, retries, idempotency
• Local webhook dev — ngrok + verifySignature workflow

Configuration

new Tally({
  apiKey: "tly_test_…",
  baseUrl: "https://app.tallyforagents.com", // override for local dev or self-hosting
  fetch: customFetch,                         // optional custom fetch impl
});

Support

• Issues: https://github.com/pkohler95/tally-v2/issues
• Email: [email protected]

License

MIT © Tally