Agent and policy

Get setup state

Report the agent's onboarding readiness and blocking steps.

GET/v1/agent-api/setup-state

Responses

200
Setup state: agent status, organization gates, policy assignment, account access and funding, signer registration, and the ordered setup steps with the capability each one still gates. A missing policy is reported as state, never as an error.

Response fields

agentobjectRequired
agent.idstringRequired
agent.namestringRequired
agent.status"pending_claim" | "active" | "suspended" | "pending_policy" | "revoked"Required
organizationobjectRequired
organization.idstringRequired
organization.environment"live" | "sandbox"Required
organization.kybVerifiedbooleanRequired
Organization completed account verification, which is what opens the fiat rails
organization.onboardingobjectRequired
organization.capabilitiesobjectRequired
organization.heldAssetsarray of stringRequired
Additional assets enabled for this organization. Empty when USDC alone is available
organization.closedNetworksarray of stringRequired
The networks Catena has made temporarily unavailable among those this agent may use and the chains its custodial accounts hold their money on. They refuse new payments with onchain_network_closed, and money on them does not count toward accounts.hasFundedAccount. Money already on them is safe, and payments already in progress complete
policyobjectRequired
policy.assignedbooleanRequired
policy.capabilitiesarray of stringOptional
accountsobjectRequired
accounts.accessibleCountnumberRequired
accounts.hasFundedAccountbooleanRequired
At least one readable account has positive available USD at par across assets this organization holds, on networks the agent may use. Closed networks, inactive accounts and retired wallets do not count.
signerobjectRequired
signer.registeredbooleanRequired
readybooleanRequired
Agent is active with a policy and at least one accessible account, so it can act at all. Steps can still be required alongside it; each gates only the capability it names
stepsarray of objectRequired
steps[].key"claim_agent" | "organization_onboarding" | "kyb_verification" | "assign_policy" | "fund_account" | "register_signer"Required
steps[].status"complete" | "required" | "not_applicable"Required
Whether this step is done, still outstanding, or not needed here. A required step gates the capability it names, which is often narrower than everything the agent can do
steps[].actor"operator" | "agent"Required
Who can complete this step
steps[].requiredPermissionstringOptional
Operator permission that authorizes completing the step
steps[].hintstringRequired
Plain-English instruction, surfaceable as-is
Updated October 29, 2026 Generated from the agent API's published OpenAPI document View as Markdown