@armsves/x402

TypeScript SDK for x402 EURD payments on Algorand via Quantoz Pay, with optional AlgoEuPay backend guardrails for wallet-managed spending.

Install

npm install @armsves/x402

Quick start — guarded payments (recommended)

Use the AlgoEuPay backend so the Quantoz API key stays on the server and spend limits apply:

import { withGuardedPayment } from "@armsves/x402";

const fetch = withGuardedPayment(globalThis.fetch, {
  backendUrl: "http://localhost:8080",
  buyerAccount: "YOUR_SEPA_ENABLED_QUANTOZ_ACCOUNT",
});

// Automatically handles HTTP 402 → pay → retry with X-PAYMENT
const res = await fetch("http://localhost:8080/api/v1/x402/scenarios/online-product");
const order = await res.json();

Direct Quantoz API (no guardrails)

import { withEurPayment } from "@armsves/x402";

const fetch = withEurPayment(globalThis.fetch, {
  apiKey: process.env.QUANTOZ_API_KEY!,
  fromAccount: "YOUR_SEPA_ENABLED_QUANTOZ_ACCOUNT",
});

const res = await fetch("https://your-api.example/forecast");

Merchant — create QR payment requests

import { createPaymentRequest, buildX402Challenge, buildEuroAcceptFromPaymentRequest } from "@armsves/x402";

const qr = await createPaymentRequest({
  apiKey: process.env.QUANTOZ_API_KEY!,
  amountEur: 0.20,
  message: "Coffee",
});

const challenge = buildX402Challenge({
  amountEur: 0.20,
  resource: "https://merchant.example/checkout",
  euroAccept: buildEuroAcceptFromPaymentRequest(qr),
});

Verify payments (merchant server)

import { verifyPayment, createX402Middleware } from "@armsves/x402";

const ok = await verifyPayment({
  apiKey: process.env.QUANTOZ_API_KEY!,
  xPayment: request.headers.get("X-PAYMENT")!,
  expectedAmountEur: 0.15,
});

// Express-style helper
app.get("/api/premium", createX402Middleware({ amountEur: 0.15, apiKey: "..." }));

API reference

Buyer

| Export | Description | |--------|-------------| | withEurPayment(fetch, options) | Wrap fetch — auto-pay x402 402 challenges via Quantoz | | withGuardedPayment(fetch, options) | Wrap fetch — pay via AlgoEuPay backend + guardrails | | payViaBackend(url, { buyerAccount, challenge, scenario }) | One-shot backend payment | | fetchGuardrailStatus(url, buyerAccount) | Read spend limits | | checkGuardrails(url, buyerAccount, amountEur) | Pre-flight limit check |

Merchant

| Export | Description | |--------|-------------| | buildX402Challenge(options) | Build HTTP 402 JSON body | | buildAlgorandChallenge(options) | Algorand EURD accept entry | | createPaymentRequest(options) | Quantoz QR / payment request | | verifyPayment(options) | Validate X-PAYMENT header | | createX402Middleware(options) | Protect routes with x402 |

Low-level

| Export | Description | |--------|-------------| | payPaymentRequest, payAlgorandBridge, payX402Challenge | Direct Quantoz payment calls | | buildProof, buildBridgeProof, parseProof | X-PAYMENT proof encoding | | ALGOEUPAY_MERCHANT_WALLET, EURD_ASSET_ID, … | Constants |

Demo scenarios (AlgoEuPay backend)

| Scenario | Price | Endpoint | |----------|-------|----------| | Online product | €0.15 | GET /api/v1/x402/scenarios/online-product | | QR payment | €0.20 | POST /api/v1/x402/scenarios/qr-payment/create | | Hackathon report | €0.10 | GET /api/v1/x402/scenarios/hackathon-report |

Run the backend, then:

BACKEND_URL=http://localhost:8080 node examples/scenarios.mjs

Links

• AlgoEuPay repo
• x402 protocol

License

MIT