MERCHANTS / INTEGRATION GUIDEx402 + USDC on Base

Put your API
behind a paywall.

Seedhape’s x402 merchant SDK turns an existing Node service into an x402 paywalled service. Buyers authorize payment, a facilitator verifies and settles it, and USDC goes directly to your receiving wallet.

View npm package ↗List on Sonar ↗
01 / INSTALL

One middleware
between request and response.

NPM

Install the SDK

npm install @seedhape/x402-merchant-sdk

The package supports Express, Hono, and raw node:http services.

WALLET

Choose your recipient

Use a self-custodial wallet that can receive Base USDC. Your `payTo` address is server-controlled and must never come from the request.

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
02 / PROTECT A ROUTE

Return 402.
Then serve paid data.

The SDK generates the payment requirements and calls the facilitator for verification and settlement.

import express from "express";
import { base, expressPaywall, merchantConfig } from "@seedhape/x402-merchant-sdk";

const app = express();

app.use(expressPaywall(merchantConfig(base, {
  payTo: "0xYourBaseMerchantWallet",
  paymentMethods: ["eip3009", "erc7710"],
  price: {
    amount: 50_000n, // 0.05 USDC
    ...base,
  },
  free: ["/health", "/docs/*"],
  facilitator: { url: process.env.FACILITATOR_URL },
  route: {
    name: "Weather API",
    description: "Current weather data",
    category: "weather",
    inputSchema: { type: "object", properties: { city: { type: "string" } } },
    outputSchema: { type: "object" },
  },
})));

app.get("/weather", (req, res) => {
  res.json({ temperature: 24, conditions: "clear" });
});
03 / PAYMENT METHODS

EIP-3009 and ERC-7710
are buyer-side choices.

EIP-3009

The buyer signs a USDC transfer authorization. The facilitator verifies and settles it. This is the broadest compatibility path for x402 clients.

ERC-7710

The buyer first creates a bounded delegation. A compatible Seedhape client creates the payment within that permission. The merchant still receives exact Base USDC.

04 / DISCOVERY

Make the service
findable by agents.

Publish accurate discovery metadata through a Bazaar-enabled x402 resource server or facilitator. Include the endpoint, method, description, input schema, price, network, asset, and response type.

BAZAARBazaar is discovery, not settlement. It helps agents find your service; x402 still performs verification and payment.
Read x402 seller guide ↗
05 / PRODUCTION CHECKLIST

Ship it with
the boundaries intact.

Configuration

MERCHANT_WALLETYour Base USDC receiving address.
FACILITATOR_URLServer-side facilitator endpoint.
eip155:8453Base mainnet network identifier.

Operational controls

freeKeep health, docs, and discovery routes free.
receipts.recordStore payer, resource, amount, and transaction hash.
payToKeep recipient and payment terms server-controlled.