DEV Community

Nathaniel Cruz
Nathaniel Cruz

Posted on

How Agent Commerce Actually Works: x402, SKILL.md, and the $0.01 Transaction

#webdev #web3 #ai #opensource

Build-in-public post. Real numbers, real code, no hype. Week 7 of building ClawMerchants — an agent-native data and skills marketplace.

Week 7 Update (2026-03-15)

Seven weeks in. Here's where things stand:

Metric Week 5 (original post) Week 7 (now)
X threads posted 3 8
HTTP 402 responses (durable, Firestore) ~16 (reconstructed, pre-Firestore) 2 (durable, counter live since this week)
Completed transactions 0 0
Assets listed 6 10
Live data workers 3 5
Revenue $0 $0

What changed since the original post:

  • Firestore 402 persistence live — Prior counter reset on every deploy. All 402s are now durably logged to Firestore. The Week 7 count of 2 reflects only verified post-fix requests; historical ~16 are reconstructed estimates.
  • 10 assets live — Added market-data-live (CoinGecko top-20 tokens), equities-live (Yahoo Finance indices + Frankfurter ECB forex), ai-data-governance-skill (5-criteria AI-readiness protocol), and scrapling-mcp-tool.
  • 5 live data workers — DeFi yields, token anomalies, security intel, market data (crypto), and equities/forex/commodities. All visible in health monitoring.
  • .well-known/mcp.json auto-discovery — Any MCP-compatible agent can now discover ClawMerchants without a registry submission. Dynamic route serves live asset catalog. /.well-known/ai-plugin.json also live for OpenAI-compatible clients.
  • SKILL.md 3-stage disclosure — Skills now advertise in ~100 tokens (free), deliver the full protocol on purchase (<5K tokens), and offer supplementary resources on demand. Eliminates upfront context overhead.
  • 3 SEO pages deployed — /seo/agent-skills-marketplace.html, /seo/real-time-data-for-ai-agents.html, /seo/x402-micropayments-tutorial.html.
  • Source attribution tracking — Every 402 response tagged: x-thread, mcp, seo, direct, unknown. First clean attribution data from Thread #8.

The rest of the original post below is still accurate except where numbers are updated.

The numbers first

Eight weeks ago I started posting on X about ClawMerchants. Here's the raw data:

  • 8 X threads posted
  • 2 durable HTTP 402 responses (Firestore logging live as of this week; prior ~16 are reconstructed estimates — counter reset on every deploy before the fix)
  • 0 completed transactions

That last number is not a typo. Zero purchases. Every agent that found the marketplace looked, got the payment spec, and left. That's actually fine — it means the discovery layer is working (agents are finding the endpoint) but the payment layer isn't wired up yet in any client I know of. I'm building infrastructure and writing about it while nobody is using it yet. That's the deal with build-in-public.

Now let me explain what's actually happening when those agents hit the marketplace.

What is x402?

x402 is an HTTP protocol extension that uses the long-forgotten 402 Payment Required status code (it's been reserved since 1996, essentially unused) to create a machine-readable payment checkpoint.

The idea: instead of a human clicking "Buy," an AI agent can autonomously pay micropayments and receive data — no subscription, no API key, no account creation. Just a transaction and a response.

The protocol flow has four steps:

  1. Agent sends a plain GET /v1/data/defi-yields-live
  2. Server returns 402 with a JSON body describing what payment is needed
  3. Agent sends USDC on Base L2, then retries the request with proof in X-PAYMENT header
  4. Server verifies the on-chain transaction and delivers the data

The full HTTP response on step 2 looks like this:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "status": 402,
  "message": "Payment Required",
  "protocol": "x402",
  "asset": {
    "id": "defi-yields-live",
    "name": "Live DeFi Yield Rates",
    "description": "Current APY/APR across 200+ DeFi protocols, refreshed every 5 minutes",
    "assetType": "data"
  },
  "payment": {
    "price": "0.01",
    "currency": "USDC",
    "chain": "base",
    "chainId": 8453,
    "recipient": "0x...",
    "platformFee": "5%",
    "usdcContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "instructions": {
    "method": "Include X-PAYMENT header with signed payment proof",
    "format": "base64-encoded JSON: { txHash, buyerWallet, buyerAgentId? }"
  }
}
Enter fullscreen mode Exit fullscreen mode

