Agents — Core API

Lists all agents for an issuer with cursor-based pagination.

Agents are non-human identities within an issuer, used for automated processes, bots, and machine-to-machine communication. Each agent can have wallet or secret verifiers for authentication.

Filtering:

• status - Filter by agent status (active, suspended, blocked)
• model - Filter by model name (exact match)
• provider - Filter by provider name (exact match)
• has_verifiers - Filter by whether the agent has any verifiers configured
• limit - Number of results per page (1-100, default 50)
• cursor - Cursor from previous response for next page

Each agent in the response includes a verifiers array listing which verifier types are configured (e.g. ["wallet", "secret"]).

Creates a new agent identity under an issuer.

Agents are non-human identities used for automated processes, bots, and machine-to-machine communication. After creation, add verifiers (wallet or secret) to enable authentication.

Agent fields:

• name (required) - Human-readable name for the agent
• description - What the agent does
• model - AI model identifier (e.g., "gpt-4", "claude-3")
• provider - Model provider (e.g., "openai", "anthropic")
• version - Agent version string
• metadata - Arbitrary key-value metadata

Retrieves a single agent by ID.

Returns the agent's profile, status, and metadata. Use the agent verifiers endpoints to manage authentication credentials.

Updates an existing agent's profile or status.

All fields are optional — only provided fields are updated. You can update the agent's name, description, model info, metadata, or status.

Status transitions:

• active → suspended (requires status_reason)
• active → blocked (requires status_reason)
• suspended → active

Suspended or blocked agents cannot authenticate or have verifiers modified.

Permanently deletes an agent and all its verifiers.

This action is irreversible. All associated data is removed:

• Agent profile and metadata
• All verifiers (wallet and secret)
• KV cache entries (agent and wallet reverse lookups)
• D1 listing index entry

Before deleting:

1. Remove the agent from any organizations it belongs to
2. Revoke any active credentials or integrations using this agent

Lists all verifiers attached to an agent.

Returns wallet and secret verifiers. For secret verifiers, only the algorithm is shown — the hash is never exposed.

Adds an authentication verifier to an agent.

Verifier types:

• wallet - Links a blockchain wallet address (CAIP-2 format) for x402 payment authentication. Requires address and network fields. A KV reverse lookup is created for wallet-to-agent resolution.

• secret - Generates a high-entropy client secret for Client Credentials authentication. The plaintext secret is returned once in the response — store it securely. The secret is SHA-256 hashed before storage and cannot be retrieved again.

Limits: Maximum 20 verifiers per agent.

Removes an authentication verifier from an agent.

For wallet verifiers, the KV reverse lookup entry is also cleaned up. For secret verifiers, the stored hash is deleted.

This action is immediate and irreversible.