quantum402 quantum402 Docs
← Back
Solana-first • Multi-network

Overview

quantum402 is a Solana-first, multi-network x402 facilitator. It issues invoices, routes the fastest chain, verifies off-chain, and returns signed receipts so your backend can authorize work instantly with minimal on-chain latency.

Why x402

  • Pay-per-use access for agents, APIs, and dApps.
  • Offline verification (TTL + nonce + signature).
  • Routing across chains with Solana as the default.

What you get

  • Instant credit decisions and meterable receipts.
  • Browser + Node SDKs with Phantom / MetaMask adapters.
  • Webhooks secured via x-integ-secret.

Quickstart

  1. Install the SDK.
  2. Request an invoice and pay via wallet.
  3. Attach x402-receipt to your API call; verify on the server.
npm
npm i quantum402
browser
import { pay } from "quantum402";

const { receipt } = await pay({
  feature: "api.translate",
  amount: "0.01",
  ttlSec: 90,
  wallet: "phantom" // or "metamask"
});

await fetch("/api/translate", {
  headers: { "x402-receipt": JSON.stringify(receipt) }
});
server (Node)
import { verifyReceipt } from "quantum402/server";

app.post("/api/translate", async (req,res) => {
  const raw = req.headers["x402-receipt"];
  const rcpt = JSON.parse(raw || "{}");
  const ok  = await verifyReceipt(rcpt);
  if(!ok) return res.status(402).json({ error: "payment required" });
  res.json({ ok:true });
});

Tip: keep a short-lived store of used nonces to prevent replay within the TTL window.

Architecture

Flow

  1. Client requests invoice → gateway returns amount, ttl, nonce.
  2. Wallet signs/transfers on the chosen chain.
  3. Gateway issues a signed receipt (credit proof).
  4. Client calls your API with x402-receipt; server verifies.

Key data

ttl
Expiry window for anti-replay.
nonce
Per-call unique value.
sig
Gateway signature over canonical message.
merkleId
Aggregated identifier for receipts batch.

x402 Facilitator

Wallet adapters ship for Phantom (Solana) and MetaMask (EVM). You can swap in a custom signer as long as you can produce the expected transaction or signature.

adapter
import { connect } from "quantum402/wallet";
const { address, chain } = await connect({ wallet: "phantom" });

Automation & AI Operation

Event triggers

  • invoice.created
  • payment.signed
  • receipt.issued
  • webhook.failed

Actions

  • call.webhook with retries
  • emit.event (internal bus)
  • queue.retry (backoff)
  • notify.email
TTL 90sNonce per-callIdempotent yesWebhook x-integ-secret

Settlement & Receipts

Receipt

receipt.json
{
  "feature": "api.translate",
  "amount": "0.01",
  "unit": "SOL",
  "ttl": 90,
  "nonce": "7f62b0e1…a9c1",
  "merkleId": "0x9d8b…ff21",
  "payer": "Fv3…QpN",
  "sig": "3Kq…TtW",
  "gatewayPubkey": "GWy…7dL",
  "ts": 1730616273
}

Verify

node
import { verifySig, isFresh, seen } from "quantum402/server-utils";
export async function verifyReceipt(rcpt){
  if(!isFresh(rcpt.ts, rcpt.ttl)) return { ok:false, err:"expired" };
  if(await seen(rcpt.nonce))      return { ok:false, err:"replay" };
  const msg = [rcpt.feature, rcpt.amount, rcpt.unit, rcpt.nonce, rcpt.merkleId, rcpt.ts].join("|");
  const ok  = await verifySig(msg, rcpt.sig, rcpt.gatewayPubkey);
  return ok ? { ok:true } : { ok:false, err:"bad-sig" };
}

Operational advice: persist receipts, index nonce, and run reconciliation for late settlements.

Developer SDKs

Install

npm
npm i quantum402

Minimal client

browser
import { pay } from "quantum402";
const { receipt } = await pay({ feature:"api.translate", amount:"0.01", wallet:"phantom" });

HTTP API Reference

POST /api/x402/invoice

Request

{
  "feature": "api.translate","amount": "0.01","unit":"SOL","wallet":"phantom"
}

Response

{
  "amount":"0.01","ttl":90,"nonce":"7f62b0e1…a9c1","gateway":"solana-main","receipt":{ "...": "..." }
}

POST /api/x402/verify

{ "ok": true, "reason": null }

Security

  • TTL & Nonce: reject expired or repeated receipts.
  • Signature: verify the gateway signature.
  • Webhooks: require x-integ-secret + timestamped HMACs.
  • Sandbox separation: never mix keys between stages.

Key rotation: publish a JWKS or key index; include it in receipts so verifiers can fetch the current pubkey bundle.

FAQ

Is Solana mandatory?

No—default is Solana, but EVM works via MetaMask.

How fast is the decision?

Sub-second for invoice → receipt, excluding wallet UI time.

Can I verify receipts offline?

Yes. TTL + nonce + signature enable offline authorization.