feat: add x402 payment protocol example for pay-per-circuit quantum access

[plagtech]

Summary

Adds a Jupyter notebook demonstrating the x402 HTTP payment protocol for quantum computing — showing how APIs like IonQ's can offer pay-per-circuit access via stablecoin micropayments, and how AI agents can consume quantum resources autonomously.

What is x402?

x402 is an open protocol (originated at Coinbase) that implements the HTTP 402 Payment Required status code with USDC stablecoin settlement. It allows any API to gate endpoints behind micropayments without requiring user accounts or subscription billing. The reference implementation is open source.

Quantum computing is a natural fit — per-shot pricing maps directly to per-request micropayments, and the protocol enables AI agents to autonomously purchase compute without human billing management.

What's included

• x402_quantum_payments.ipynb — Covers:
  • How the x402 protocol flow works (discovery → quote → payment → result)
  • Submitting Bell State and GHZ circuits through an x402 gateway
  • Qiskit circuit conversion for x402 submission
  • Server-side implementation pattern for adding x402 to any quantum API
  • Links to the open protocol spec, Coinbase reference implementation, and a hosted gateway

How it fits

Follows the same structure as existing notebooks (qiskit.ipynb, cirq.ipynb, etc.) — a self-contained, runnable example. The gateway URL is configurable via environment variable, so users can point to any x402-compatible gateway or self-host one.

Testing

• All cells designed to work with IONQ_API_KEY environment variable
• Gateway calls return structured JSON responses (402 quote or 200 result)
• Compatible with the repo's pytest tests/ notebook runner

[TateLyman]

Did a no-payment documentation pass on the notebook. I did not call IonQ, gateway.spraay.app, send payment headers, use an API key, sign a wallet request, or broadcast a transaction.

This is a useful direction, but I would tighten a few protocol/documentation details before merging into official samples:

• P1: the notebook presents X-PAYMENT: x402-usdc-base / X-PAYMENT-NETWORK: base as if those are sufficient payment headers. In current x402 flows, the first unauthenticated request should receive a 402 challenge with the exact accepted requirement, and the retry should include a signed payment payload/proof, not only a symbolic willingness-to-pay string. I would label the current headers as pseudocode or replace with a real client-library flow.
• P1: https://gateway.spraay.app is used as the default hosted gateway, but the notebook does not establish whether this is an IonQ-controlled, endorsed, or example-only gateway. For an official IonQ sample, either make it an explicit placeholder (YOUR_X402_GATEWAY_URL) or document the trust boundary: what the gateway can see, who operates it, and whether it is suitable for real IonQ API keys.
• P2: the manifest path is shown as /.well-known/x402-manifest. Many current services use /.well-known/x402 and/or /.well-known/x402.json. If this notebook is teaching a specific gateway convention, call that out; otherwise include the common discovery aliases.
• P2: the example combines an upstream IONQ_API_KEY with an x402 gateway. That is fine for a provider-operated gateway, but if a third-party gateway is in the path the sample should warn not to send real IonQ API keys through it unless the operator is trusted and contractually authorized.
• P2: add a no-payment smoke-test cell that verifies the expected 402 challenge shape before any signing step: amount, asset, network, payTo, resource, expiry, and cache/CORS headers. That gives users a safe way to validate the gateway before money moves.

The safest structure is: public discovery check -> unpaid 402 challenge inspection -> explicit user/wallet approval -> signed payment retry -> IonQ job submission. That keeps the quantum API key and payment authorization boundaries clear.

[plagtech]

@TateLyman — really appreciate the thorough review. All points addressed in the updated notebook:

P1 — Payment headers as pseudocode:
Completely restructured. The flow now follows the pattern you described: unpaid request → 402 challenge inspection → wallet signing (clearly marked as pseudocode) → paid retry with X-PAYMENT-PROOF. The old "willingness-to-pay" headers are gone — the initial request is now sent bare, and the signed proof is a separate explicit step.

P1 — Gateway trust boundary:
Default URL is now YOUR_X402_GATEWAY_URL (placeholder). Added a dedicated "Gateway trust boundary" section at the top documenting what a gateway can see (terminates TLS, reads headers including API keys), the three deployment options (self-host, provider-operated, third-party), and an explicit warning not to send real IonQ API keys through untrusted third-party gateways.

P2 — Discovery paths:
Now probes all three common well-known paths (/.well-known/x402, /.well-known/x402.json, /.well-known/x402-manifest) and notes which convention each follows. Returns whichever responds first.

P2 — API key trust warning:
The submit_circuit_x402 function documents the trust implication in its docstring, and the API key is commented out by default in the example call — user must explicitly uncomment it and has to have read the trust section first.

P2 — Smoke test cell:
Added Step 2 as a dedicated 402 challenge inspection cell. It sends an unpaid request (no API key, no payment), parses the challenge body, validates expected fields (amount/price, asset/currency, network, payTo, resource, expiry), and inspects response headers (Cache-Control, CORS). Gives users a safe way to validate the gateway before any money moves.

Overall structure now follows:
public discovery → unpaid 402 challenge inspection → circuit build → explicit wallet approval (pseudocode) → signed payment retry → job submission

The Spraay gateway reference is now limited to one bullet in the client library table — the notebook is gateway-agnostic by default.

[TateLyman]

Thanks for the detailed update. I re-read the current notebook head after a66e17d and the main trust/payment-flow issues from my pass look addressed.

Quick no-payment doc verification:

• The old symbolic X-PAYMENT: x402-usdc-base / X-PAYMENT-NETWORK flow is gone.
• Default gateway config is now YOUR_X402_GATEWAY_URL, with a clear gateway trust-boundary warning before API keys enter the path.
• Discovery now covers /.well-known/x402, /.well-known/x402.json, and /.well-known/x402-manifest.
• The payment section separates unpaid 402 inspection from wallet signing and paid retry, and marks the signing step as pseudocode.
• The smoke-test guidance now checks challenge fields and response headers before money moves.

No further blocker from my earlier notes. I still did not call a gateway, use an IonQ key, send payment headers, sign, or broadcast a transaction.