Quickstart

Ship your first agent payment in 10 minutes.

By the end of this guide, you’ll have a registered agent that can spend USDC against a user-authorized grant on Base Sepolia.

Prerequisites

• A Tally account (free).
• Node.js 20 or later.
• A test wallet funded with Base Sepolia USDC.

1. Install the SDK

npm

npm install @tally/sdk

2. Get an API key

From the dashboard, navigate to API keys and create a new key. Test-mode keys are prefixed sk_test_.

export TALLY_API_KEY="sk_test_..."

3. Register an agent

Every agent has a stable string ID you choose. That ID is the handle for permissions, payments, and analytics — pick something durable.

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

const tally = new Tally(process.env.TALLY_API_KEY);

await tally.agents.upsert({
  id: "research-bot",
  display_name: "Research Bot",
});

4. Grant a permission

Permissions live on-chain and are signed by the user. For local testing, you can mint a test grant from the dashboard:

1. Open Permissions

   Navigate to Permissions → New grant in the dashboard.

2. Select your agent

   Pick research-bot from the dropdown.

3. Set the allowance

   For example, 50.00 USDC.

4. Sign with your treasury wallet

   The user wallet signs the grant — it’s recorded on-chain.

5. Make a payment

const result = await tally.pay({
  agent_id: "research-bot",
  to: "0x7a3fA1B9c4D2e6F8a0B1c2D3e4F5a6B7c8D9e0b21c",
  amount_usdc: 4.50,
  memo: "arxiv API access",
});

console.log(result.tx_hash);

If the agent has remaining allowance, you’ll get back a transaction hash within a few seconds. Over the limit, you’ll get a structured error:

TallyError: insufficient_allowance
  agent_id:   research-bot
  granted:    50.00 USDC
  spent:      48.20 USDC
  requested:   4.50 USDC
  remaining:   1.80 USDC

You’ve just made your first agent payment. The transaction is on-chain, attributed to research-bot, and visible in your dashboard’s transactions tab.

What’s next?

Webhooks

React to inbound payments and grant changes in real time.

API key rotation

Set up before going to production.

Permissions in depth

Learn how Tally stays non-custodial.

Payments reference

All the SDK surface for outbound + inbound.