Cleave for the Vercel AI SDK

Install

npm install @cleave-protocol/ai-sdk ai zod

No API key is needed.

Example

import { generateText, isStepCount } from 'ai';
import { cleaveTools } from '@cleave-protocol/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  prompt:
    'Plan a swap of 25 USDC to WETH on Base for wallet 0x00000000000000000000000000000000000A11cE.',
  tools: cleaveTools(),
  stopWhen: isStepCount(5),
});

console.log(text);

On ai 6, use stepCountIs in place of isStepCount.

Each tool can also be added on its own:

import { findToken, planSwap } from '@cleave-protocol/ai-sdk';

const tools = { planSwap: planSwap(), findToken: findToken() };

The four tools

The tools match the tools of the MCP server and call the public Agent REST API.

Tool	MCP tool	What it does
`planSwap`	`cleave_plan_swap`	Plans a swap on one chain, a cross-chain swap or a bridge, and returns unsigned calls in signing order
`trackSwap`	`cleave_track_swap`	Reports the state of a sent plan or gas order, and what arrived
`findToken`	`cleave_find_token`	Finds a token by symbol or address and flags look-alikes
`getGas`	`cleave_get_gas`	Offers native gas for USDC, then passes the order the wallet signed to Cleave's relayer

What the tools return

planSwap returns unsigned calls as { chainId, from, to, data, value }, in signing order. The user's own wallet signs and sends them.
The tools take no private keys. They sign nothing; the only thing they send is a gas order the wallet has signed.
A plan states its notices first, then the outcome kind, the costs charged by others, the expected time and validUntil. Cleave's fees are included in the price.
A block notice means no calls. A warn notice, or a recipient other than the wallet, sets requiresConfirmation.

Gas orders wait for approval

getGas takes two calls. The first returns an offer with one USDC authorization to sign. The second passes the order the wallet signed to Cleave's relayer.
That second call asks for your approval by default: generateText stops with a tool-approval-request, and your app resumes with the user's answer.
getGasApproval: false turns the approval off.
Calling a tool's .execute() directly skips the AI SDK's approval step.
An authorization that is never used never debits the wallet.

Before signing

Before any wallet signs, show the user the warnings, the recipient, the amounts and the slippage, and get their confirmation. Do not raise slippage above the default 50 bps without the user's consent. The tools only plan: your app, or the signer it uses, enforces this.

Check with trackSwap before sending a plan again: a plan still in flight that is sent twice can pay twice.

Server side only

Run the tools on a server, in a bot or in agent code. The Agent REST API refuses requests that carry an Origin header, as browsers send, with 403 and code forbidden_origin.

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.