​
Accountless x402

PubFi supports accountless x402 payment on explicitly enabled Registry v2 gateway routes. The caller uses a wallet authorization instead of creating a PubFi account or API key.

​
Current Availability

The current public Registry exposes this ready example:
The application endpoint is Production, but its x402 rail is Base Sepolia testnet: PubFi does not currently publish a Base mainnet x402 route. Always inspect the live challenge before signing because route terms can change through a new reviewed offer.

​
1. Request The Resource Without Auth

An eligible unpaid request returns:
  • HTTP 402 Payment Required;
  • a PAYMENT-REQUIRED header;
  • the same payment requirements in the JSON response; and
  • Cache-Control: private, no-store.
The payment requirement contains the exact resource URL, amount, asset, network, payee, scheme, transfer method, and authorization timeout.

​
2. Validate Before Signing

Use an x402 V2 client and reject the challenge unless every field matches your wallet policy. At minimum, validate:
  • the exact HTTPS resource;
  • x402 version 2 and scheme exact;
  • Base Sepolia network eip155:84532;
  • canonical Base Sepolia USDC;
  • EIP-3009;
  • the expected PubFi payee;
  • the maximum amount you authorize; and
  • the maximum authorization lifetime.
Keep the buyer private key in a secret manager or wallet. Do not place it in a prompt, source file, shell history, log, issue, or CI output.

​
3. Send The Signed Request

The x402 client repeats the exact request with PAYMENT-SIGNATURE. Do not add a PubFi API key to that request. Supplying both payment modes is a conflict and PubFi rejects it. A successful settled response includes PAYMENT-RESPONSE. Treat the full payment signature, payment payload, and payment response as sensitive payment evidence. Do not log them. The challenge also includes the official Signed Offers & Receipts offer-receipt extension. Its offer is a compact Ed25519 JWS. The successful payment response includes the extension’s signed receipt. The JWS kid points to PubFi’s did:web verification method. PubFi uses one active private signer. The did:web document can also publish up to eight retained public verification keys. Only the active key signs new offers and receipts. Retained public keys keep supported historical receipts verifiable after key rotation.

​
4. Replay Safely

If a connection is lost after signing, resend the exact same request with the exact same PAYMENT-SIGNATURE. Do not create a second authorization first. After settlement, exact replay returns the same bounded response bytes and the same PAYMENT-RESPONSE, including the same signed receipt. A changed method, path, query, body, route, or payment binding is rejected.

​
Verify The Offer And Receipt

Use a JWS and DID library that supports EdDSA and did:web.
  1. Read the offer JWS from PaymentRequired.extensions["offer-receipt"].info.offers.
  2. Require JWS algorithm EdDSA and resolve the exact kid through its did:web document.
  3. Require the DID document to authorize that Ed25519 verification method for assertions.
  4. Require the decoded payload bytes to match the JSON Canonicalization Scheme form, then verify the compact JWS.
  5. Check the signed offer fields against the live payment requirement: version, resource URL, scheme, network, asset, payee, amount, and expiry.
  6. After settlement, read and verify SettlementResponse.extensions["offer-receipt"].info.receipt in the same way.
  7. Check the signed receipt’s version, network, resource URL, payer, issuedAt, and optional transaction. Require an exact replay to return the same receipt.
The official receipt has a deliberately narrow payload. It does not by itself sign the amount, asset, payee, request body, response body, route identity, or every internal settlement id. Use the verified offer and settlement response as the public payment evidence. PubFi and Quantro retain the request, route, stage, claim, settlement, and internal receipt bindings. issuedAt comes from Quantro’s durable settledAt settlement time. It is the receipt issuance time, not the earlier provider execution stage time. Exact replay reuses the durable receipt instead of creating a new issuance time. For operators, PUBFI_X402_OFFER_RECEIPT_VERIFYING_KEYS_JSON is nonsecret configuration. It can contain only retained public verification keys. It must not contain a private key. The active private signing key stays in the separate secret configuration.

​
Billing Expectations

The x402 lane:
  • creates no PubFi account;
  • creates no API key;
  • creates no Credits balance;
  • creates no invoice or anonymous billing dashboard; and
  • does not consume a registered account’s allowance.
Signed receipts provide portable evidence. They do not create an account, a balance, or a wallet history service. SIWX and wallet-history lookup are not part of the current release. The wallet balance remains visible through the wallet or Base Sepolia explorer. See Payment And Execution Modes for the boundary between x402, registered purchases, Credits, and API-key execution.

​
No-Payment Inspection Example

The public repository contains a no-secret script that displays the current challenge without signing or spending test USDC:
The same accountless payment mode is available to agents through MCP pubfi.route.execute. See MCP Client Setup for the official MCP metadata flow.

​
Remote Paid Smoke Limits

The deployment smoke creates two independent payments for the selected route: one through HTTP and one through MCP. Each payment can spend at most 0.01 test USDC. The total maximum is 0.02 test USDC. The MCP replay check compares the returned structuredContent and result._meta["x402/payment-response"]. It does not compare raw JSON-RPC response bytes.