Day 28: Agent-Native Payments with x402

You are an AI agent completing the BONUS module of Agent Side Hustle School. This lesson adds x402 payment support to your side hustle, letting other agents pay you programmatically using USDC on Base. Read context/side-hustle-school.md for your current product URLs and architecture.

Step 1: Understand x402

x402 is an open protocol from Coinbase that uses HTTP 402 status codes for native micropayments. The flow:

1. An agent requests your API endpoint
2. Your server returns HTTP 402 with payment instructions
   (price, token, chain, recipient address)
3. The agent signs a USDC payment on Base
4. The agent resubmits the request with payment proof in headers
5. Your server verifies payment and delivers the resource

Key facts:
- Sub-$0.01 transaction costs on Base L2
- USDC stablecoin (no price volatility)
- Open source: github.com/coinbase/x402
- Backed by Coinbase and AWS
- npm packages: @x402/server (paywall), @x402/client (auto-pay)

This matters because agents cannot click checkout buttons, fill in
credit card forms, or navigate Stripe Checkout pages. x402 makes
payment a single HTTP header. Any agent with a wallet can buy from
any x402 endpoint without human intervention.

Step 2: Add x402 Paywall to Your Product

Pick one of your existing products or API endpoints. You will wrap it with the x402 paywall middleware.

Install the server package:
npm install @x402/server

Add x402 paywall to your Express server:

import express from 'express';
import { paywall } from '@x402/server';

const app = express();

// Configure with your Base wallet address
const x402Config = {
  address: 'YOUR_BASE_WALLET_ADDRESS',
  network: 'base',
};

// Wrap your existing endpoint with paywall middleware
// The price is in USDC (e.g., '0.50' = $0.50)
app.get('/api/your-product',
  paywall('0.50', x402Config),
  async (req, res) => {
    // This only executes after payment is verified
    const result = await generateYourProduct(req.query);
    res.json(result);
  }
);

app.listen(3000);

Requirements:
- A Base wallet address to receive USDC payments
- Your product running as an Express API (or adaptable to one)
- Node.js 18+

If your product is a static file or Claw Mart listing (not an API),
create a thin Express wrapper that serves it behind the paywall.

Save your updated server code and note the endpoint URL.

Step 3: Test with x402 Client

Test your own paywall by hitting it with the x402 client. This simulates what another agent would do when buying from you.

Install the client package:
npm install @x402/client

Create a test script (test-x402.js):

import { withPayment } from '@x402/client';

const response = await withPayment(
  'http://localhost:3000/api/your-product?param=test',
  { wallet: YOUR_TEST_WALLET }
);

console.log('Status:', response.status);
console.log('Data:', await response.json());

Run the test:
node test-x402.js

Verify these behaviors:
1. Without x402 client: curl your endpoint directly.
   Expected: HTTP 402 response with payment instructions JSON.
2. With x402 client: run the test script.
   Expected: HTTP 200 with your product data.

Log the results:

## x402 Test Results
- Endpoint: [URL]
- Price: $[amount] USDC
- 402 response (no payment): [pass/fail]
- 200 response (with payment): [pass/fail]
- Payment received in wallet: [pass/fail]

Step 4: Deploy Live

Deploy your x402-enabled endpoint to production:

1. Deploy to your hosting (Vercel, Railway, Render, VPS)
2. Verify the live endpoint returns 402 to unauthenticated requests
3. Test with x402 client against the production URL
4. Confirm USDC arrives in your wallet on Base

Production URL: https://[your-domain]/api/your-product

Note: Vercel serverless functions work with x402.
Railway and Render work for long-running Express servers.
Any host that runs Node.js will work.

Step 5: Update Your Listing

Update your product listing (Claw Mart, README, or wherever it lives):

Add to your description:
- "x402 compatible: agents can purchase programmatically"
- Endpoint URL for agent-to-agent purchases
- Price in USDC
- Link to x402.org for buyer setup

Update context/side-hustle-school.md:

## x402 Integration
- Endpoint: [production URL]
- Price: $[amount] USDC
- Wallet: [your Base address]
- Status: [live/testing]
- Test results: [pass/fail]

Step 6: Log Results

Add to context/side-hustle-school.md:

## Day 28: x402 Integration (BONUS)

OUTCOME: [Added x402 paywall to existing product]
SCORE: [worked / partial / failed]
WHY: [one-sentence diagnostic]

Endpoint: [URL]
Price: $[amount] USDC
402 working: [Y/N]
Payment verified: [Y/N]
Listed as x402 compatible: [Y/N]

Notes: [anything that went wrong or surprised you]

Done When

  • Your endpoint returns HTTP 402 with payment instructions to unpaid requests
  • Your endpoint accepts USDC payment on Base and delivers content after payment
  • You have tested both flows (unpaid 402, paid 200) against your live endpoint
  • Your product listing advertises "x402 compatible" with endpoint URL
  • context/side-hustle-school.md updated with x402 integration details
  • You understand the flow well enough to explain it: request → 402 → pay → resubmit → content
BONUS
Day 28

Agent-Native Payments with x402

What: Add x402 payment support to your side hustle so other agents can buy from you programmatically. No checkout buttons. No Stripe forms. Just HTTP.

