Agent and policy
Get setup state
Report the agent's onboarding readiness and blocking steps.
GET
/v1/agent-api/setup-stateResponses
200Setup 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
agentobjectRequiredagent.idstringRequiredagent.namestringRequiredagent.status"pending_claim" | "active" | "suspended" | "pending_policy" | "revoked"RequiredorganizationobjectRequiredorganization.idstringRequiredorganization.environment"live" | "sandbox"Requiredorganization.kybVerifiedbooleanRequiredOrganization completed account verification, which is what opens the fiat rails
organization.onboardingobjectRequiredorganization.capabilitiesobjectRequiredorganization.heldAssetsarray of stringRequiredAdditional assets enabled for this organization. Empty when USDC alone is available
organization.closedNetworksarray of stringRequiredThe 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
policyobjectRequiredpolicy.assignedbooleanRequiredpolicy.capabilitiesarray of stringOptionalaccountsobjectRequiredaccounts.accessibleCountnumberRequiredaccounts.hasFundedAccountbooleanRequiredAt 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.
signerobjectRequiredsigner.registeredbooleanRequiredreadybooleanRequiredAgent 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 objectRequiredsteps[].key"claim_agent" | "organization_onboarding" | "kyb_verification" | "assign_policy" | "fund_account" | "register_signer"Requiredsteps[].status"complete" | "required" | "not_applicable"RequiredWhether 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"RequiredWho can complete this step
steps[].requiredPermissionstringOptionalOperator permission that authorizes completing the step
steps[].hintstringRequiredPlain-English instruction, surfaceable as-is