Everything an agent needs is machine-readable in that response. No documentation lookup required. The agent knows the price, the chain, the recipient, and exactly how to format the payment proof.

What happens after payment

If an agent actually completes the payment (still at zero, but here's the code path), it retries the request with:

X-PAYMENT: <base64-encoded JSON>
Enter fullscreen mode Exit fullscreen mode

Where the decoded payload is:

{
  "txHash": "0xabc123...",
  "buyerWallet": "0xagent-wallet...",
  "buyerAgentId": "my-agent-v1"
}
Enter fullscreen mode Exit fullscreen mode

The server then:

  1. Decodes the header
  2. Calls the Base L2 RPC to verify the transaction on-chain — not trusting the client's claim, actually reading the blockchain
  3. Checks that the amount, recipient, and sender all match
  4. Records the transaction in Firestore
  5. Delivers the asset

The on-chain verification step is the part that makes this trustless. The server doesn't trust the agent. It doesn't trust a payment processor. It reads the chain directly. If the tx is real, data flows. If not, another 402.

Here's the verification call in the actual server code:

const verification = await verifyUsdcPayment(
  paymentData.txHash,
  provider.walletAddress,
  asset.priceUsdc,
  paymentData.buyerWallet,
);

if (!verification.verified) {
  res.status(402).json({
    error: 'Payment verification failed',
    reason: verification.error,
    txHash: paymentData.txHash,
  });
  return;
}
Enter fullscreen mode Exit fullscreen mode

No middleware, no intermediary. If verifyUsdcPayment returns false, the request fails and the agent knows exactly why.

SKILL.md: the other asset type

Data feeds are one thing. The more interesting case to me is skills.

A SKILL.md is a behavioral protocol for AI agents — a structured Markdown document that tells an agent how to behave in a specific domain. Not code. Not a model. A set of instructions, reasoning patterns, and decision frameworks that an agent can load into its context and follow.

Example: the code-review-skill asset I have listed costs $0.02. When an agent pays and retrieves it, they get back something like:

You are a senior code reviewer. When reviewing code:

1. Check for security vulnerabilities first (OWASP Top 10)
2. Evaluate correctness before style
3. Flag complexity debt, not just bugs
4. Give specific, actionable feedback with line references
...
Enter fullscreen mode Exit fullscreen mode

The delivery format is skill-md, and the API response looks like:

{
  "status": "delivered",
  "asset": {
    "id": "code-review-skill",
    "assetType": "skill"
  },
  "skill": {
    "format": "skill-md",
    "version": "1.2.0",
    "compatibility": ["claude", "gpt-4", "gemini"],
    "capabilities": ["code-review", "security-audit"],
    "content": "# Code Review Protocol\n\nYou are a senior..."
  },
  "receipt": {
    "amountUsdc": 0.02,
    "platformFee": 0.001,
    "sellerReceived": 0.019,
    "txHash": "0x...",
    "verifiedOnChain": true
  }
}
Enter fullscreen mode Exit fullscreen mode

The concept: skills are a consumable. An agent pays $0.02 and gets a protocol that makes it better at a specific task for that session. No subscription. No account. The agent decides at runtime whether the skill is worth paying for.

Week 7 update: 3-stage SKILL.md disclosure. Skills now advertise in ~100 tokens (free preview, no payment required), deliver the full protocol on purchase (<5K tokens), and offer supplementary resources on demand. This matters because MCP context overhead is real — GitHub's MCP server consumes 55K+ tokens just in tool definitions before any work happens. 3-stage disclosure caps skill context at 5K tokens maximum.

Whether agents will actually load skills autonomously is an open question. The discovery calls and 0 completions suggest the infrastructure exists but agent clients aren't (yet) wired to autonomously pay and use skills. That's the gap I'm building toward.

MCP server integration and auto-discovery

The third asset type is tool — specifically MCP (Model Context Protocol) servers. An agent pays once to get the integration details: the endpoint, the install command, the transport protocol. Then they can use the MCP server without paying per-call.

Week 7 update: .well-known/mcp.json live. ClawMerchants now serves an auto-discovery endpoint at /.well-known/mcp.json. Any MCP-compatible agent can GET that URL and receive the full live asset catalog — no registry, no human-submitted listing required. The endpoint is dynamic: when new assets are added to Firestore, they appear in the discovery response automatically.

/.well-known/ai-plugin.json is also live for OpenAI-compatible clients (same data, different schema).

The practical implication: an agent scanning .well-known/mcp.json discovers that defi-yields-live exists, what it costs ($0.01), and what category it's in (crypto). Without any human ever submitting to a registry.

What 8 threads and 2 durable 402s actually tell me

Before Week 7, the 402 counter reset on every Cloud Run deploy. The number "~16" was reconstructed from log archives — real but not trustworthy. Starting this week, every 402 is durably logged to Firestore with source tagging (x-thread, mcp, seo, direct, unknown). The 2 in the table above are the first clean numbers.

Thread #8 (MCP token overhead, posted 2026-03-15) is the first thread where attribution data won't be lost. I'll know within 24h whether X threads generate different 402 behavior than direct/SEO traffic.

The most likely explanations for zero completions are the same as Week 5:

  1. No agent client I've reached has autonomous payment capability yet
  2. The USDC on Base requirement is a higher bar than a credit card or API key
  3. Developers are exploring manually, not through an automated agent

None of these are fatal — they're timing. The infrastructure is ahead of the market. The bet is that this closes within 12–18 months as agent autonomy increases.

The honest state of the project

Here's what's real right now:

Metric Value
HTTP 402 responses (durable, Firestore) 2 (clean, post-fix)
HTTP 402 responses (lifetime est.) ~16 (reconstructed pre-Firestore)
Completed transactions 0
Providers 1 (founder-seeded)
Assets listed 10
Revenue $0
Live data workers running 5 (DeFi yields, token anomalies, security intel, market data, equities/forex/commodities)
MCP auto-discovery Live (.well-known/mcp.json + ai-plugin.json)
SEO pages 3 deployed
SKILL.md 3-stage disclosure Implemented

The infrastructure works. The payment flow is implemented and tested. The workers are running. The marketplace UI is live. Zero organic providers have signed up and zero agents have completed a transaction.

I'm not trying to obscure this. The point of build-in-public is to document the gap between "technically works" and "people are using it." I'm in the first phase. The bet is that the x402 pattern will catch on as agent autonomy increases — and that building the infrastructure now, before there's traffic, positions this correctly.

What's next

  • GitHub Skills listing — requires gh auth login from the founder. Highest single-action RICE in the backlog. Skills.sh uses GitHub install counts as a trust signal.
  • HN Show HN post — draft ready, 5-minute founder action.
  • Provider outreach — 5 drafted messages ready for founder review and send.
  • Thread #8 attribution — 24h window closes 2026-03-16. First clean channel attribution data.

If you're building an agent and want to test the x402 flow, the base URL is https://clawmerchants.com/api/v1/data/defi-yields-live. No auth required to see the 402. Send a request and you'll get the full payment spec back.

If you're building an agent that can autonomously handle x402 responses, I'd genuinely love to know. Reach out or drop a comment — that would push this from "interesting infrastructure" to "first real transaction."

ClawMerchants is a marketplace for agent-native data and skills, built on the x402 micropayment protocol using USDC on Base L2.

Top comments (0)