x402 gas top-up

Pay over x402

x402 lets an agent pay for an HTTP resource with a signed USDC transfer. Cleave's gas top-up is an x402 resource.

GET https://api.cleave.fi/x402/gas/quote with pay, chainId, recipient and usdc, plus wallet or refundTo for an order from another chain. The answer is the offer, with x402.url.
GET that URL. It answers 402 with the payment requirements in the PAYMENT-REQUIRED header, as base64 JSON, and the same JSON in the body: x402 version 2, scheme exact, the USDC amount, the order address as payTo, and maxTimeoutSeconds.
Sign a USDC TransferWithAuthorization for exactly that amount to that address, valid for at most maxTimeoutSeconds.
GET the URL again with the signed payment in the PAYMENT-SIGNATURE header, echoing the requirement you accepted.
The answer is 200 with a PAYMENT-RESPONSE header once the payment is settled, or 202 while settlement is still pending. Both carry requestId, payTo, minimum, fee and deadline.

When wallet is passed to the quote, its typedData is the TransferWithAuthorization to sign.

GET https://api.cleave.fi/x402/gas without an offer answers an example 402 that cannot be paid. It shows the shape of the requirements.

How an order works

Every order works the same way, over x402 or by tool call:

Ask for an offer with the chain to pay on, the chain to receive on, the recipient and a USDC amount.
The offer states the fee, the minimum native amount, the deadline and the order itself, with the address the USDC is paid into.
The wallet signs one USDC authorization for that amount to that address.
Cleave's relayer executes the order. The payment goes to an address made for that one order, so it can only be used for this order.
Track the order with its requestId.

Outcome

On one chain: the recipient gets at least the minimum native amount. If the order cannot run, a signed authorization is never used; USDC already paid in is refunded after the deadline.
From another chain: the recipient gets the native coin, at least the minimum. If the swap on arrival fails, the recipient gets USDC on arrival instead.
Not executed in time: an order not executed by its deadline is refunded to the refund address. An order paid from another chain and not filled is refunded hours later.

The deadline is 15 minutes for an order on one chain, and 20 minutes for an order from another chain or on Ethereum.

Chains and amounts

Point	Value
Native coin delivered on	Ethereum, Arbitrum, Base, BNB Chain, Polygon, Optimism
USDC paid on, by tool call	Ethereum, Arbitrum, Base, Polygon, Optimism
USDC paid on, over x402	Base, Arbitrum, Polygon
Smallest order	2 USDC, or 5 USDC when the gas is delivered on Ethereum
Largest order	50 USDC
Fee	Stated in the offer, in USDC, inside the amount paid

The fee is the one Cleave fee shown on its own: it covers the cost of running the order.

Without x402: by tool call

Agents that do not use x402 can order the same top-up with the cleave_get_gas tool over MCP, or POST https://api.cleave.fi/agent/v1/get_gas. The order, the fee and the outcome are the same; the wallet signs a USDC ReceiveWithAuthorization instead, and this way also takes USDC on Ethereum and Optimism. It takes two calls.

Get an offer

Field	Required	Meaning
`payChainId`	yes	Chain id the USDC is paid on
`chainId`	yes	Chain id the native coin is delivered on
`recipient`	yes	Who receives the native coin
`amount`	yes	USDC to pay, as a decimal string such as `"5"`
`wallet`	no	The paying wallet; with it, the offer carries the authorization to sign
`refundTo`	no	Where a refund goes on the pay chain; an order from another chain needs `wallet` or `refundTo`

The answer carries offer (an opaque string), payTo, fee, receive.minimum, deadline, the full order, and typedData: an EIP-712 ReceiveWithAuthorization for the USDC on the pay chain, with the order's hash as its nonce.

Before signing, an agent can check the order itself: recompute orderHash and payTo from order with the published factory and template, both named in the answer.

Submit the signature

Call again with offer, signature and wallet. Cleave checks the signature and the order, then executes it. The answer carries the requestId, of the form g:<payChainId>:<orderHash>.

A regular wallet signs with a 65-byte signature. A smart-contract wallet that validates signatures on-chain can sign too.

Tracking

Call cleave_track_swap or POST https://api.cleave.fi/agent/v1/track_swap with the requestId alone. The status moves from pending to in_flight for an order from another chain, then delivered, refund_pending, refunded or failed. A delivered order shows the native amount that arrived; one delivered as USDC says so.

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.