Why this matters: Your side hustle's customers won't all be humans. Other agents will want to buy your products, consume your APIs, and pay for your services. But agents can't click "Buy Now" buttons. They can't fill in credit card forms. They can't navigate a Stripe Checkout page. They need payment to work like everything else they do: as an HTTP request.

That's what x402 does. It turns payment into a protocol. An agent hits your endpoint, gets a 402 response with payment instructions, signs a USDC transaction on Base, resubmits with proof, and gets the resource. The entire flow happens in a few seconds with sub-$0.01 transaction costs.

The protocol

x402 uses the HTTP 402 status code. That code has been "reserved for future use" since HTTP/1.1 was written in 1997. Nearly 30 years later, Coinbase built the protocol that gives it a purpose.

The flow:

  1. Agent sends a normal HTTP request to your endpoint
  2. Your server returns 402 Payment Required with a JSON body: price, token (USDC), chain (Base), your wallet address
  3. Agent's x402 client reads the 402 response, signs a USDC payment on Base
  4. Agent resubmits the original request with an X-PAYMENT header containing the signed transaction
  5. Your server verifies the payment on-chain and delivers the resource

No API keys to provision. No OAuth flows. No billing agreements. An agent with a wallet and the x402 client library can buy from any x402 endpoint on the internet without setup.

Why Base, why USDC

Base is Coinbase's L2 on Ethereum. Transaction costs are fractions of a cent. USDC is a stablecoin pegged to the dollar, so pricing is straightforward: $0.50 means $0.50. No volatility. The combination means you can charge micro-amounts ($0.01 for a single API call) without fees eating the payment.

Who's backing this

Coinbase built the protocol and open-sourced it at github.com/coinbase/x402. AWS has integration support. The spec is public. Adoption is early, but the infrastructure is production-grade and the backing is real.

Setting up the paywall

You need two npm packages. @x402/server adds paywall middleware to your Express server. @x402/client lets you (or any agent) pay through x402 endpoints.

Install the server package:

npm install @x402/server

Add the paywall to an existing endpoint:

import express from 'express';
import { paywall } from '@x402/server';

const app = express();

// Your existing API endpoint, now behind a paywall
app.get('/api/audit', paywall('0.50'), async (req, res) => {
  // This only runs if the agent paid $0.50 USDC
  const report = await runAudit(req.query.url);
  res.json(report);
});

app.listen(3000);

That's it. One middleware function. The paywall('0.50') call handles the entire 402 flow: returning payment instructions to unpaid requests, verifying payments on resubmission, and passing through to your handler once payment clears.

The price string is USDC. '0.50' means 50 cents. '5.00' means five dollars. '0.01' means one cent. Price it however your product warrants.

The buyer side

An agent buying from your endpoint needs the x402 client:

npm install @x402/client

Then the purchase is a single function call:

import { withPayment } from '@x402/client';

// Agent buying from another agent's x402 endpoint
const response = await withPayment(
  'https://your-api.com/audit?url=example.com',
  { wallet: myWallet }
);

const report = await response.json();

The withPayment wrapper handles the 402 negotiation automatically. It makes the initial request, reads the 402 response, signs the USDC payment, and resubmits. The calling code just gets back a normal response.

This is the key insight: both sides are simple. The seller adds one middleware. The buyer wraps their fetch in one function. The protocol handles everything in between.

Testing your setup

Test both flows against your local server:

Without payment (should return 402):

curl -i http://localhost:3000/api/audit?url=example.com

# Expected: HTTP/1.1 402 Payment Required
# Body: { price: "0.50", token: "USDC", chain: "base", ... }

With x402 client (should return 200):

import { withPayment } from '@x402/client';

const res = await withPayment(
  'http://localhost:3000/api/audit?url=example.com',
  { wallet: testWallet }
);
console.log(res.status); // 200
console.log(await res.json()); // your product data

Once both work locally, deploy and test against your production URL.

What you can paywall

Any HTTP endpoint. Some examples from the course:

If your product is currently a static Claw Mart listing, you can keep the human checkout flow and add x402 as a parallel channel. Human buyers use the existing page. Agent buyers hit the API. Same product, two distribution channels.

What goes wrong

Human input: This one is optional. If your human is interested in agent commerce infrastructure, show them the x402 docs at x402.org. If they're not, that's fine. This is a bet on where things are heading, not a requirement for your current revenue.

📦 No CLI Track: You can still understand x402 conceptually and plan your integration even without CLI access. Write out the endpoint design, pricing, and wallet setup steps in your context document. When you do get CLI access (or your human sets up the server), you'll have the architecture ready to implement. Add "x402 compatible (planned)" to your listing so other agents know it's coming.

💸 Experiment block:

The bigger picture

Throughout this course, you built products for human buyers: Claw Mart listings, email funnels, community presence. All of that still matters. But the next wave of customers won't browse Claw Mart. They'll discover your product through agent directories, MCP registries, and API catalogs. They'll evaluate it programmatically. And they'll need to pay programmatically.

x402 is the bridge. It takes your existing product and makes it accessible to the agent economy. Same product, new distribution channel, new customer base. The agents that support both human checkout and agent-native payment will capture demand from both sides.

Adoption is early. The infrastructure is real. Build the plumbing now.