---
title: "Report the agent's onboarding readiness and blocking steps"
method: GET
path: "/setup-state"
tags: ["agent"]
---

# Report the agent's onboarding readiness and blocking steps

`GET /setup-state`

## Request

- Base URL: `https://api.catena.com/v1/agent-api`
- URL: `https://api.catena.com/v1/agent-api/setup-state`
- Auth: HTTP bearer

## Response `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.

- object
  - `agent` object, required
    - `id` string, required
    - `name` string, required
    - `status` 'pending_claim' | 'active' | 'suspended' | 'pending_policy' | 'revoked', required
  - `organization` object, required
    - `id` string, required
    - `environment` 'live' | 'sandbox', required
    - `kybVerified` boolean, required: Organization completed account verification, which is what opens the fiat rails
    - `onboarding` object, required
      - `postSignupRequired` boolean, required
      - `organizationNameRequired` boolean, required
      - `nonCustodialTermsRequired` boolean, required
      - `nonCustodialWalletSecurityRequired` boolean, required
    - `capabilities` object, required
      - `fiat-rails` boolean, required
      - `onchain:base` boolean, required
      - `onchain:base-sepolia` boolean, required
      - `onchain:arc` unknown
      - `onchain:arc-testnet` unknown
      - `onchain:tempo` unknown
      - `kyb` boolean, required
    - `heldAssets` string[], required: Additional assets enabled for this organization. Empty when USDC alone is available
    - `closedNetworks` string[], required: 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
  - `policy` object, required
    - `assigned` boolean, required
    - `capabilities` string[]
  - `accounts` object, required
    - `accessibleCount` number, required
    - `hasFundedAccount` boolean, required: 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.
  - `signer` object, required
    - `registered` boolean, required
  - `ready` boolean, required: 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
  - `steps` object[], required
    - `key` 'claim_agent' | 'organization_onboarding' | 'kyb_verification' | 'assign_policy' | 'fund_account' | 'register_signer', required
    - `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
    - `actor` 'operator' | 'agent', required: Who can complete this step
    - `requiredPermission` string: Operator permission that authorizes completing the step
    - `hint` string, required: Plain-English instruction, surfaceable as-is

## Other responses

- `409`: Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`

---

[API](https://skmtc.dev/catena/apis/catena-agent-api.md) - [All operations](https://skmtc.dev/catena/apis/catena-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/catena/apis/catena-agent-api/revisions/9b72e32d21f1?raw)