Agent REST API

Endpoints

The OpenAPI document describes every input field: https://api.cleave.fi/agent/v1/openapi.json.

Requests

• Send POST with Content-Type: application/json and the tool's fields in the body.
• The body can be at most 16 KiB.
• Query parameters are refused: every field goes in the body.
• An unknown field is refused, and the answer lists the fields the tool takes.

curl -s https://api.cleave.fi/agent/v1/plan_swap \
  -H 'Content-Type: application/json' \
  -d '{"fromChainId":8453,"sellToken":"USDC","buyToken":"WETH","amount":"25","wallet":"0x00000000000000000000000000000000c1ea7e01"}'

Answers

A successful call answers 200 with the tool's JSON. The fields are listed on the MCP server page.

Read a plan in this order:

1. blocked and notices. A block notice means calls is empty.
2. requiresConfirmation: set by a warn notice or a recipient other than the wallet. Show the plan to the user before signing.
3. route.outcomeKind and receive: what arrives, the minimum, and the fallback or refund.
4. validUntil: sign and send the calls before this unix time, in order.

Then call track_swap with chainId, txHash and the plan's requestId.

Errors

A refusal answers with an HTTP error status and this body:

{
  "apiVersion": "1",
  "requestId": "…",
  "error": {
    "code": "not_found",
    "reason": "not_a_cleave_tx",
    "message": "…",
    "detail": "…",
    "retryable": false
  }
}

• code sets the HTTP status; reason narrows it down when present.
• retryable: true means the same call can succeed later. retryAfterSec, when present, says when.
• suggestion, when present, carries a value to try instead, such as a smaller amount.

The full list of codes is on the API page.

Limits

• Without a key, each caller's address can make 40 requests per 10 seconds and 120 per minute. Requests from a known hosted platform, where many agents share one address, are counted by the request's wallet instead.
• All keyless agents share one planning capacity. A cross-chain plan counts twice. When it is busy, the answer is 429 with reason agent_limit and a short retryAfterSec.
• With a partner key, send Authorization: Bearer cq_live_<your key>. Requests then count against the key's own limit instead.

Differences from MCP

• There are no connection settings: no wallet pin and no USD cap.
• The token to receive must be on Cleave's token list.
• Browsers can call these endpoints; a key must never be used from a browser.

Terms of use

Use of the API, the partner API and the MCP server is subject to the Terms of Use and the Privacy Policy. By sending requests or connecting a client after this notice, you accept them.

If an agent or other software calls Cleave, its operator accepts them and is responsible for what it does. Partner and agent keys are issued only after the key holder accepts them. Stay within the published rate limits.