@ever_amsterdam/x402-euro-eurd

A fetch wrapper that automatically pays x402 payment challenges using Quantoz managed accounts. When your agent hits a paywalled resource, this package pays and retries — transparently.

Supports two payment schemes:

• euro — off-chain, instant. Both sides need a Quantoz managed account.
• exact on algorand:mainnet — on-chain EURD via the EURO→Algorand bridge. Only the agent needs a Quantoz account; the merchant just needs a whitelisted Algorand address.

Install

npm install @ever_amsterdam/x402-euro-eurd

Usage

import { withEurPayment } from "@ever_amsterdam/x402-euro-eurd";

const fetch = withEurPayment(globalThis.fetch, {
  apiKey: process.env.QUANTOZ_API_KEY,
  fromAccount: process.env.QUANTOZ_ACCOUNT, // e.g. "ACC_xxxxx"
});

// 402 challenges are paid and retried automatically
const res = await fetch("https://merchant.example.com/premium-resource");
const data = await res.json();

All other responses (200, 4xx, 5xx) pass through untouched.

How it works

1. Makes the original request
2. If the response is 402, inspects the accepts array:
   • euro scheme → pays via POST /transaction/payment with toType: "PaymentRequestCode", builds proof with paymentRequestCode
   • exact + algorand:mainnet → pays via the EURO→Algorand bridge (toType: "BlockchainAddress"), builds proof with transactionCode
3. Retries the original request with the X-PAYMENT header
4. Returns the retry response

Options

withEurPayment(fetch, {
  apiKey: string;        // Quantoz API key
  fromAccount: string;   // Account code to pay from (ACC_xxxxx)
  baseUrl?: string;      // Defaults to https://api.quantozpay.com

  // Return false to cancel a payment (e.g. spending limits)
  onBeforePayment?: (accept: EurdAccept) => boolean | Promise<boolean>;

  // Called after payment, before the retry
  onPaymentComplete?: (accept: EurdAccept) => void | Promise<void>;
})

Spending limit example

const fetch = withEurPayment(globalThis.fetch, {
  apiKey: process.env.QUANTOZ_API_KEY,
  fromAccount: process.env.QUANTOZ_ACCOUNT,
  onBeforePayment: (accept) => {
    if (parseFloat(accept.amount) > 0.10) {
      console.warn(`Skipping: €${accept.amount} exceeds limit`);
      return false; // original 402 is returned
    }
    return true;
  },
});

Low-level exports

import { buildProof, parseProof, buildBridgeProof } from "@ever_amsterdam/x402-euro-eurd";

// Build X-PAYMENT header for euro scheme
const proof = buildProof(accept);

// Parse X-PAYMENT header back to a proof object
const decoded = parseProof(xPaymentHeader);

// Build X-PAYMENT header for Algorand bridge scheme
const bridgeProof = buildBridgeProof(accept, transactionCode);

Requirements

• A Quantoz account with a funded managed account
• Node.js 18+ (uses global fetch and Buffer)

Environment variables

QUANTOZ_API_KEY=qpay_live_...
QUANTOZ_ACCOUNT=ACC_xxxxx
QUANTOZ_BASE_URL=https://api.quantozpay.com  # optional

Docs

docs.ai.quantozpay.com