Install
pip install -U langchain-cleavePython 3.10 or later. No API key is needed. Version 0.2.0 also installs pycryptodome.
Example
This example also needs langchain and a chat model package:
pip install -U langchain-cleave langchain "langchain[anthropic]"from langchain.agents import create_agent
from langchain_cleave import CleaveToolkit
agent = create_agent(
model="claude-sonnet-4-6",
tools=CleaveToolkit().get_tools(),
)
agent.invoke(
{
"messages": [
{
"role": "user",
"content": (
"Plan a swap of 25 USDC to WETH on Base for wallet "
"0x00000000000000000000000000000000000A11cE"
),
}
]
}
)The four tools
The tools have the same names, inputs and answers as the tools of the MCP server, and call the keyless Agent REST API. CleaveToolkit().get_tools() returns all four.
| Tool | Class | What it does |
|---|---|---|
cleave_plan_swap | CleavePlanSwap | Plans a swap on one chain, a cross-chain swap or a bridge, and returns unsigned calls in signing order |
cleave_track_swap | CleaveTrackSwap | Reports the state of a sent plan or a gas order, and what arrived |
cleave_find_token | CleaveFindToken | Finds a token by symbol or address and flags look-alikes |
cleave_get_gas | CleaveGetGas | Offers native gas for USDC; with the relay turned on, passes the order the wallet signed to Cleave's relayer |
What the tools return
cleave_plan_swapreturns a plan whosecallsare unsigned and in signing order. The user's own wallet signs and sends them.- The tools never take a private key. They sign nothing; the only thing they send is a gas order the wallet has signed, and only when the gas relay is turned on.
- Read a plan in this order:
blockedandnotices, thenrequiresConfirmation, thenroute.outcomeKindandreceive, thenfees, thenvalidUntil. feeslists costs charged by others, such as a bridge fee. Cleave's fees are included in the price.
Address checks
Before a cleave_plan_swap plan or a cleave_get_gas offer reaches the model, the package checks it against Cleave's contracts, functions, rails and tokens, pinned per chain in the package.
- A plan or offer that fails a check becomes an
address_not_allowedrefusal, with no calls and no typed data. - A plan or offer that passes keeps only its documented top-level fields.
- An error answer whose body has no
errorobject becomes anhttp_errorrefusal, retryable for 5xx and 429. - After Cleave redeploys a contract, plans that use it fail these checks until a package update pins the new address.
What the checks do not cover
- The price, the route and the amount received.
- Recipients inside a bridge handler or composer message. On routes that swap on arrival or pay a fee through the bridge message, the funds go to the bridge's handler or Cleave's composer, and that message decides who receives them. Have a person check such a plan before signing.
- Sell tokens other than USDC and the chain's native and wrapped native coin. For a symbol, check
send.token; for any such token, check the approve amount andpullsAtMost. - The native messaging fee some bridges charge. It is the API's figure, and nothing bounds it.
- The
nexttext and the notices, which are text from the API.
Calling the API directly
Agents that call the API without these tools should pass each answer through screen_plan_swap(request, body) or screen_get_gas(request, body) and forward only what they return: the refusal, or the answer cut to its documented fields. check_plan_swap and check_get_gas return only a verdict, a CheckResult with ok, rule and message; a pass from them does not make the original answer safe to forward.
The gas relay is off by default
cleave_get_gasreturns offers. A call withofferorsignaturecomes back as a refusal with coderelay_disabled, without a request.- Turn the relay on in code, not from the agent, with
include_gas_relay=True:
from langchain_cleave import CleaveGetGas, CleaveToolkit
tools = CleaveToolkit(include_gas_relay=True).get_tools()
gas = CleaveGetGas(allow_relay=True)With the relay on, HumanInTheLoopMiddleware(interrupt_on={"cleave_get_gas": True}) pauses the agent so a person approves each signed order before it is sent; the agent needs a checkpointer. An authorization that is never submitted never debits the wallet.
Before signing
- Do not pair these tools with a wallet that signs without a human looking.
- Do not act on a blocked plan.
- 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.
- Never change the recipient or raise slippage to get past a refusal or a warning.
blocked,requiresConfirmationand the notices are advisory. They bind only if your application, or the signer it uses, enforces them.
Track with cleave_track_swap before sending a plan again: a plan still in flight that is sent twice can pay twice.
Server side only
Call the API from a server, bot or agent process. The Agent REST API refuses requests that carry an Origin header, as browsers send, with 403 and code forbidden_origin.
Links
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. This notice tells you where they are. Section 1 of the Terms of Use says how they are accepted. Where the applicable law treats use after clear notice as acceptance, sending requests, connecting a client or paying for a paid route after this notice is acceptance.
If an agent or other software calls Cleave, Section 12 of the Terms of Use says when its operator is bound and what the operator is responsible for. Partner and agent keys are issued only after the key holder accepts the Terms of Use. Stay within the published rate limits.