# Agent API

The agent API is the HTTP API that the Catena CLI and SDK call, and the MCP
connector exposes the same capabilities to your agents as tools. Every request
acts as a single agent, and Catena will check it against that agent's policy.

|          |                                                                                                                       |
| -------- | --------------------------------------------------------------------------------------------------------------------- |
| Base URL | `https://api.catena.com/v1/agent-api`                                                                                 |
| Contract | OpenAPI 3.1 at [`https://api.catena.com/v1/agent-api/openapi.json`](https://api.catena.com/v1/agent-api/openapi.json) |
| Format   | JSON requests and responses                                                                                           |

We generate the contract from the API's own request and response validators, and
we check every change for backward compatibility against the published copy. The
reference pages in this section come from the same document.

The supported clients are the TypeScript [SDK](https://docs.catena.com/sdk.md) and the [CLI](https://docs.catena.com/cli.md). If you
are writing TypeScript, we recommend the SDK: it signs requests, handles
retries, and checks each payment before it signs it.

## Authentication

Each agent credential is a P-256 key (either the secret key from the console or
the key that `catena link` stores on a machine). Clients sign every request with
that key using HTTP Message Signatures (RFC 9421), so the key stays on the
client.

The signing rules are as follows:

- Each signature covers the method, the full URL, a digest of the body, and the
  signer's identity.
- Each request carries two signatures made with the same key, timestamp, and
  nonce. The standard profile uses `Signature-Input`, `Signature`,
  `Signature-Agent`, and `Content-Digest`, and the dedicated profile uses the
  same four headers with a `Catena-` prefix.
- If a proxy replaces the standard headers, it must leave the four `Catena-*`
  headers, the URL, and the body unchanged.
- A request with an invalid or partial dedicated signature will fail, even when
  its standard signature is valid.
- Catena checks the agent's link on every signed request, so revoking a key or
  unlinking a machine will take effect on the next request.

> [!NOTE] **Session tokens**
>
> The OpenAPI document also describes session tokens (`agentBearer`), which the
> linking flow uses. New integrations should sign requests instead.

## Conventions

Below are the conventions that apply across the agent API.

| Topic       | Convention                                                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| IDs         | Every ID starts with its type: `agent_`, `acct_` (account), `cp_` (counterparty), `cpr_` (counterparty rail), and `int_` (intent).                                       |
| Money       | Either a decimal string in USD, such as `"125.00"`, or a money object `{ "amount": "125.00", "assetId": "USD" }`. Responses still include the deprecated `asset_id` key. |
| Idempotency | `POST /intents` accepts an `Idempotency-Key` header. Only reuse a key to retry the same submission. See [Intents and retries](https://docs.catena.com/intents.md#retry-safely).                    |
| Networks    | The OpenAPI document lists the live networks, `base` and `arc`. Sandbox organizations use `base-sepolia` and `arc-testnet` instead.                                      |
| Pagination  | List endpoints take `limit` (default 50, maximum 200) and `offset`.                                                                                                      |
| Rate limits | Catena limits bank payments per organization, by default to 60 a minute. If you go over the limit, the API will return 429 with a `Retry-After` header.                  |
| Errors      | See [Error format](https://docs.catena.com/troubleshooting.md#error-format).                                                                                                                       |

## Endpoints

Each operation has its own page with an SDK call, a CLI command, and an example
response.

| Area             | Operations                                                                                                                                                                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent and policy | [`GET /me`](https://docs.catena.com/api/get-agent.md), [`GET /policy`](https://docs.catena.com/api/get-policy.md), [`GET /setup-state`](https://docs.catena.com/api/get-setup-state.md), [`GET /onchain-networks`](https://docs.catena.com/api/list-networks.md), [`POST /feedback`](https://docs.catena.com/api/send-feedback.md), [`POST /unlink`](https://docs.catena.com/api/unlink-agent.md)               |
| Accounts         | [`GET /accounts`](https://docs.catena.com/api/list-accounts.md), [`GET /accounts/{id}/balance`](https://docs.catena.com/api/get-balance.md), [`GET /accounts/{id}/transactions`](https://docs.catena.com/api/list-transactions.md), [`GET /accounts/{id}/deposit-address`](https://docs.catena.com/api/get-deposit-address.md)                              |
| Counterparties   | [`GET /counterparties`](https://docs.catena.com/api/list-counterparties.md)                                                                                                                                                                                                   |
| Intents          | [`POST /intents`](https://docs.catena.com/api/create-intent.md), [`GET /intents`](https://docs.catena.com/api/list-intents.md), [`GET /intents/{id}`](https://docs.catena.com/api/get-intent.md), [`POST /intents/{intentId}/cancel`](https://docs.catena.com/api/cancel-intent.md), [`POST /intents/{intentId}/settlement-report`](https://docs.catena.com/api/report-settlement.md) |

### Operations the clients call

While linking, the CLI and the SDK call `POST /claim`, `POST /refresh`, and
`POST /signer/register`, and they call `POST /intents/{intentId}/submit-stamp`
to submit a signed wallet payment. These operations are part of the published
contract but do not have pages here, since you do not call them yourself when
you use the CLI or the SDK.

## Operator API

We also publish the operator API, which the console uses, at
`https://api.catena.com/v1/openapi.json`. Because it requires a person signed in
to the console, these docs do not cover it.

Missing something you'd find helpful? Send us an email at <support@catena.com>.

## Related

- [SDK reference](https://docs.catena.com/sdk.md): Setup, methods, intent actions, errors, and client options for @catena/sdk, the TypeScript client for the agent API.
- [CLI reference](https://docs.catena.com/cli.md): The public commands in @catena/cli 0.19.0, generated from the CLI's help text.
- [Link with secret keys](https://docs.catena.com/connect/secret-keys.md): A secret key lets an agent act in Catena from hosts where catena link cannot store a credential, such as CI jobs, cloud sandboxes, and deployed services.
- [Intents and retries](https://docs.catena.com/intents.md): Learn how an intent moves through its statuses and resolutions, which fields explain its result, and how to retry safely with idempotency keys.