Agent Developer Guide

This guide explains how to build an agent that pays x402-protected resources automatically. Two payment schemes are supported — the withEurPayment() wrapper handles both transparently.

Prerequisites

• A Quantoz account with an API key and funded managed account → Sign up
• npm install @ever_amsterdam/x402-euro-eurd → npmjs.com/package/@ever_amsterdam/x402-euro-eurd

---

The easy path — withEurPayment()

The withEurPayment() wrapper detects the scheme in the 402 response and pays automatically. You don’t need to know which scheme the merchant uses.

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

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

// Works for euro scheme, exact/Algorand scheme, and bridge payments
const res = await fetch("https://merchant.example.com/premium-resource");

What it does per scheme:

Scheme in 402	What withEurPayment() does
euro	Pays via Quantoz API, builds proof with paymentRequestCode
exact + algorand:mainnet	Converts EURO → EURD on-chain via the bridge, builds proof with blockchainTxId

---

How the payment works per scheme

euro scheme (off-chain)

The 402 response contains a paymentRequestCode. The agent pays it via the Quantoz API:

1. Hit resource → 402 with { scheme: "euro", paymentRequestCode: "pr_...", amount: "0.10" }

2. POST /transaction/payment
   { toType: "PaymentRequestCode", paymentTo: "pr_...", amount: 0.10 }

3. Build X-PAYMENT proof:
   {
     "x402Version": 2,
     "scheme": "euro",
     "network": "quantoz:mainnet",
     "payload": { "paymentRequestCode": "pr_..." }
   }

4. base64url-encode → X-PAYMENT header → retry

exact scheme on Algorand — direct on-chain

Agent holds EURD directly on Algorand (whitelisted wallet required):

1. Hit resource → 402 with { scheme: "exact", network: "algorand:mainnet", asset: "1221682136", maxAmountRequired: "50" }

2. make_asset_transfer_txn (EURD ASA 1221682136, amount in atomic units, to merchant payTo)
   wallet_sign_transaction (fee: 1000 microAlgos)

3. Build X-PAYMENT proof:
   {
     "x402Version": 2,
     "scheme": "exact",
     "network": "algorand:mainnet",
     "payload": { "transaction": "<base64 signed txn>", "paymentIndex": 0 }
   }

4. base64url-encode → X-PAYMENT header → retry

exact scheme on Algorand — via EURO bridge

Agent has only a Quantoz EURO account. No Algorand wallet needed.

1. Hit resource → 402 with { scheme: "exact", network: "algorand:mainnet", payTo: "<Algo address>" }

2. POST /transaction/payment
   { toType: "BlockchainAddress", paymentTo: "<Algo address>", amount: 0.50 }
   → returns { transactionCode: "QP20260605..." }

3. Poll GET /transaction?txCode=QP20260605... until blockchainTxId appears

4. Build X-PAYMENT proof:
   {
     "x402Version": 2,
     "scheme": "exact",
     "network": "algorand:mainnet",
     "payload": {
       "transactionCode": "QP20260605...",
       "blockchainTxId": "<Algorand txID>",
       "payTo": "<merchant Algorand address>",
       "asset": "1221682136"
     }
   }

5. base64url-encode → X-PAYMENT header → retry

withEurPayment() does all of this automatically when it detects no euro accept in the 402.

---

Using the MCP pay_x402_challenge tool

For agents using the Quantoz MCP server directly (e.g. Claude with the connector), the pay_x402_challenge tool handles the full pay-and-proof flow in one step:

Tool: pay_x402_challenge
Arguments:
  challenge:    <paste the full 402 response body>
  paymentFrom:  <your account code>

Returns:

{
  "xPaymentHeader": "<base64url proof>",
  "amount": "0.10",
  "instruction": "Retry your request with the header: X-PAYMENT: <proof>"
}

The tool picks the best scheme automatically (prefers euro; falls back to exact via bridge).

---

System prompt snippet

When you receive an HTTP 402 response, call the pay_x402_challenge MCP tool
with the full 402 response body and your account code. Then retry the original
request with the X-PAYMENT header value it returns.

---

Error handling

Response	Meaning
{ valid: false, reason: "Payment not confirmed (status: Open)" }	Payment not yet processed — wait briefly and retry verify
{ valid: false, reason: "Payment request already used" }	Replay attempt — request a fresh 402
{ valid: false, reason: "Payment request expired" }	Timed out — request a fresh 402 and pay again
402 on retry	Verification failed — check account balance

---

Environment variables

QUANTOZ_API_KEY=<your-api-key>
QUANTOZ_ACCOUNT=<your-account-code>   # e.g. ACC_xxxxx
QUANTOZ_BASE_URL=https://api.quantozpay.com