# Get setup state

> Report the agent's onboarding readiness and blocking steps.

`GET /v1/agent-api/setup-state`

## Responses

| Status | Description                                                                                                                                                                                                                                        |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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

| Field                         | Type                                                                                                                                   | Required | Description                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent`                       | object                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `agent.id`                    | string                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `agent.name`                  | string                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `agent.status`                | `"pending_claim"` \| `"active"` \| `"suspended"` \| `"pending_policy"` \| `"revoked"`                                                  | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `organization`                | object                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `organization.id`             | string                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `organization.environment`    | `"live"` \| `"sandbox"`                                                                                                                | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `organization.kybVerified`    | boolean                                                                                                                                | Yes      | Organization completed account verification, which is what opens the fiat rails                                                                                                                                                                                                                                                                  |
| `organization.onboarding`     | object                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `organization.capabilities`   | object                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `organization.heldAssets`     | array of string                                                                                                                        | Yes      | Additional assets enabled for this organization. Empty when USDC alone is available                                                                                                                                                                                                                                                              |
| `organization.closedNetworks` | array of string                                                                                                                        | Yes      | 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                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `policy.assigned`             | boolean                                                                                                                                | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `policy.capabilities`         | array of string                                                                                                                        |          |                                                                                                                                                                                                                                                                                                                                                  |
| `accounts`                    | object                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `accounts.accessibleCount`    | number                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `accounts.hasFundedAccount`   | boolean                                                                                                                                | Yes      | 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                                                                                                                                 | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `signer.registered`           | boolean                                                                                                                                | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `ready`                       | boolean                                                                                                                                | Yes      | 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`                       | array of object                                                                                                                        | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `steps[].key`                 | `"claim_agent"` \| `"organization_onboarding"` \| `"kyb_verification"` \| `"assign_policy"` \| `"fund_account"` \| `"register_signer"` | Yes      |                                                                                                                                                                                                                                                                                                                                                  |
| `steps[].status`              | `"complete"` \| `"required"` \| `"not_applicable"`                                                                                     | Yes      | 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"`                                                                                                              | Yes      | Who can complete this step                                                                                                                                                                                                                                                                                                                       |
| `steps[].requiredPermission`  | string                                                                                                                                 |          | Operator permission that authorizes completing the step                                                                                                                                                                                                                                                                                          |
| `steps[].hint`                | string                                                                                                                                 | Yes      | Plain-English instruction, surfaceable as-is                                                                                                                                                                                                                                                                                                     |

## Example

### SDK

```ts
import { createCatenaClient } from "@catena/sdk"

// Reads CATENA_SECRET_KEY
const client = createCatenaClient()

const setup = await client.getSetupState()
```

### CLI

```sh
catena setup-state
```

### Response `200`

```json
{
  "agent": {
    "id": "agent_01JC2Y4H8M3T9V6Q2X7R5N1KPB",
    "name": "Invoice agent",
    "status": "active"
  },
  "organization": {
    "id": "org_01JC2X9V7T5R3P1N8L6J4G2E0C",
    "environment": "live",
    "kybVerified": true,
    "onboarding": {
      "postSignupRequired": false,
      "organizationNameRequired": false,
      "nonCustodialTermsRequired": false,
      "nonCustodialWalletSecurityRequired": false
    },
    "capabilities": {
      "fiat-rails": true,
      "onchain:base": true,
      "onchain:base-sepolia": false,
      "onchain:arc": true,
      "kyb": true
    },
    "heldAssets": [],
    "closedNetworks": []
  },
  "policy": {
    "assigned": true,
    "capabilities": ["read", "send"]
  },
  "accounts": {
    "accessibleCount": 1,
    "hasFundedAccount": true
  },
  "signer": {
    "registered": true
  },
  "ready": true,
  "steps": [
    {
      "key": "claim_agent",
      "status": "complete",
      "actor": "operator",
      "hint": "This agent is claimed, so a linked client can act as it."
    },
    {
      "key": "organization_onboarding",
      "status": "complete",
      "actor": "operator",
      "hint": "Organization onboarding is complete."
    },
    {
      "key": "kyb_verification",
      "status": "complete",
      "actor": "operator",
      "hint": "Account verification is complete, so the fiat rails are open to this organization."
    },
    {
      "key": "assign_policy",
      "status": "complete",
      "actor": "operator",
      "hint": "A policy is assigned to this agent, so its permitted actions and accounts come from that policy."
    },
    {
      "key": "fund_account",
      "status": "complete",
      "actor": "operator",
      "hint": "At least one account this agent can read has an available balance."
    },
    {
      "key": "register_signer",
      "status": "complete",
      "actor": "agent",
      "hint": "This client has a registered signing key, so it signs its own wallet-account sends."
    }
  ]
}
```