Cleave for Agents: token swaps, cross-chain swaps and gas top-ups

Plans a token swap on one chain, a cross-chain swap or bridge, or a native-gas top-up on Ethereum, Arbitrum, Base, BNB Chain, Polygon or Optimism, and returns unsigned transactions for the given wallet to sign. It fits when the user wants to exchange tokens, move them between these chains, or get ETH, BNB or POL for gas. It sends nothing and moves no funds. The answer leads with blocking notices and warnings, then gives the route's outcome kind (exact or at least a minimum; with a swap on arrival, the token, else a named fallback; where a transfer can go unfilled, a refund of the bridged token on the source chain hours later), every third-party cost except network gas, the expected time, validUntil and the calls in signing order. A blocking notice returns no calls; a warning, or a recipient other than the wallet, sets requiresConfirmation, and the connection's settings can turn either into a refusal. Calls sent after validUntil are stale: they can revert or, on some routes, end in a refund hours later. Amounts are decimal strings in token units; tokens are listed symbols or contract addresses; the recipient defaults to the wallet. Limits set in the connection (a pinned wallet, a per-plan USD cap, listed tokens only) bound every argument. For an ambiguous symbol, cleave_find_token lists the candidates; after sending, cleave_track_swap reports progress. A wallet with no gas can get it with cleave_get_gas.

{
  "type": "object",
  "properties": {
    "fromChainId": {
      "type": "integer",
      "enum": [
        1,
        10,
        56,
        137,
        8453,
        42161
      ]
    },
    "toChainId": {
      "type": "integer",
      "enum": [
        1,
        10,
        56,
        137,
        8453,
        42161
      ]
    },
    "sellToken": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "A listed symbol or a contract address"
    },
    "buyToken": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "A listed symbol or a contract address"
    },
    "amount": {
      "type": "string",
      "pattern": "^[0-9]+(\\.[0-9]+)?$",
      "description": "A decimal amount in token units"
    },
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "recipient": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "maxSlippageBps": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5000
    }
  },
  "required": [
    "fromChainId",
    "sellToken",
    "buyToken",
    "amount",
    "wallet"
  ],
  "additionalProperties": false
}

Reports the status of a swap, bridge or gas top-up that was planned with cleave_plan_swap and then sent, or ordered with cleave_get_gas: its state (for example pending, in flight, delivered, refund pending or refunded), what arrived against the plan and on which chain, and the next action or when to check again. It takes the chain and transaction hash, plus the plan's requestId when known, or for a gas top-up the requestId alone; a transaction to a contract outside Cleave's published list is reported as such. It fits when the user asks whether such a transfer arrived, and before any re-send, because re-sending a plan that is still in flight can pay twice. It reports states only and returns no transactions.

{
  "type": "object",
  "properties": {
    "chainId": {
      "type": "integer",
      "enum": [
        1,
        10,
        56,
        137,
        8453,
        42161
      ]
    },
    "txHash": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$"
    },
    "requestId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 79,
      "pattern": "^([A-Za-z0-9-]{1,64}|g:[0-9]{1,10}:0x[0-9a-fA-F]{64})$"
    }
  },
  "additionalProperties": false
}

Finds a token by symbol or contract address on Ethereum, Arbitrum, Base, BNB Chain, Polygon or Optimism and returns its address, decimals and whether it is on Cleave's token list, with a flag when it resembles a listed token. A symbol shared by several listed tokens returns every candidate by address instead of picking one. An unlisted token is found only by its address and comes back flagged, without a name or symbol. It fits before cleave_plan_swap when the user names a token by symbol and the address is unknown.

{
  "type": "object",
  "properties": {
    "chainId": {
      "type": "integer",
      "enum": [
        1,
        10,
        56,
        137,
        8453,
        42161
      ]
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "A symbol or a contract address"
    }
  },
  "required": [
    "chainId",
    "query"
  ],
  "additionalProperties": false
}

Gets native gas (ETH, BNB or POL) on Ethereum, Arbitrum, Base, BNB Chain, Polygon or Optimism for a wallet that holds USDC on Ethereum, Arbitrum, Base, Optimism or Polygon but has no gas to send transactions. Called with the paying chain, the receiving chain, the recipient and a USDC amount, it returns an offer: the fee, the minimum native amount, the deadline, the order and one USDC authorization for the wallet to sign; signing costs no gas. Called again with the offer and the signature, it passes the signed order to Cleave's relayer, which executes it through a contract made for that one order, and returns a requestId for cleave_track_swap. On one chain the recipient gets at least the minimum or nothing moves; from another chain it gets the native coin at the minimum, else USDC on arrival if the arrival swap fails. An order not executed by its deadline is refunded to the refund address, or, if paid from another chain and not filled, refunded hours later. When the wallet already holds some gas, cleave_plan_swap plans a swap to the native coin.

{
  "type": "object",
  "properties": {
    "payChainId": {
      "type": "integer",
      "enum": [
        1,
        10,
        56,
        137,
        8453,
        42161
      ]
    },
    "chainId": {
      "type": "integer",
      "enum": [
        1,
        10,
        56,
        137,
        8453,
        42161
      ]
    },
    "recipient": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "amount": {
      "type": "string",
      "pattern": "^[0-9]+(\\.[0-9]+)?$",
      "description": "A decimal amount in token units"
    },
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "refundTo": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "offer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "signature": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]+$"
    }
  },
  "additionalProperties": false
}