@cleave-protocol/ai-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cleave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,267 @@
-# Temporary Holding Version
+# @cleave-protocol/ai-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cleave swap tools for [Vercel AI SDK](https://ai-sdk.dev) agents.
+
+Cleave is a DEX aggregator on Ethereum, Arbitrum, Base, BNB Chain, Polygon
+and Optimism. It splits a trade across pools and paths, and swaps between
+chains in one step. Quotes include Cleave's fees in the price.
+
+These tools plan swaps and return unsigned calls. The user's own wallet
+signs and sends them. They sign nothing; the only thing they send is a gas
+order the wallet has signed.
+
+## Install
+
+```sh
+npm install @cleave-protocol/ai-sdk ai zod
+```
+
+No API key is needed.
+
+## Usage
+
+```ts
+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`.
+
+`cleaveTools()` includes `getGas`. Its second call passes a gas order the
+wallet has signed to Cleave's relayer. That call waits for your approval
+by default; see [Approving a gas order](#approving-a-gas-order).
+
+Each tool can also be added on its own:
+
+```ts
+import { findToken, planSwap } from '@cleave-protocol/ai-sdk';
+
+const tools = { planSwap: planSwap(), findToken: findToken() };
+```
+
+## Tools
+
+The tools match Cleave's MCP server tools and call the public
+[Agent REST API](https://cleave.fi/docs/agents/rest).
+
+| 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 |
+
+The usual flow:
+
+1. `findToken`, when a symbol is ambiguous.
+2. `planSwap`, with the wallet, the tokens and the amount.
+3. The wallet signs the returned `calls` in order, before `validUntil`.
+4. `trackSwap`, with the chain, the transaction hash and the plan's
+   `requestId`.
+
+Check with `trackSwap` before sending a plan again: a plan still in flight
+that is sent twice can pay twice.
+
+A plan states its notices first, then the outcome kind, the costs charged
+by others, the expected time and `validUntil`. A `block` notice means no
+calls. A `warn` notice, or a recipient other than the wallet, sets
+`requiresConfirmation`. The token to receive must be on Cleave's token
+list.
+
+Before any wallet signs, show the user the warnings, recipient, amounts
+and slippage, and get their confirmation. Do not raise slippage above the
+default 50 bps without the user's consent. Your signer enforces this: the
+tools only plan.
+
+`findToken` returns up to ten candidates for a symbol. When the user can
+give a verified contract address, prefer it to a symbol.
+
+Field-by-field answers are documented at
+[cleave.fi/docs/agents/mcp](https://cleave.fi/docs/agents/mcp).
+
+## Keys and signing
+
+- The tools take no private keys.
+- They sign nothing; the only thing they send is a gas order the wallet
+  has signed.
+- `planSwap` returns unsigned calls as `{ chainId, from, to, data, value }`.
+- `getGas` returns an offer with one USDC authorization to sign. Called
+  again with that offer, the wallet and the wallet's signature, it passes
+  the signed order to Cleave's relayer. That second call has
+  `needsApproval` set, so the AI SDK asks for your approval before it runs.
+
+## Gas top-ups
+
+`getGas` takes two calls.
+
+1. The offer: `payChainId`, `chainId`, `recipient` and `amount`.
+   - `typedData`, the USDC authorization to sign, comes back only when
+     `wallet` is passed.
+   - An order from another chain needs `wallet` or `refundTo`. On one
+     chain, a refund goes to `refundTo`, else `wallet`, else the recipient.
+   - `amount` is USDC with at most 6 decimals, from 2 to 50 USDC; gas
+     delivered on Ethereum needs at least 5 USDC.
+2. The order: `offer`, `wallet` and `signature`. The tool passes the
+   signed order to Cleave's relayer.
+
+An authorization that is never used never debits the wallet. Once an
+order is funded, follow `trackSwap` with its `requestId`
+(`g:<payChainId>:<orderHash>`) and report the status it gives; do not
+assume a refund.
+
+### Approving a gas order
+
+The second `getGas` call has `needsApproval` set, so `generateText` stops
+with a `tool-approval-request` instead of running it. Your app shows the
+request to the user and resumes with their answer:
+
+```ts
+import { generateText, isStepCount } from 'ai';
+import type { ModelMessage, ToolApprovalResponse } from 'ai';
+import { cleaveTools } from '@cleave-protocol/ai-sdk';
+
+const tools = cleaveTools();
+const messages: ModelMessage[] = [
+  { role: 'user', content: 'Submit the gas order my wallet just signed.' },
+];
+
+const first = await generateText({
+  model: 'openai/gpt-5-mini',
+  tools,
+  messages,
+  stopWhen: isStepCount(5),
+});
+messages.push(...first.response.messages);
+
+const approvals: ToolApprovalResponse[] = [];
+for (const part of first.content) {
+  if (part.type === 'tool-approval-request') {
+    approvals.push({
+      type: 'tool-approval-response',
+      approvalId: part.approvalId,
+      approved: await confirmWithUser(part.toolCall.input),
+    });
+  }
+}
+
+if (approvals.length > 0) {
+  messages.push({ role: 'tool', content: approvals });
+  const second = await generateText({
+    model: 'openai/gpt-5-mini',
+    tools,
+    messages,
+    stopWhen: isStepCount(5),
+  });
+  console.log(second.text);
+}
+```
+
+`confirmWithUser` stands for your own prompt to the user.
+
+- This approval comes after the wallet has signed. Before the wallet
+  signs, show the user the order from the offer: the payer, the
+  recipient, the refund address, the amount and the fee.
+- Calling a tool's `.execute()` directly skips the AI SDK's approval step.
+- `getGasApproval: false` turns the approval off.
+
+## Options
+
+Every factory, and `cleaveTools`, takes the same optional settings:
+
+```ts
+cleaveTools({
+  baseUrl: 'https://api.cleave.fi',
+  apiKey: process.env.CLEAVE_API_KEY,
+  timeoutMs: 30000,
+  fetch: globalThis.fetch,
+  getGasApproval: true,
+});
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `baseUrl` | `https://api.cleave.fi` | API origin |
+| `apiKey` | none | Optional partner key, sent to `baseUrl` as `Authorization: Bearer`. An unknown or revoked key fails every call with `unauthorized`; there is no keyless fallback |
+| `timeoutMs` | `30000` | Time limit for each call, combined with the AI SDK's abort signal |
+| `fetch` | `globalThis.fetch` | A custom fetch |
+| `getGasApproval` | `true` | Whether `getGas` asks for approval before passing a signed order |
+
+## Errors
+
+A refusal from the API comes back as the tool's result, unchanged, so the
+model can read it:
+
+```json
+{
+  "apiVersion": "1",
+  "requestId": "...",
+  "error": {
+    "code": "not_found",
+    "reason": "unknown_order",
+    "message": "...",
+    "detail": "...",
+    "retryable": false
+  }
+}
+```
+
+`retryable: true` means the same call can succeed later; `retryAfterSec`,
+when present, says when.
+
+`CleaveApiError` is thrown when there is no API answer to return:
+
+- a network error, a timeout or an abort: `status` is `0` and `cause`
+  holds the original error;
+- an answer that is not JSON: `status` is the HTTP status.
+
+`requestId` carries the `x-request-id` header when the API sent one.
+
+Aborting a call, or a timeout, does not cancel a gas order the API has
+already accepted. If a `getGas` submission fails this way, track
+`g:<payChainId>:<orderHash>` from the first offer before signing a new
+one.
+
+## Server side only
+
+Run these 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`.
+
+## Limits
+
+- Without a key, each client IP can make 40 requests per 10 seconds and
+  120 per minute.
+- From a recognised hosted platform, where many agents share one address,
+  a request with a valid `wallet` in its body is counted by that wallet
+  instead. `findToken` and `trackSwap` take no `wallet`, so they stay
+  counted by IP.
+- With `apiKey`, calls count against the partner key's own limits.
+- All keyless agents share one planning capacity, used by `planSwap` and
+  by `getGas` offers; a cross-chain plan or offer counts twice. When it is
+  busy, the answer is `rate_limited` with reason `agent_limit` and a short
+  `retryAfterSec`.
+
+## Links
+
+- [Cleave for agents](https://cleave.fi/docs/agents)
+- [Agent REST API](https://cleave.fi/docs/agents/rest)
+- [Gas top-up](https://cleave.fi/docs/agents/gas)
+- [MCP server](https://cleave.fi/docs/agents/mcp): `https://api.cleave.fi/mcp`
+
+Use of the API is subject to Cleave's
+[Terms of Use](https://cleave.fi/terms) and
+[Privacy Policy](https://cleave.fi/privacy).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,177 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+var index_exports = {};
+__export(index_exports, {
+  CHAIN_IDS: () => CHAIN_IDS,
+  CleaveApiError: () => CleaveApiError,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  cleaveTools: () => cleaveTools,
+  findToken: () => findToken,
+  getGas: () => getGas,
+  planSwap: () => planSwap,
+  trackSwap: () => trackSwap
+});
+module.exports = __toCommonJS(index_exports);
+
+var import_ai = require("ai");
+
+var DEFAULT_BASE_URL = "https://api.cleave.fi";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var USER_AGENT = `cleave-ai-sdk/${"0.1.0"}`;
+var CleaveApiError = class extends Error {
+  status;
+  requestId;
+  constructor(message, status, requestId = null, options) {
+    super(message, options);
+    this.name = "CleaveApiError";
+    this.status = status;
+    this.requestId = requestId;
+  }
+};
+function untilAborted(signal) {
+  return new Promise((_, reject) => {
+    if (signal.aborted) reject(signal.reason);
+    else signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+}
+async function callTool(endpoint, input, options, abortSignal) {
+  const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const headers = { "content-type": "application/json", accept: "application/json", "user-agent": USER_AGENT };
+  if (options.apiKey !== void 0 && options.apiKey !== "") headers.authorization = `Bearer ${options.apiKey}`;
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const signal = abortSignal === void 0 ? timeout : AbortSignal.any([abortSignal, timeout]);
+  const stopped = untilAborted(signal);
+  stopped.catch(() => void 0);
+  let response;
+  let text;
+  try {
+    response = await Promise.race([doFetch(`${base}/agent/v1/${endpoint}`, { method: "POST", headers, body: JSON.stringify(input), signal }), stopped]);
+    text = await Promise.race([response.text(), stopped]);
+  } catch (err) {
+    const message = abortSignal?.aborted ? "The Cleave API call was aborted" : timeout.aborted ? `Cleave API did not answer within ${timeoutMs} ms` : "Cleave API could not be reached";
+    throw new CleaveApiError(message, 0, null, { cause: err });
+  }
+  const requestId = response.headers.get("x-request-id");
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch (err) {
+    throw new CleaveApiError(`Cleave API answered HTTP ${response.status} without a JSON body`, response.status, requestId, { cause: err });
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw new CleaveApiError(`Cleave API answered HTTP ${response.status} without a JSON object`, response.status, requestId);
+  if (!response.ok && !("error" in body)) throw new CleaveApiError(`Cleave API answered HTTP ${response.status} without an error body`, response.status, requestId);
+  return body;
+}
+
+var import_v4 = require("zod/v4");
+var CHAIN_IDS = [1, 10, 56, 137, 8453, 42161];
+var chain = (description) => import_v4.z.literal(CHAIN_IDS).meta({ type: "integer" }).describe(description);
+var address = (description) => import_v4.z.string().regex(/^0x[0-9a-fA-F]{40}$/).describe(description);
+var token = (description) => import_v4.z.string().min(1).max(64).describe(description);
+var amount = (description) => import_v4.z.string().regex(/^[0-9]+(\.[0-9]+)?$/).describe(description);
+var planSwapInput = import_v4.z.strictObject({
+  fromChainId: chain("Chain id of the token to sell: 1 Ethereum, 10 Optimism, 56 BNB Chain, 137 Polygon, 8453 Base, 42161 Arbitrum"),
+  toChainId: chain("Chain id of the token to receive; defaults to fromChainId").optional(),
+  sellToken: token("The token to sell: a listed symbol or a contract address"),
+  buyToken: token("The token to receive: a listed symbol or a contract address"),
+  amount: amount('Decimal amount of sellToken in token units, such as "25.5"'),
+  wallet: address("The wallet that signs and pays"),
+  recipient: address("Who receives; defaults to wallet").optional(),
+  maxSlippageBps: import_v4.z.number().int().min(0).max(5e3).describe("Slippage limit in basis points, 0 to 5000").optional()
+});
+var trackSwapInput = import_v4.z.strictObject({
+  chainId: chain("Chain id of the sent transaction").optional(),
+  txHash: import_v4.z.string().regex(/^0x[0-9a-fA-F]{64}$/).describe("Hash of the sent transaction").optional(),
+  requestId: import_v4.z.string().min(1).max(79).regex(/^([A-Za-z0-9-]{1,64}|g:[0-9]{1,10}:0x[0-9a-fA-F]{64})$/).describe("The plan's requestId, or for a gas order its requestId alone (g:<payChainId>:<orderHash>)").optional()
+});
+var findTokenInput = import_v4.z.strictObject({
+  chainId: chain("Chain id to search on"),
+  query: import_v4.z.string().min(1).max(64).describe("A symbol or a contract address")
+});
+var getGasInput = import_v4.z.strictObject({
+  payChainId: chain("Chain id the USDC is paid on (first call)").optional(),
+  chainId: chain("Chain id the native coin is delivered on (first call)").optional(),
+  recipient: address("Who receives the native coin (first call)").optional(),
+  amount: amount('USDC to pay, as a decimal string such as "5" (first call)').optional(),
+  wallet: address("The paying wallet; with it, the offer carries the authorization to sign. Required on the second call").optional(),
+  refundTo: address("Where a refund goes on the pay chain (first call)").optional(),
+  offer: import_v4.z.string().min(1).max(4096).describe("The offer string from the first call (second call)").optional(),
+  signature: import_v4.z.string().regex(/^0x[0-9a-fA-F]+$/).describe("The wallet's signature of the offer's typedData (second call)").optional()
+});
+
+var DESCRIPTIONS = {
+  planSwap: "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.",
+  trackSwap: "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.",
+  findToken: "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.",
+  getGas: "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."
+};
+var NAMES = " In this package, cleave_plan_swap, cleave_track_swap, cleave_find_token and cleave_get_gas are the tools planSwap, trackSwap, findToken and getGas.";
+var PLAN_SUFFIX = " This package has no connection settings, and the token to receive must be on Cleave's token list. Before any wallet signs, show the user the warnings, recipient, amounts and slippage, and get their confirmation. Do not raise slippage above the default 50 bps without the user's consent.";
+var GAS_SUFFIX = " If a submission fails or times out, the order may still have been accepted: track g:<payChainId>:<orderHash> before signing a new offer.";
+function planSwap(options = {}) {
+  return (0, import_ai.tool)({
+    title: "Plan a swap, bridge or gas top-up",
+    description: DESCRIPTIONS.planSwap + PLAN_SUFFIX + NAMES,
+    inputSchema: planSwapInput,
+    execute: (input, { abortSignal }) => callTool("plan_swap", input, options, abortSignal)
+  });
+}
+function trackSwap(options = {}) {
+  return (0, import_ai.tool)({
+    title: "Track a planned swap or transfer",
+    description: DESCRIPTIONS.trackSwap + NAMES,
+    inputSchema: trackSwapInput,
+    execute: (input, { abortSignal }) => callTool("track_swap", input, options, abortSignal)
+  });
+}
+function findToken(options = {}) {
+  return (0, import_ai.tool)({
+    title: "Find a token's contract address",
+    description: DESCRIPTIONS.findToken + NAMES,
+    inputSchema: findTokenInput,
+    execute: (input, { abortSignal }) => callTool("find_token", input, options, abortSignal)
+  });
+}
+function getGas(options = {}) {
+  return (0, import_ai.tool)({
+    title: "Get native gas with USDC",
+    description: DESCRIPTIONS.getGas + GAS_SUFFIX + NAMES,
+    inputSchema: getGasInput,
+    needsApproval: options.getGasApproval === false ? false : (input) => input.signature !== void 0,
+    execute: (input, { abortSignal }) => callTool("get_gas", input, options, abortSignal)
+  });
+}
+function cleaveTools(options = {}) {
+  return { planSwap: planSwap(options), trackSwap: trackSwap(options), findToken: findToken(options), getGas: getGas(options) };
+}
+0 && (module.exports = {
+  CHAIN_IDS,
+  CleaveApiError,
+  DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT_MS,
+  cleaveTools,
+  findToken,
+  getGas,
+  planSwap,
+  trackSwap
+});

package/dist/index.d.cts

@@ -0,0 +1,70 @@
+import { Tool } from 'ai';
+import { z } from 'zod/v4';
+
+declare const DEFAULT_BASE_URL = "https://api.cleave.fi";
+declare const DEFAULT_TIMEOUT_MS = 30000;
+interface CleaveToolsOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+    getGasApproval?: boolean;
+}
+type CleaveResult = Record<string, unknown>;
+declare class CleaveApiError extends Error {
+    readonly status: number;
+    readonly requestId: string | null;
+    constructor(message: string, status: number, requestId?: string | null, options?: {
+        cause?: unknown;
+    });
+}
+
+declare const CHAIN_IDS: readonly [1, 10, 56, 137, 8453, 42161];
+declare const planSwapInput: z.ZodObject<{
+    fromChainId: z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>;
+    toChainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    sellToken: z.ZodString;
+    buyToken: z.ZodString;
+    amount: z.ZodString;
+    wallet: z.ZodString;
+    recipient: z.ZodOptional<z.ZodString>;
+    maxSlippageBps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+declare const trackSwapInput: z.ZodObject<{
+    chainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    txHash: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const findTokenInput: z.ZodObject<{
+    chainId: z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>;
+    query: z.ZodString;
+}, z.core.$strict>;
+declare const getGasInput: z.ZodObject<{
+    payChainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    chainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    recipient: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodString>;
+    wallet: z.ZodOptional<z.ZodString>;
+    refundTo: z.ZodOptional<z.ZodString>;
+    offer: z.ZodOptional<z.ZodString>;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type PlanSwapInput = z.infer<typeof planSwapInput>;
+type TrackSwapInput = z.infer<typeof trackSwapInput>;
+type FindTokenInput = z.infer<typeof findTokenInput>;
+type GetGasInput = z.infer<typeof getGasInput>;
+
+type CleaveTools = {
+    planSwap: Tool<PlanSwapInput, CleaveResult>;
+    trackSwap: Tool<TrackSwapInput, CleaveResult>;
+    findToken: Tool<FindTokenInput, CleaveResult>;
+    getGas: Tool<GetGasInput, CleaveResult>;
+};
+declare function planSwap(options?: CleaveToolsOptions): Tool<PlanSwapInput, CleaveResult>;
+declare function trackSwap(options?: CleaveToolsOptions): Tool<TrackSwapInput, CleaveResult>;
+declare function findToken(options?: CleaveToolsOptions): Tool<FindTokenInput, CleaveResult>;
+declare function getGas(options?: CleaveToolsOptions): Tool<GetGasInput, CleaveResult>;
+declare function cleaveTools(options?: CleaveToolsOptions): CleaveTools;
+
+export { CHAIN_IDS, CleaveApiError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, cleaveTools, findToken, getGas, planSwap, trackSwap };
+export type { CleaveResult, CleaveTools, CleaveToolsOptions, FindTokenInput, GetGasInput, PlanSwapInput, TrackSwapInput };

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { Tool } from 'ai';
+import { z } from 'zod/v4';
+
+declare const DEFAULT_BASE_URL = "https://api.cleave.fi";
+declare const DEFAULT_TIMEOUT_MS = 30000;
+interface CleaveToolsOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+    getGasApproval?: boolean;
+}
+type CleaveResult = Record<string, unknown>;
+declare class CleaveApiError extends Error {
+    readonly status: number;
+    readonly requestId: string | null;
+    constructor(message: string, status: number, requestId?: string | null, options?: {
+        cause?: unknown;
+    });
+}
+
+declare const CHAIN_IDS: readonly [1, 10, 56, 137, 8453, 42161];
+declare const planSwapInput: z.ZodObject<{
+    fromChainId: z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>;
+    toChainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    sellToken: z.ZodString;
+    buyToken: z.ZodString;
+    amount: z.ZodString;
+    wallet: z.ZodString;
+    recipient: z.ZodOptional<z.ZodString>;
+    maxSlippageBps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+declare const trackSwapInput: z.ZodObject<{
+    chainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    txHash: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const findTokenInput: z.ZodObject<{
+    chainId: z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>;
+    query: z.ZodString;
+}, z.core.$strict>;
+declare const getGasInput: z.ZodObject<{
+    payChainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    chainId: z.ZodOptional<z.ZodLiteral<1 | 10 | 56 | 137 | 8453 | 42161>>;
+    recipient: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodString>;
+    wallet: z.ZodOptional<z.ZodString>;
+    refundTo: z.ZodOptional<z.ZodString>;
+    offer: z.ZodOptional<z.ZodString>;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type PlanSwapInput = z.infer<typeof planSwapInput>;
+type TrackSwapInput = z.infer<typeof trackSwapInput>;
+type FindTokenInput = z.infer<typeof findTokenInput>;
+type GetGasInput = z.infer<typeof getGasInput>;
+
+type CleaveTools = {
+    planSwap: Tool<PlanSwapInput, CleaveResult>;
+    trackSwap: Tool<TrackSwapInput, CleaveResult>;
+    findToken: Tool<FindTokenInput, CleaveResult>;
+    getGas: Tool<GetGasInput, CleaveResult>;
+};
+declare function planSwap(options?: CleaveToolsOptions): Tool<PlanSwapInput, CleaveResult>;
+declare function trackSwap(options?: CleaveToolsOptions): Tool<TrackSwapInput, CleaveResult>;
+declare function findToken(options?: CleaveToolsOptions): Tool<FindTokenInput, CleaveResult>;
+declare function getGas(options?: CleaveToolsOptions): Tool<GetGasInput, CleaveResult>;
+declare function cleaveTools(options?: CleaveToolsOptions): CleaveTools;
+
+export { CHAIN_IDS, CleaveApiError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, cleaveTools, findToken, getGas, planSwap, trackSwap };
+export type { CleaveResult, CleaveTools, CleaveToolsOptions, FindTokenInput, GetGasInput, PlanSwapInput, TrackSwapInput };

package/dist/index.js

@@ -0,0 +1,144 @@
+import { tool } from "ai";
+
+var DEFAULT_BASE_URL = "https://api.cleave.fi";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var USER_AGENT = `cleave-ai-sdk/${"0.1.0"}`;
+var CleaveApiError = class extends Error {
+  status;
+  requestId;
+  constructor(message, status, requestId = null, options) {
+    super(message, options);
+    this.name = "CleaveApiError";
+    this.status = status;
+    this.requestId = requestId;
+  }
+};
+function untilAborted(signal) {
+  return new Promise((_, reject) => {
+    if (signal.aborted) reject(signal.reason);
+    else signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+}
+async function callTool(endpoint, input, options, abortSignal) {
+  const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const headers = { "content-type": "application/json", accept: "application/json", "user-agent": USER_AGENT };
+  if (options.apiKey !== void 0 && options.apiKey !== "") headers.authorization = `Bearer ${options.apiKey}`;
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const signal = abortSignal === void 0 ? timeout : AbortSignal.any([abortSignal, timeout]);
+  const stopped = untilAborted(signal);
+  stopped.catch(() => void 0);
+  let response;
+  let text;
+  try {
+    response = await Promise.race([doFetch(`${base}/agent/v1/${endpoint}`, { method: "POST", headers, body: JSON.stringify(input), signal }), stopped]);
+    text = await Promise.race([response.text(), stopped]);
+  } catch (err) {
+    const message = abortSignal?.aborted ? "The Cleave API call was aborted" : timeout.aborted ? `Cleave API did not answer within ${timeoutMs} ms` : "Cleave API could not be reached";
+    throw new CleaveApiError(message, 0, null, { cause: err });
+  }
+  const requestId = response.headers.get("x-request-id");
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch (err) {
+    throw new CleaveApiError(`Cleave API answered HTTP ${response.status} without a JSON body`, response.status, requestId, { cause: err });
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw new CleaveApiError(`Cleave API answered HTTP ${response.status} without a JSON object`, response.status, requestId);
+  if (!response.ok && !("error" in body)) throw new CleaveApiError(`Cleave API answered HTTP ${response.status} without an error body`, response.status, requestId);
+  return body;
+}
+
+import { z } from "zod/v4";
+var CHAIN_IDS = [1, 10, 56, 137, 8453, 42161];
+var chain = (description) => z.literal(CHAIN_IDS).meta({ type: "integer" }).describe(description);
+var address = (description) => z.string().regex(/^0x[0-9a-fA-F]{40}$/).describe(description);
+var token = (description) => z.string().min(1).max(64).describe(description);
+var amount = (description) => z.string().regex(/^[0-9]+(\.[0-9]+)?$/).describe(description);
+var planSwapInput = z.strictObject({
+  fromChainId: chain("Chain id of the token to sell: 1 Ethereum, 10 Optimism, 56 BNB Chain, 137 Polygon, 8453 Base, 42161 Arbitrum"),
+  toChainId: chain("Chain id of the token to receive; defaults to fromChainId").optional(),
+  sellToken: token("The token to sell: a listed symbol or a contract address"),
+  buyToken: token("The token to receive: a listed symbol or a contract address"),
+  amount: amount('Decimal amount of sellToken in token units, such as "25.5"'),
+  wallet: address("The wallet that signs and pays"),
+  recipient: address("Who receives; defaults to wallet").optional(),
+  maxSlippageBps: z.number().int().min(0).max(5e3).describe("Slippage limit in basis points, 0 to 5000").optional()
+});
+var trackSwapInput = z.strictObject({
+  chainId: chain("Chain id of the sent transaction").optional(),
+  txHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/).describe("Hash of the sent transaction").optional(),
+  requestId: z.string().min(1).max(79).regex(/^([A-Za-z0-9-]{1,64}|g:[0-9]{1,10}:0x[0-9a-fA-F]{64})$/).describe("The plan's requestId, or for a gas order its requestId alone (g:<payChainId>:<orderHash>)").optional()
+});
+var findTokenInput = z.strictObject({
+  chainId: chain("Chain id to search on"),
+  query: z.string().min(1).max(64).describe("A symbol or a contract address")
+});
+var getGasInput = z.strictObject({
+  payChainId: chain("Chain id the USDC is paid on (first call)").optional(),
+  chainId: chain("Chain id the native coin is delivered on (first call)").optional(),
+  recipient: address("Who receives the native coin (first call)").optional(),
+  amount: amount('USDC to pay, as a decimal string such as "5" (first call)').optional(),
+  wallet: address("The paying wallet; with it, the offer carries the authorization to sign. Required on the second call").optional(),
+  refundTo: address("Where a refund goes on the pay chain (first call)").optional(),
+  offer: z.string().min(1).max(4096).describe("The offer string from the first call (second call)").optional(),
+  signature: z.string().regex(/^0x[0-9a-fA-F]+$/).describe("The wallet's signature of the offer's typedData (second call)").optional()
+});
+
+var DESCRIPTIONS = {
+  planSwap: "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.",
+  trackSwap: "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.",
+  findToken: "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.",
+  getGas: "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."
+};
+var NAMES = " In this package, cleave_plan_swap, cleave_track_swap, cleave_find_token and cleave_get_gas are the tools planSwap, trackSwap, findToken and getGas.";
+var PLAN_SUFFIX = " This package has no connection settings, and the token to receive must be on Cleave's token list. Before any wallet signs, show the user the warnings, recipient, amounts and slippage, and get their confirmation. Do not raise slippage above the default 50 bps without the user's consent.";
+var GAS_SUFFIX = " If a submission fails or times out, the order may still have been accepted: track g:<payChainId>:<orderHash> before signing a new offer.";
+function planSwap(options = {}) {
+  return tool({
+    title: "Plan a swap, bridge or gas top-up",
+    description: DESCRIPTIONS.planSwap + PLAN_SUFFIX + NAMES,
+    inputSchema: planSwapInput,
+    execute: (input, { abortSignal }) => callTool("plan_swap", input, options, abortSignal)
+  });
+}
+function trackSwap(options = {}) {
+  return tool({
+    title: "Track a planned swap or transfer",
+    description: DESCRIPTIONS.trackSwap + NAMES,
+    inputSchema: trackSwapInput,
+    execute: (input, { abortSignal }) => callTool("track_swap", input, options, abortSignal)
+  });
+}
+function findToken(options = {}) {
+  return tool({
+    title: "Find a token's contract address",
+    description: DESCRIPTIONS.findToken + NAMES,
+    inputSchema: findTokenInput,
+    execute: (input, { abortSignal }) => callTool("find_token", input, options, abortSignal)
+  });
+}
+function getGas(options = {}) {
+  return tool({
+    title: "Get native gas with USDC",
+    description: DESCRIPTIONS.getGas + GAS_SUFFIX + NAMES,
+    inputSchema: getGasInput,
+    needsApproval: options.getGasApproval === false ? false : (input) => input.signature !== void 0,
+    execute: (input, { abortSignal }) => callTool("get_gas", input, options, abortSignal)
+  });
+}
+function cleaveTools(options = {}) {
+  return { planSwap: planSwap(options), trackSwap: trackSwap(options), findToken: findToken(options), getGas: getGas(options) };
+}
+export {
+  CHAIN_IDS,
+  CleaveApiError,
+  DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT_MS,
+  cleaveTools,
+  findToken,
+  getGas,
+  planSwap,
+  trackSwap
+};

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@cleave-protocol/ai-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cleave agent tools for the Vercel AI SDK: plan swaps as unsigned calls, track them, find tokens, and order gas top-ups, submitting the gas orders a wallet has signed.",
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "vercel-ai-sdk",
+    "tools",
+    "agents",
+    "dex",
+    "dex-aggregator",
+    "swap",
+    "cross-chain",
+    "bridge",
+    "ethereum",
+    "arbitrum",
+    "base",
+    "bnb",
+    "polygon",
+    "optimism"
+  ],
+  "homepage": "https://cleave.fi/docs/agents",
+  "bugs": {
+    "url": "https://github.com/cleave-protocol/ai-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cleave-protocol/ai-sdk.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc",
+    "test": "vitest run",
+    "lint": "publint && attw --pack .",
+    "probe": "npm run build && node scripts/probe.mjs",
+    "rename": "node scripts/rename.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run lint"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0 || ^7.0.0",
+    "zod": "^3.25.76 || ^4.1.8"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^22.20.5",
+    "ai": "^7.0.159",
+    "publint": "^0.3.25",
+    "tsup": "^9.0.0",
+    "typescript": "~5.9.3",
+    "vitest": "^5.0.5",
+    "zod": "^4.6.7"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}