Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tally-77cc1294.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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 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.