ahhda · Oct 7, 2026 · Oct 13, 2026 · Oct 19, 2026
@@ -9,6 +9,7 @@ CoW Protocol offers multiple integration approaches to suit different developmen
 | **Widget** | Quick integration, minimal setup | Low | Basic styling and configuration |
 | **SDK** | Full control, custom UI | Medium | Complete control over UI/UX |
 | **API** | Backend integration, custom logic | High | Maximum flexibility |
+| **[x402](./x402.mdx)** | Paid quote requests from scripts and agents | Low | Prepaid payments without an API key |
 
 ## Choose Your Integration Method
 
@@ -35,4 +36,4 @@ Best for backend services, advanced integrations, and when you need maximum cont
 
 ---
 
-Choose the integration method that best fits your project's requirements and development timeline. Each approach is designed to provide progressively more control and customization options.
+Choose the integration method that best fits your project's requirements and development timeline. Each approach is designed to provide progressively more control and customization options.
@@ -1,5 +1,8 @@
 # API Integration
 
+For scripts and agents that want to pay per quote without an API key, see
+[Paid quotes with x402](./x402.mdx). The guide covers prepaid funding, quote requests and withdrawals.
+
 The CoW Protocol API provides direct access to the protocol's functionality through RESTful endpoints. This approach offers maximum flexibility and control for backend integrations and custom implementations.
 
 ## Overview
