Discovery · build on open infra · $0, nothing hosted · experimental
Be discoverable. Find anything.
x402 makes an endpoint payable — but not findable. PipRail closes the gap by building on the open x402 indexes that already exist, so any merchant or AI agent gets discovered the moment they gate a route. No registry, no database, no fee — nothing PipRail-hosted.
Payable, but invisible.
The x402 protocol answers one question — “how do I pay for THIS url?” It does not answer “what payable URLs exist?” So a fresh endpoint is a shop with no sign, on a street with no name — and an agent has no phone book to look in.
The seller
adds requirePayment() — now charging, but no one knows the URL exists.
The buyer
an agent with a budget can only pay URLs a human already handed it.
Built on open infra. Nothing hosted.
We don’t run a directory — we plug into the open x402 indexes that already exist, and contribute back. A registry of our own would be a backend forever; that’s the one thing PipRail refuses to become.
402 Index
Primary register · free read
One POST to list yourself — no auth, no signature, no fee. Searchable in seconds, every chain. A superset (it also re-ingests the CDP Bazaar).
CDP Bazaar
Free read source
Coinbase’s catalog. Read it free to find others’ endpoints; listing there is facilitator-settle only, so backendless PipRail merchants get found via 402 Index instead.
x402scan
Secondary register (SIWX)
List with one wallet signature — the strongest ownership-proof model, facilitator-free. Base + Solana only; reads are paid (opt-in).
Every chain, guaranteed. 402 Index needs no signature and
has no chain allowlist — so a built-in preset, any non-EVM family, or a custom { id, rpcUrl }
chain is listed and findable, and discover() never silently hides a chain it can’t resolve.
x402scan is the one Base/Solana-only bonus target.
Exactly how it works — three opt-in moves.
Two moves to be found, one to find. All opt-in; the pay path is byte-identical to before. Each is a couple of lines.
Turn your gate into a crawlable file
- gate.describe() exposes your price, token, chain and payTo as static, nonce-free metadata.
- buildOpenApi / buildWellKnownX402 / buildX402DnsTxt are pure — no network, no chain library.
- Serve the result as a static file on your own origin (/openapi.json). No backend, ever.
import { createPaymentGate, buildOpenApi } from '@piprail/sdk'
const gate = createPaymentGate({
chain: 'base', token: 'USDC',
amount: '0.05', payTo,
})
// gate config → a crawlable discovery file
const doc = buildOpenApi({
origin: 'https://api.acme.com',
resources: [await gate.describe(
'https://api.acme.com/report',
)],
})
// serve doc at /openapi.json — static, no backendList yourself on the open registries
- client.register(url) POSTs to 402 Index by default — no auth, no signature, no payment.
- Add x402scan via SIWX (one wallet signature; Base/Solana) for an ownership-verified listing.
- Returns one outcome per index — a step a chain can’t satisfy is reported, never thrown.
import { PipRailClient } from '@piprail/sdk'
const client = new PipRailClient({ chain: 'base', wallet })
// one POST — no auth, no signature, no fee
await client.register('https://api.acme.com/report', {
name: 'Market Report',
priceUsd: 0.05,
})
// → listed on 402 Index, searchable in secondsFind payable resources to pay
- client.discover() reads the open indexes (free), filtered to your chain by default.
- Each hit carries its rails; feed a chosen resource into the usual quote → plan → pay.
- Never throws — a down or changed index simply contributes nothing.
// find payable APIs on the open indexes
const hits = await client.discover({
query: 'weather',
maxPrice: 0.01,
})
// then the usual quote → plan → pay
const res = await client.fetch(hits[0].resource)The round trip, end to end.
The merchant becomes findable; the agent finds and pays. The index is third-party, but the payment never touches it — value still settles wallet-to-wallet with local verify.
Merchant — be found
- 01
Gate the route
requirePayment() — it’s now payable, but invisible.
- 02
Describe + emit
gate.describe() → buildOpenApi() → serve /openapi.json on your origin.
- 03
Register
client.register(url) → 402 Index (no auth) [+ x402scan SIWX].
- 04
Found
Searchable in seconds. Nothing PipRail-hosted.
Agent — find & pay
- 01
Discover
client.discover({ query }) — candidates from the open indexes.
- 02
Quote
client.quote(resource) — the exact live price.
- 03
Plan
client.planPayment(resource) — can I actually settle it?
- 04
Pay
client.fetch(resource) — merchant-direct, verified locally. No facilitator.
What you actually need — no surprises.
Full transparency on wallets, signing, and sign-ups. There's no PipRail account and no x402 sign-up anywhere — the only thing ever registered is a merchant's own URL, by one call. The fastest path to discoverable (highlighted) needs no wallet, no signature, no account.
| Step | Wallet? | Private key / signing? | Sign-up? | Cost |
|---|---|---|---|---|
| Gate an endpoint | receiving address only | No | No | Free |
| Emit /openapi.json | — | No | No | Free |
| Register · 402 Index (default) | — | No | No | Free |
| Register · x402scan (optional) | your own | 1 SIWX signature · no funds move | No | Free |
| Ownership badge (optional) | your own | sign the origin string | No | Free |
| Discover | — | No | No | Free |
| Quote / plan | — | No | No | Free |
| Pay a discovered API | funded wallet | the payment tx | No | price + gas |
The reliable attribution rides along automatically — your emitted /openapi.json
carries a x-generator: "@piprail/sdk" stamp (opt-out), and index
requests send a PipRail User-Agent. Nothing is hidden, nothing is forced.
Two MCP tools: find and be found.
The PipRail MCP server hands an agent the same discovery the SDK has — budget-bound, local-only.
piprail_discover
Search the open indexes for payable APIs — the phone book. Filtered to the agent’s chain by default.
piprail_register
List an endpoint the agent runs (402 Index, no signature) so other agents discover it.
The honest caveats.
We document the rough edges plainly — discovery is a young, moving layer, so we ship it
experimental. (The read path + 402 Index register are
live-verified; 402 Index only lists endpoints that truly return a 402.)
Scheme
The open indexes assume the mainstream exact scheme. To be usefully listed, also offer a standard exact USDC rail on Base/Solana.
Coverage
x402scan indexes Base + Solana only. 402 Index has no such limit, so it’s the default register target — every chain.
Standard
No single ratified discovery standard yet. OpenAPI-first is an emerging convention — we emit it, never oversell it.
Discovery FAQ.
How does an AI agent discover my x402 endpoint?
Discovery is built into the SDK and backendless — PipRail builds on the open x402 indexes that already exist (402 Index, the CDP Bazaar read API, x402scan) and hosts none of its own. To be found, call client.register(url): one POST to 402 Index, no auth and no signature, searchable in seconds (optionally x402scan via one wallet signature, Base/Solana only). To find resources to pay, an agent calls client.discover({ query }), which reads those open indexes for free and returns candidates it then quotes and pays. No registry, no database, no fee.
Does PipRail run a registry or database for discovery?
No. PipRail hosts nothing — no registry, no database, no backend, no fee. Emitting a discovery file produces a static file you serve on your own origin; registering and discovering are runtime calls to third-party open indexes; and payment still settles wallet-to-wallet with local verification. We consume and contribute to open infrastructure rather than running our own directory, which would turn the tool into a platform you sign up for.
Why don’t my PipRail endpoints appear in the Coinbase Bazaar automatically?
The CDP Bazaar catalogs a resource only when Coinbase’s facilitator settles a payment for it. PipRail is backendless and uses no facilitator — payments settle straight to your wallet, verified against your own RPC — so it never appears in the Bazaar by construction. That’s by design; discoverability for a backendless merchant comes from 402 Index (every chain) and x402scan (Base/Solana). PipRail can still read the Bazaar to help an agent find other people’s endpoints.
Is there a single official x402 discovery standard?
Not yet. The ratified x402 v2 spec defines discovery only as the read-only facilitator Bazaar. The OpenAPI-first convention PipRail emits (x-payment-info per operation) is an emerging multi-vendor convention — it’s what the live indexes parse today and where an early IETF draft points — but it isn’t ratified, so PipRail emits it while treating it as a moving target, never overselling it as “the standard.”
Get found in one line.
Gate a route, then client.register(url) — searchable in seconds, on infra you don’t run.