Get started
Agent API

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
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 and the CLI. 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.
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.

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, GET /policy, GET /setup-state, GET /onchain-networks, POST /feedback, POST /unlink
Accounts GET /accounts, GET /accounts/{id}/balance, GET /accounts/{id}/transactions, GET /accounts/{id}/deposit-address
Counterparties GET /counterparties
Intents POST /intents, GET /intents, GET /intents/{id}, POST /intents/{intentId}/cancel, POST /intents/{intentId}/settlement-report

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.

Updated October 29, 2026 View as Markdown