@@ -217,4 +220,3 @@ For complete API documentation including all endpoints, parameters, and response
 - **[API Explorer](https://api.cow.fi/docs/)** - Interactive documentation
 - **[GitHub Examples](https://github.com/cowprotocol/cow-sdk/tree/main/examples)** - Code examples
 - **[Order Signing Guide](../reference/core/signing_schemes.mdx)** - Cryptographic signing details
-
@@ -0,0 +1,200 @@
+---
+title: x402 recovery and withdrawals
+description: Complete x402 client example, payment recovery and withdrawal instructions.
+sidebar_position: 5
+---
+
+import CodeBlock from '@theme/CodeBlock'
+import inspectSource from '!!raw-loader!@site/static/code-examples/x402/inspect.mjs'
+import quoteSource from '!!raw-loader!@site/static/code-examples/x402/quote.mts'
+import withdrawSource from '!!raw-loader!@site/static/code-examples/x402/withdraw.mts'
+
+# x402 recovery and withdrawals
+
+Start with the [x402 quickstart](./x402.mdx) to install the SDK and set up your payer.
+This page contains the full runnable example, optional limits, recovery guidance and withdrawal steps.
+Use the same project directory and preserve its saved files when moving between the examples.
+
+## Complete quote example
+
+The SDK handles the payment protocol. The extra code here configures your limits,
+checks the RPC and receiver, saves signed attempts and original channel terms, and reports errors.
+These are application safeguards, not additional protocol steps you must implement yourself.
+
+### Inspect current terms
+
+Save <a href="/code-examples/x402/inspect.mjs" download="inspect.mjs">inspect.mjs</a> and run `node inspect.mjs`.
+It shows the current price, minimum deposit and withdrawal delay without a key, signature or payment.
+Fund your wallet with enough Base USDC if you accept the terms.
+
+<details>
+<summary>Read-only terms preview</summary>
+
+<CodeBlock language="javascript" title="inspect.mjs">
+  {inspectSource}
+</CodeBlock>
+
+</details>
+
+For illustration, a 1 USDC deposit at 0.001 USDC per quote funds 1,000 quotes while that price is unchanged.
+Always read current terms from the service.
+
+### Client limits
+
+The example defaults to **0.001 USDC per quote**, **1 USDC per deposit or top-up**, and a **24-hour maximum accepted withdrawal delay**. These are client limits, not guaranteed server terms. If an offer exceeds them, the script stops before signing.
+
+<details>
+<summary>Optional limits</summary>
+
+```text
+# Optional overrides; these are the example's defaults.
+MAX_QUOTE_USDC=0.001
+MAX_DEPOSIT_USDC=1
+MAX_WITHDRAW_DELAY_HOURS=24
+```
+
+`MAX_WITHDRAW_DELAY_HOURS` only limits which offers your client accepts. It does not choose the waiting period: a new channel takes the delay advertised by the server, and keeps that delay for its lifetime. You can omit this setting; the example accepts delays up to 24 hours.
+
+Enter price and deposit limits in human USDC units.
+A per-deposit limit applies to each top-up; it is not a lifetime spending cap.
+
+</details>
+
+### Run the complete example
+
+Save <a href="/code-examples/x402/quote.mts" download="quote.mts">quote.mts</a> in the project directory.
+It checks payment terms, uses SDK receipt validation and saves channel state and recovery files.
+The example uses `@x402/*` **2.26.0**.
+
+<details>
+<summary>Complete quote example</summary>
+
+<CodeBlock language="typescript" title="quote.mts">
+  {quoteSource}
+</CodeBlock>
+
+</details>
+
+```bash
+node --env-file=.env --import tsx quote.mts
+```
+
+A successful run prints `status: 200`, `quoteReceived: true`, the charge, a saved channel-file path and the quote JSON.
+The first request funds the channel; later requests reuse it and top up when needed, within your limits.
+The CoW Protocol x402 payment service pays deposit and collection gas.
+
+Run one request at a time per channel and keep the saved files across restarts.
+
+## Recover an uncertain payment
+
+The SDK handles a corrective `402` inside `wrapFetchWithPayment`: it validates the returned channel/voucher state, updates local storage and retries once with a fresh payment. This can produce a new charged quote; it does not retrieve a lost quote response.
+If the script still fails or the connection drops, follow these steps before rerunning it or withdrawing.
+
+**1. Stop requests on this channel and keep the evidence.** Preserve `x402-state/`, `x402-channels/`, all `x402-attempts/` files from the run, the error output and any transaction hash. Use the `savedAttempt` path printed by the error in step 2. Do not delete state, manually lower its charged total or replay the signed attempt to check its status.
+
+**2. Inspect the saved attempt and local state.** Run this from the same project directory, replacing the attempt filename. It reads local files without signing or sending a request:
+
+```bash
+ATTEMPT=./x402-attempts/YOUR_ATTEMPT.json node --input-type=module <<'JS'
+import { readFileSync } from "node:fs";
+import { getChannel } from "@x402/evm/batch-settlement/client";
+import { FileClientChannelStorage } from "@x402/evm/batch-settlement/client/file-storage";
+
+const attempt = JSON.parse(readFileSync(process.env.ATTEMPT, "utf8"));
+const channelId = attempt.payload.voucher.channelId;
+const storage = new FileClientChannelStorage({ directory: "./x402-state" });
+const local = await getChannel(storage, channelId);
+console.log({
+  channelId,
+  paymentNetwork: attempt.accepted.network,
+  paymentType: attempt.payload.type,
+  signedLimitAtomic: attempt.payload.voucher.maxClaimableAmount,
+  recordedChargesAtomic: local?.chargedCumulativeAmount ?? null,
+});
+JS
+```
+
+The signed limit is a cumulative authorization cap, not proof of a charge. `recordedChargesAtomic` is the client's last recorded total; it may be stale after a lost response. A missing record does not mean the payment failed. Keep the signed attempt private.
+
+**3. Check the chain without changing it.** Save <a href="/code-examples/x402/withdraw.mts" download="withdraw.mts">withdraw.mts</a>. Set `CHANNEL=./x402-channels/YOUR_CHANNEL_ID.json` in `.env` using the channel ID above, and keep `RPC_URL` on the payment chain. Then run:
+
+```bash
+node --env-file=.env --import tsx withdraw.mts status
+```
+
+This reads the channel balance, claimed total and withdrawal status; it sends no transaction and needs no private key. If the original error included a transaction hash, also check its receipt in the payment chain's explorer. A pending or missing receipt remains unresolved. A successful deposit proves that funds reached the channel, not that the quote was charged. The on-chain claimed total omits charges awaiting collection.
+
+**4. Establish the payment outcome.** A completed example run prints `status: 200`, `quoteReceived: true` and `chargedUSDC` from the payment receipt. If you have that output, that request succeeded and another run is a new purchase. If the receipt was lost, failed validation, or the script reported an accounting/settlement error, the checks above cannot establish whether that request was charged.
+
+Contact [CoW Protocol Discord](https://discord.com/invite/cowprotocol) with the payment network, channel ID, approximate request time, error code and any transaction hash. Ask the team to confirm the request's charge and reconcile the channel state before another payment or withdrawal. Do not post your private key, signed attempt or full state files. There is no public read-only payment-status endpoint for this check.
+
+**5. Resume only after the uncertainty is resolved.** Keep using the reconciled state and original channel configuration. Each successful new quote can incur another charge. If you are finished with the channel, follow the withdrawal steps below.
+
+:::warning Do not reset state from on-chain claims
+
+SDK 2.26.0's `recoverChannel()` rebuilds the charged total from on-chain claims. It is not a general repair for a lost response while uncollected charges may exist. The normal corrective-`402` path uses `processCorrectivePaymentRequired()` through the SDK hooks; do not bypass those checks or manually edit the charged total.
+
+:::
+
+## Withdraw unused funds
+
+You initiate a withdrawal, wait for the saved channel's deadline, then finalize it.
+These are **two transactions**, paid by your wallet in Base ETH for this example.
+Finalization returns tokens to the payer; it is not automatic.
+
+Save <a href="/code-examples/x402/withdraw.mts" download="withdraw.mts">withdraw.mts</a> in the same project directory.
+In `.env`, set `CHANNEL` to the channel-file path printed by the quote example.
+Keep `RPC_URL` on that channel's payment chain.
+
+```text
+CHANNEL=./x402-channels/YOUR_CHANNEL_ID.json
+```
+
+<details>
+<summary>Complete withdrawal example</summary>
+
+<CodeBlock language="typescript" title="withdraw.mts">
+  {withdrawSource}
+</CodeBlock>
+
+</details>
+
+**1. Check status** without spending gas:
+
+```bash
+node --env-file=.env --import tsx withdraw.mts status
+```
+
+**2. Stop using the channel and initiate** the withdrawal:
+
+```bash
+node --env-file=.env --import tsx withdraw.mts initiate
+node --env-file=.env --import tsx withdraw.mts status
+```
+
+**3. Wait until `finalizeAt`**, calculated from the on-chain initiation time and that channel's original delay.
+A new offer cannot change it.
+
+**4. Finalize**, then check the receipt and your token balance:
+
+```bash
+node --env-file=.env --import tsx withdraw.mts finalize
+node --env-file=.env --import tsx withdraw.mts status
+```
+
+The x402 payment service may collect outstanding charges during the wait, reducing the returned amount.
+Collection happens only when economic; uncollected fees do not extend the withdrawal deadline.
+A pending withdrawal cannot be cancelled.
+If a transaction times out, check its hash and status before sending another.
+Resolve uncertain payments before withdrawing.
+
+## Other payment options and help
+
+The current options are USDC or \$COW on Base, USDC on Ethereum and USDC on BNB.
+\$COW and BNB USDC require an explicit SDK asset entry and Permit2 approval.
+Approval and withdrawal gas is paid in the payment chain's native token.
+\$COW amounts have no guaranteed dollar equivalent.
+
+Use the [live API reference](https://x402.cow.fi/docs/) for payment fields, networks and errors.
+Contact [CoW Protocol Discord](https://discord.com/invite/cowprotocol) with your network, channel ID and transaction hash;
+never share keys or signed payments.
@@ -0,0 +1,114 @@
+---
+title: Paid quotes with x402
+description: Get CoW Protocol quotes using prepaid x402 payments and withdraw unused funds.
+sidebar_position: 4
+---
+
+import CodeBlock from '@theme/CodeBlock'
+import quoteSource from '!!raw-loader!@site/static/code-examples/x402/quote.mts'
+
+# Paid quotes with x402
+
+Get CoW Protocol quotes from a script or agent without an API key. Deposit tokens into a prepaid channel, then authorise each quote with an off-chain signature. The deposit funds future requests; it is not an extra quote fee. The CoW Protocol x402 payment service collects the charges in batches.
+
+The x402 SDK handles the payment challenge, signing, paid retry and receipt validation.
+Your application configures a payer and spending limits, then uses a payment-aware `fetch`.
+
+## Get a quote
+
+This example uses **Node.js 22** and **USDC on Base** to buy an Ethereum quote.
+The payment and quote chains are independent. It returns a quote; it does not execute a swap.
+Browser paid retries are not supported.
+
+### 1. Check the terms
+
+Save <a href="/code-examples/x402/inspect.mjs" download="inspect.mjs">inspect.mjs</a> and run `node inspect.mjs`.
+It shows the current price, minimum deposit and withdrawal delay without a key, signature or payment.
+Fund your wallet with enough Base USDC if you accept the terms.
+
+Deposits remain available for later quotes until spent or withdrawn.
+
+### 2. Set up the example
+
+```bash
+mkdir x402-quickstart
+cd x402-quickstart
+npm init -y
+npm install @x402/fetch@2.26.0 @x402/evm@2.26.0 @x402/core@2.26.0 viem
+npm install --save-dev tsx
+umask 077
+touch .env
+chmod 600 .env
+```
+
+Edit `.env` locally with your payer key and a Base RPC URL:
+
+```text
+PRIVATE_KEY=YOUR_PAYER_PRIVATE_KEY
+RPC_URL=YOUR_BASE_RPC_URL
+```
+
+Keep `.env`, `x402-state/`, `x402-channels/` and `x402-attempts/` out of source control.
+Saved signed attempts are sensitive too.
+
+The runnable example defaults to **0.001 USDC per quote**, **1 USDC per deposit or top-up**, and a **24-hour maximum accepted withdrawal delay**. These are client limits, not guaranteed server terms. If an offer exceeds them, the script stops before signing.
+See [optional limits](./x402-recovery.mdx#client-limits) to change them. A per-deposit limit is not a lifetime spending cap.
+
+### 3. Request a quote
+
+The core SDK setup is below. This is an **excerpt**, not a standalone script:
+the [complete example](./x402-recovery.mdx#complete-quote-example) creates the RPC-backed
+`signer`, selects Base USDC, checks the expected receiver and your limits, and saves recovery files.
+
+<CodeBlock language="typescript" title="SDK setup (excerpt from quote.mts)">
+  {quoteSource.slice(quoteSource.indexOf('const client ='), quoteSource.indexOf('// Sign only')).trim()}
+</CodeBlock>
+
+Once that client is configured, request a quote with `paidFetch`:
+
+```typescript
+const paidFetch = wrapFetchWithPayment(fetch, client);
+const response = await paidFetch("https://x402.cow.fi/mainnet/api/v1/quote", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(quoteRequest), // Standard orderbook quote parameters.
+});
+```
+
+To run it, save <a href="/code-examples/x402/quote.mts" download="quote.mts">quote.mts</a>
+in the project directory. It includes the imports, payment limits and a complete quote request.
+
+```bash
+node --env-file=.env --import tsx quote.mts
+```
+
+A successful run prints `status: 200`, `quoteReceived: true`, the charge, a saved channel-file path and the quote JSON.
+The first request funds the channel; later requests reuse it and top up when needed, within your limits.
+The CoW Protocol x402 payment service pays deposit and collection gas.
+
+Run one request at a time per channel and keep the saved files across restarts.
+
+If a request times out or returns a settlement error, keep the saved files and transaction hash.
+A charge or deposit may have succeeded even without a quote response.
+Follow the [recovery guidance](./x402-recovery.mdx#recover-an-uncertain-payment) before retrying.
+
+## Withdraw unused funds
+
+You initiate a withdrawal, wait for the saved channel's deadline, then finalize it.
+These are **two transactions**, paid by your wallet in Base ETH for this example.
+Finalization returns tokens to the payer; it is not automatic.
+
+Follow the [withdrawal walkthrough](./x402-recovery.mdx#withdraw-unused-funds) using
+the original channel-file path printed by the quote example.
+Claims during the waiting period can reduce the amount returned.
+
+## Other payment options and help
+
+The current options are USDC or \$COW on Base, USDC on Ethereum and USDC on BNB.
+\$COW and BNB USDC require an explicit SDK asset entry and Permit2 approval.
+Approval and withdrawal gas is paid in the payment chain's native token.
+\$COW amounts have no guaranteed dollar equivalent.
+
+Use the [live API reference](https://x402.cow.fi/docs/) for payment fields, networks and errors.
+Contact [CoW Protocol Discord](https://discord.com/invite/cowprotocol) with your network, channel ID and transaction hash;
+never share keys or signed payments.
@@ -44,6 +44,7 @@
     "docusaurus-plugin-typedoc": "^0.21.0",
     "dotenv": "^16.3.1",
     "prettier": "^3.0.3",
+    "raw-loader": "4.0.2",
     "typedoc": "^0.25.3",
     "typedoc-plugin-markdown": "^3.17.0",
     "typescript": "~5.2.2"

@@ -0,0 +1,26 @@
+// inspect.mjs — read-only; no private key, SDK, signature or payment.
+const response = await fetch("https://x402.cow.fi/mainnet/api/v1/quote", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: "{}",
+});
+const header = response.headers.get("PAYMENT-REQUIRED");
+if (response.status !== 402 || !header) throw new Error("No payment challenge received");
+const challenge = JSON.parse(Buffer.from(header, "base64").toString("utf8"));
+const option = challenge.accepts.find(r =>
+  r.scheme === "batch-settlement" && r.network === "eip155:8453" &&
+  r.asset.toLowerCase() === "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
+);
+if (!option) throw new Error("Base USDC is not currently offered");
+function usdc(atomic) {
+  if (typeof atomic !== "string" || !/^\d+$/.test(atomic)) throw new Error("Invalid amount");
+  const digits = BigInt(atomic).toString().padStart(7, "0");
+  return (digits.slice(0, -6) + "." + digits.slice(-6)).replace(/\.?0+$/, "") + " USDC";
+}
+console.table({
+  payment: "USDC on Base",
+  quotePrice: usdc(option.amount),
+  minimumDepositOrTopUp: usdc(option.extra.minDeposit),
+  newChannelWithdrawalDelay: option.extra.withdrawDelay / 3600 + " hours",
+  depositAuthorizationValidity: option.maxTimeoutSeconds + " seconds",
+});