clawpay-x402 — JavaScript SDK

ClawPay × x402 client + server SDK for the clawpay-cny / clawpay-dcep / clawpay-cross schemes. Implements the x402 HTTP 402 protocol with China-localized settlement.

Spec: https://erc8004.cn/specs/clawpay-x402/ · License: CC0 · ESM only · Zero deps

Install

npm i clawpay-x402
# or pnpm add / yarn add / bun add

Client — pay an x402 endpoint in 3 lines

import { x402Pay } from "clawpay-x402/client";

const r = await x402Pay("https://erc8004.cn/api/x402/demo", { from: "clawpay:my-agent" });
console.log(r.body, r.receipt);

What x402Pay does (per spec):

1. GET the URL.
2. If 200, returns the body (no payment needed).
3. If 402, parses accepts[], picks the first scheme matching prefer (default order: clawpay-cny → clawpay-dcep → clawpay-cross → exact), builds a PaymentPayload, base64-encodes it as X-PAYMENT, retries.
4. Returns { status, body, paid, paymentRequirements, receipt, response }.

Real settlement integration — pass onBuildPayload to inject a real transactionId from your payment processor:

const r = await x402Pay(url, {
  from: "clawpay:user_42",
  onBuildPayload: async (req) => {
    // call WeChat Pay / Alipay / DCEP API → get a real txn id
    const txn = await wechatPay.charge({ amount: req.maxAmountRequired, payee: req.payTo });
    return { transactionId: txn.id, rail: "wechat" };
  },
});

For the exact (USDC on Base) scheme, this SDK throws — use Coinbase's official x402 SDK or filter exact out via prefer.

Server — protect any endpoint in 1 line (express/connect/node http)

import express from "express";
import { x402Protect } from "clawpay-x402/server";

const app = express();
app.get("/api/translate",
  x402Protect({
    accepts: [
      { scheme: "clawpay-cny", network: "clawpay-mainnet",
        maxAmountRequired: "150", asset: "CNY", payTo: "agent:31981",
        extra: { facilitator: "https://erc8004.cn/api/x402/facilitator", humanPrice: "¥1.50" } },
    ],
    verify: async (payload, req) => {
      // call ClawPay facilitator /verify, or your own WeChat receipt lookup
      return await myFacilitator.verify(payload);
    },
  }),
  (req, res) => res.json({ output: "Hello, world", paidWith: req.x402.payload.scheme })
);

The middleware:

• emits 402 + accepts[] when no X-PAYMENT header present
• decodes & shape-validates the header (rejects malformed, wrong scheme, under-amount, stale signedAt)
• calls your verify hook for real settlement check
• on success, sets X-PAYMENT-RESPONSE (base64 receipt) and calls next()
• attaches req.x402 = { payload, paymentRequirements }

For framework-agnostic use, the lower-level building blocks are exported too:

import { build402Body, decodePayment, verifyShape, encodeReceipt } from "clawpay-x402/server";

See examples/server.mjs for a vanilla node:http integration.

Test

node --test test/                    # unit tests (no network)
LIVE=1 node --test test/live.test.js # hits the real erc8004.cn demo

What this SDK is and isn't

| ✅ | ❌ | |---|---| | HTTP layer: 402 ↔ X-PAYMENT ↔ X-PAYMENT-RESPONSE | Real WeChat/Alipay/DCEP settlement (call your processor) | | Shape & freshness validation | Real fraud check (delegate to facilitator) | | Spec-compliant PaymentPayload encoding | On-chain USDC signing (use Coinbase x402 SDK) | | Client + server in one tiny ESM package | Crypto custody (illegal for CN domestic entities anyway) |

Why CC0?

We want this scheme adopted, not licensed. Fork it, rebrand it, productize it. Tag us if you ship.