Agents

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
}

Field	Type	Description
`id`	string	Stable 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_at`	ISO 8601 string	When the agent was first registered.
`active_signers`	number	Non-revoked, activated signers across all wallets.
`pending_signers`	number	Non-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 field	Type	Required	Description
`id`	string	Yes	Stable 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

Status	`type`	When
400	`validation_failed`	`id` is missing, empty, or fails server-side format checks.
401	`unauthenticated`	API key is missing, invalid, or out of its rotation grace window.
429	`rate_limited`	Default 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

Status	`type`	When
401	`unauthenticated`	API key invalid.
429	`rate_limited`	Default 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 param	Description
`id`	The agent’s public identifier. URL-encode it (handled automatically by the SDK).

Response

200 OK:

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

Errors

Status	`type`	When
401	`unauthenticated`	API key invalid.
404	`not_found`	No agent with that id in this (account, mode).
429	`rate_limited`	Default 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.

Get started

Concepts

Guides

API reference

SDK reference

Ops

Resources

The agent object

`POST /v1/agents`

Request

Response

Errors

`GET /v1/agents`

Request

Response

Errors

`GET /v1/agents/{id}`

Request

Response

Errors

Patterns

Register required agents at boot

Gate spend on `status`

Not yet exposed

​The agent object

​POST /v1/agents

​Request

​Response

​Errors

​GET /v1/agents

​Request

​Response

​Errors

​GET /v1/agents/{id}

​Request

​Response

​Errors

​Patterns

​Register required agents at boot

​Gate spend on status

​Not yet exposed

The agent object

`POST /v1/agents`

Request

Response

Errors

`GET /v1/agents`

Request

Response

Errors

`GET /v1/agents/{id}`

Request

Response

Errors

Patterns

Register required agents at boot

Gate spend on `status`

Not yet exposed