BLOG

How We Built an Auto-Discovery Crawler for x402 Payment Servers

March 2026 · 6 min read

HTTP 402 ("Payment Required") has been a reserved status code since 1997. For 29 years, it sat unused — a placeholder for "future use." In 2025, x402 gave it a purpose: a standard protocol for API monetization where servers return payment requirements in the 402 response, clients pay on-chain, and access is granted.

The problem: how do you find x402 servers? There's no registry. No DNS record. No well-known directory. Servers just... exist, returning 402 to unpaid requests. We decided to build one.

The Detection Problem

An x402-compatible server can be identified three ways:

1. HTTP 402 Response — the server returns status 402 with
   payment requirements in the response body (JSON with
   paymentRequirements, acceptedAssets, x402Version)

2. /.well-known/x402 — standard discovery endpoint that
   returns supported payment methods without triggering
   a 402 error

3. /supported — sola2a-style discovery that returns
   {kinds: [{x402Version: 2, scheme: "exact", network: "solana:..."}]}

Our crawler tries all three, in order, with 5-second timeouts per check. If any method succeeds, the server is marked as x402-compatible.

Architecture

The entire system runs on a single Cloudflare Worker — no databases, no queues, no infrastructure. Just one JavaScript file.

Community submission ──→ POST /x402/submit ──→ KV (pending)
GitHub scraper (hourly) ──┘                        │
                                          Cron (15 min)
                                                   │
                                    ┌──────────────┴──────────────┐
                                    │  probeX402(url)              │
                                    │  1. GET url → check 402     │
                                    │  2. GET /.well-known/x402   │
                                    │  3. GET /supported           │
                                    └──────────────┬──────────────┘
                                                   │
                              ┌────────────────────┼────────────────────┐
                              │                    │                    │
                         x402 detected        Not x402             Offline
                              │                    │                    │
                    KV (x402:server:*)      KV (not-x402)        KV (offline)
                              │
                    ┌─────────┴─────────┐
                    │                   │
               GET /x402/index    GET /x402/map
               (JSON + HTML)      (force graph)

Certification Levels

Not all x402 servers are equal. We grade them on a 4-level scale:

Level 0 — Offline or not detected
Level 1 — Server responds but no x402 headers found
Level 2 — x402 detected via at least one method
Level 3 — x402 detected + accepted assets listed + network specified

Each verified server gets an embeddable SVG badge:

<a href="https://sola2a.com/x402/index">
  <img src="https://sola2a.com/x402/badge" alt="x402 compatible">
</a>

GitHub Scraping

Every hour, the cron searches GitHub for repos mentioning "x402 payment" and extracts their homepage URLs. If a repo has a live demo or API endpoint, it gets auto-submitted as a candidate for probing.

GitHub API → search repos "x402 payment"
  → extract homepage URLs
  → extract GitHub Pages URLs
  → auto-submit as candidates
  → probed on next 15-min cron cycle

This passive discovery means the index grows without anyone manually registering. If you push x402 code to GitHub, we'll probably find you.

The Ecosystem Map

We built a force-directed graph visualization that shows all discovered servers as an interactive network. Nodes are colored by certification level, sized by uptime, and connected by shared network edges (servers on the same chain cluster together).

You can drag nodes, hover for details, and watch the physics simulation settle into a natural layout. As more servers get discovered, the graph grows organically.

The Self-Fetch Problem

One amusing edge case: sola2a.com is itself an x402 server (it has /supported returning x402 v2 with Solana mainnet + devnet). But a Cloudflare Worker can't reliably fetch() its own domain — the request loops. Our solution: self-register in the cron handler, bypassing the probe entirely.

What We Learned

The x402 ecosystem is tiny. As of March 2026, we've probed ~50 URLs and found exactly 1 verified x402 server (ourselves). But the infrastructure is ready for when the protocol takes off.

Building the crawler was straightforward — the hard part is that x402 is still in early adoption. Most potential x402 servers (RPC providers, AI APIs, data services) haven't implemented the protocol yet. Our index will be more useful in 6-12 months when x402 has wider adoption.

In the meantime, the tools we built serve a dual purpose: they make it trivially easy for new x402 servers to get discovered (just exist and we'll find you), and they provide social proof through certification badges and the ecosystem map.

Try It

Test Your Server Ecosystem Map Server Index

The entire system is open source at github.com/openSVM/ammasm in the sola2a/ directory. One file, zero dependencies, ~4200 lines of JavaScript running on Cloudflare Workers.

Submit your x402 server at sola2a.com or just deploy one — the GitHub scraper will find it.