Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tallyforagents.com/llms.txt

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

The Tally REST API is the same surface the TypeScript SDK wraps. Use the REST endpoints directly when you’re working in a language the SDK doesn’t cover yet, or when you want full control over HTTP behavior (custom retry middleware, structured logging, etc.).

​
Base URL

https://api.tally.example.com
Set this explicitly in production. The SDK defaults to http://localhost:3000 for local development — that’s helpful for dev, but every deployed environment should set the base URL.

​
Versioning

Every endpoint is prefixed with /v1. The v1 family is stable: we add fields and endpoints, but we don’t remove or repurpose them. Breaking changes will live under /v2 whenever they happen — v1 will keep working in parallel.

​
Request format

  • HTTPS only. Plain HTTP is rejected.
  • JSON only. Set Content-Type: application/json on every request with a body. Tally returns application/json on every response, including errors.
  • Field names are snake_case — agent_id, amount_usdc, idempotency_key. The SDK preserves this casing in TypeScript types.
curl https://api.tally.example.com/v1/agents \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "research-bot"}'

​
Response format

Successful responses return a JSON object with the resource keyed under its name: 
{
  "agent": {
    "id": "research-bot",
    "status": "no_permissions",
    "mode": "test",
    "created_at": "2026-05-18T12:00:00Z",
    "active_signers": 0,
    "pending_signers": 0
  }
}
List endpoints return arrays under a plural key: 
{ "agents": [ { "id": "research-bot", ... }, { "id": "summarizer", ... } ] }
This shape is consistent across the API — your client can lift fields by their resource name without per-endpoint parsing.

​
Error format

Errors use a consistent envelope across every endpoint: 
{
  "error": {
    "type": "validation_failed",
    "message": "Amount exceeds per-tx max.",
    "code": "amount_too_large",
    "details": { "max_per_tx_usdc": "10", "requested": "15" }
  }
}
FieldTypeDescription
typestringCoarse-grained category — unauthenticated, forbidden, not_found, etc. Drives the HTTP status.
messagestringHuman-readable. Safe to log; no PII.
codestring (optional)Specific failure mode within type.
detailsany (optional)Structured context — often the failed Zod issue list.
The HTTP status code follows from type. See Errors for the full table.

​
Authentication

Bearer-token, scoped to one (account, mode). See Authentication for the details.

​
Where to go from here

Resource endpoints:
  • Agents — POST /v1/agents, GET /v1/agents, GET /v1/agents/{id}
  • Payments — POST /v1/payments, GET /v1/payments/{id}