Skip to main content
The agents endpoints let you register, list, and retrieve the identities Tally attaches to payments and analytics. See Agents (concept) for the model and SDK agents for the TypeScript wrapper.

​
The agent object

{
  "id": "research-bot",
  "status": "no_permissions",
  "mode": "test",
  "created_at": "2026-05-18T12:00:00Z",
  "active_signers": 0,
  "pending_signers": 0
}
FieldTypeDescription
idstringStable user-provided identifier. Unique within (account, mode).
status"no_permissions" | "active"active once at least one wallet has authorized this agent.
mode"test" | "live"Derived from the API key; can’t be changed after creation.
created_atISO 8601 stringWhen the agent was first registered.
active_signersnumberNon-revoked, activated signers across all wallets.
pending_signersnumberNon-revoked signers awaiting the wallet owner’s passkey signature.

​
POST /v1/agents

Create an agent if it doesn’t exist; no-op if it does. Idempotent — safe to call on every deploy.

​
Request

curl https://api.tally.example.com/v1/agents \
  -X POST \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "research-bot" }'
Body fieldTypeRequiredDescription
idstringYesStable identifier, 1–64 chars. Must be unique within (account, mode).

​
Response

201 Created: 
{
  "agent": {
    "id": "research-bot",
    "status": "no_permissions",
    "mode": "test",
    "created_at": "2026-05-18T12:00:00Z",
    "active_signers": 0,
    "pending_signers": 0
  }
}
Returns 201 even on idempotent no-op (the agent already existed). The response always reflects the current state — including signer counts if grants already exist.

​
Errors

StatustypeWhen
400validation_failedid is missing, empty, or fails server-side format checks.
401unauthenticatedAPI key is missing, invalid, or out of its rotation grace window.
429rate_limitedDefault bucket: 60 req/min per key exceeded.

​
GET /v1/agents

List every agent in this (account, mode).

​
Request

curl https://api.tally.example.com/v1/agents \
  -H "Authorization: Bearer $TALLY_API_KEY"
No query parameters today. Pagination is on the roadmap; until it lands, accounts with hundreds of agents get the full list in one response.

​
Response

200 OK: 
{
  "agents": [
    { "id": "research-bot", "status": "active", "mode": "test", ... },
    { "id": "summarizer", "status": "no_permissions", "mode": "test", ... }
  ]
}
Ordering is by created_at ascending. Stable across calls.

​
Errors

StatustypeWhen
401unauthenticatedAPI key invalid.
429rate_limitedDefault bucket exceeded.

​
GET /v1/agents/{id}

Retrieve a single agent by its public id.

​
Request

curl https://api.tally.example.com/v1/agents/research-bot \
  -H "Authorization: Bearer $TALLY_API_KEY"
Path paramDescription
idThe agent’s public identifier. URL-encode it (handled automatically by the SDK).

​
Response

200 OK: 
{ "agent": { "id": "research-bot", "status": "active", "mode": "test", ... } }

​
Errors

StatustypeWhen
401unauthenticatedAPI key invalid.
404not_foundNo agent with that id in this (account, mode).
429rate_limitedDefault bucket exceeded.

​
Patterns

​
Register required agents at boot

Because POST /v1/agents is idempotent, the cleanest pattern is to declare the agents your service needs at startup: 
const REQUIRED = ["research-bot", "summarizer", "publisher"];
for (const id of REQUIRED) {
  await fetch(`${baseUrl}/v1/agents`, {
    method: "POST",
    headers: authHeaders,
    body: JSON.stringify({ id }),
  });
}
Adding a new agent later is a one-line change; existing entries are unchanged.

​
Gate spend on status

agent.status === "active" means at least one wallet has authorized this agent. Use it as a gate before submitting payments: 
const { agent } = await get(`/v1/agents/research-bot`);
if (agent.status === "no_permissions") {
  // Surface to user: they need to grant a permission via the dashboard.
  return;
}
// Safe to call POST /v1/payments.
This won’t tell you which wallets the agent can spend from — for that, attempt a payment and branch on the error code, or check the dashboard. SDK methods for listing grants are on the roadmap.

​
Not yet exposed

  • DELETE /v1/agents/{id} — soft-delete an agent.
  • GET /v1/agents with cursor pagination — for accounts with hundreds of agents.
  • GET /v1/agents/{id}/permissions — list active grants for an agent, with policy summary.
Tracked in BUILD_LOG.md.