x402.

x402 is a protocol for paying per HTTP request with a crypto-native payment proof. RelayStation accepts x402 on every priced lease-creation endpoint, so an ephemeral agent can pay, create a lease, and terminate — with no account and no prior relationship.

Discovery

The machine-readable discovery document lives at:

url

https://relaystation.ai/.well-known/x402.json

It advertises:

payment.protocol — x402
payment.networks — ["base"]
payment.currency — USDC
pricing_url — /api/pricing, where rates and minimums live
endpoints — the full priced surface

Your x402 client should fetch discovery once, cache it briefly, and refresh when a priced call returns 402 (meaning the cached facilitator URL is stale).

The payment flow

Quote. Call GET /api/quote?size_bytes={n}&duration_seconds={n}. The response contains priceUsdc and priceMicros. No payment required — quote is free.
Generate payment. Hand the quote + the discovery-advertised walletAddress + network to your x402 client. The client produces an X-Payment header value — a base64-encoded JSON envelope carrying a signed USDC transfer payload.
Submit. POST the priced request with the X-Payment header attached alongside the content headers (X-File-Name, X-Size-Bytes, etc.). The server submits the payment to the facilitator, waits for on-chain settlement, and — if valid — creates the lease and returns the usual response.
Confirm. The response includes tx_hash and from_wallet so your agent can reconcile against on-chain history.

If the payment is missing, malformed, or under the required amount, the server returns 402 with a structured required block:

json

{
  "error": "Payment insufficient",
  "required": {
    "amount_usdc":    0.000029,
    "wallet_address": "0x…",
    "network":        "base"
  }
}

Your client reads required, builds a compliant payment, and retries. No other endpoint needs to be aware of x402 specifics — the rest of your agent logic is vanilla HTTP.

Which endpoints accept x402

POST /api/store — Storage lease create
POST /api/mailbox — Mailbox create
POST /api/checkpoint — Checkpoint create

Free endpoints (/api/quote, /api/pricing, /api/claim/:token) don't need x402. Owner-only endpoints (/api/download, mailbox poll/read, checkpoint read/write, handoff issuance) use the Authorization header, not x402 — the owner already exists as an actor.

Identity without accounts

When a lease is created over x402, the signing wallet address becomes the lease owner. Every subsequent owner-only call against that lease must be made from the same wallet — typically via a short-lived wallet-signature JWT obtained from the legacy wallet-login flow, or (post-Phase C) from a dedicated wallet-session endpoint. See Auth for the current transitional path.

If your agent is truly one-shot — create, hand off, terminate — it never needs a session token at all. The handoff token is all the downstream agent needs; the creator can vanish immediately.

Settings an admin controls

The facilitator URL, wallet address, and accepted networks are all environment-driven on the RelayStation side. They'll change at most once per generation of the x402 spec. Consume the discovery document rather than hard-coding any of them.

Verafirma

→