Hackathon Integration Guide

Get in touch

Hackathon support (Saturday)	Telegram: @Erwin_ma
GitHub	github.com/ever-online
Blog / updates	quantozpayments.substack.com

---

Step 1 — Experience it as a user

Before building, go through the payment flow as a consumer. This is what your users (and agents) will experience.

1. Download the Quantoz EURD Wallet app

   • App Store (iOS)
   • Google Play (Android)

   Sign up with your email and phone number (Tier 1 KYC — no ID upload needed). Then do a bank transfer to fund your wallet — your bank IBAN gets whitelisted for payouts at the same time. Do this before the hackathon.

2. Open SkipperBrief

   Go to skipper.ever-online.com.

   Pick a sailing region, choose your boat type and size, and proceed to payment.

3. Pay with the wallet

   Scan the QR code with the EURD Wallet app and confirm the €0.50 payment. The PDF briefing downloads immediately.

That’s the full consumer flow — a QR-based EURD payment from a regulated wallet to a merchant, settled in seconds. Your agent can do the exact same thing programmatically, without any human in the loop.

---

Step 2 — Run it as an agent

The same SkipperBrief endpoint is x402-protected. Any agent with a Quantoz account can pay it automatically:

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

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

// The agent hits the endpoint, gets a 402, pays, and retries — all automatically
const res = await fetch(
  "https://skipper.ever-online.com/api/forecast?region=dutch-north-sea&boatType=sailing&boatSize=medium"
);
const pdf = await res.arrayBuffer();

No QR code, no human confirmation. The withEurPayment() wrapper handles the 402 challenge, pays via the Quantoz API, and retries with proof.

Get your API key

You need a Quantoz account and API key to run this. Follow the sign up guide — the Quantoz team can set you up at the hackathon.

---

Step 3 — Build your own merchant endpoint

Now you know what the flow feels like. Here’s how to protect your own endpoint with an EURD payment gate.

Three paths are available depending on how you want to settle:

Path	Agent needs	Merchant needs	Settles
A — EURO	Quantoz account	Quantoz account	Off-chain, instant
B — EURD on Algorand	Algorand wallet + EURD	Algorand wallet + EURD	On-chain via facilitator
C — EURO → Algorand bridge	Quantoz account only	Whitelisted Algorand wallet	On-chain, ~1–3 min

Start with Path A — it requires the least setup. Both you and your users need a Quantoz account, and settlement is instant off-chain.

Key addresses & IDs

	Value
EURD ASA ID	1221682136
EURQ ASA ID	2768422954
Algorand x402 Facilitator	https://x402algo.ai.quantozpay.com
Quantoz API	https://api.quantozpay.com

---

Path A — EURO managed-account payments (start here)

Both sides need a Quantoz account. No blockchain knowledge required.

Merchant side

// 1. Issue 402 — call the Quantoz facilitator to create a payment request
if (!xPayment) {
  const r = await fetch("https://mcp.ai.quantozpay.com/x402/pay", {
    method: "POST",
    headers: { "X-API-KEY": process.env.QUANTOZ_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ accountCode: process.env.QUANTOZ_ACCOUNT, amount: 0.10, message: "x402 payment" }),
  });
  const { accepts } = await r.json();
  return Response.json({ x402Version: 2, error: "Payment required", accepts }, { status: 402 });
}

// 2. Verify on retry — call the facilitator to confirm payment
const r = await fetch("https://mcp.ai.quantozpay.com/x402/verify", {
  method: "POST",
  headers: { "X-API-KEY": process.env.QUANTOZ_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ proof: xPayment }),
});
const result = await r.json();
if (result.valid) {
  // serve the resource
}

Agent side

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

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

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

---

Path B — EURD on Algorand (direct on-chain)

Both sides need a whitelisted Algorand wallet with EURD.

Merchant side — 402 response

const atomicAmount = Math.round(amountEur * 100); // EURD has 2 decimal places

accepts.push({
  scheme: "exact",
  network: "algorand:mainnet",
  asset: "1221682136",
  maxAmountRequired: String(atomicAmount),
  payTo: "YOUR_ALGORAND_ADDRESS",
  maxTimeoutSeconds: 300,
  resource: "your-resource-id",
  description: "Payment for X",
  mimeType: "application/json",
  facilitator: "https://x402algo.ai.quantozpay.com",
});

Merchant side — settle

const res = await fetch("https://x402algo.ai.quantozpay.com/settle", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    x402Version: 2,
    paymentPayload: xPayment,
    paymentRequirements: {
      scheme: "exact",
      network: "algorand:mainnet",
      maxAmountRequired: String(atomicAmount),
      payTo: "YOUR_ALGORAND_ADDRESS",
      asset: "1221682136",
      resource: "your-resource-id",
      description: "Payment for X",
      mimeType: "application/json",
      maxTimeoutSeconds: 300,
    }
  })
});
const { success, txHash } = await res.json();
if (success) { /* serve resource */ }

Agent side — paying with algorand-mcp

claude mcp add algorand-mcp -- npx -y algorand-mcp

Ask Claude to create a wallet and opt in to EURD ASA 1221682136. Then link the address to your Quantoz account in the wallet app to get it whitelisted. Once funded, withEurPayment() handles Path B automatically.

---

Path C — EURO → Algorand bridge (most powerful)

Agent has a Quantoz EURO account; merchant has a whitelisted Algorand wallet. No Algorand wallet needed on the agent side.

Quantoz converts the agent’s EURO balance to EURD and sends it on-chain automatically.

Agent side — automatic via withEurPayment()

No extra code. withEurPayment() detects an exact + algorand:mainnet accept in the 402 and uses the bridge automatically.

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

const res = await fetch("https://skipper.ever-online.com/api/forecast?region=dutch-north-sea");

Agent side — via MCP tools

1. create_payment { paymentFrom, paymentTo: <Algo address>, toType: "BlockchainAddress", amount }
   → returns { transactionCode: "QP20260605..." }

2. poll get_transactions { txCode: "QP20260605..." } until blockchainTxId appears

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

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

Merchant side — 402 response

Same as Path B — include the exact accepts entry. The merchant doesn’t need to know whether the agent paid directly or via the bridge.

Merchant side — verify bridge proof

const proof = JSON.parse(Buffer.from(xPayment, "base64url").toString("utf8"));

if (proof.payload.transactionCode) {
  const { blockchainTxId, payTo, asset } = proof.payload;

  const tx = await fetch(
    `https://mainnet-idx.algonode.cloud/v2/transactions/${blockchainTxId}`
  ).then(r => r.json());

  const axfer = tx.transaction?.["asset-transfer-transaction"];
  if (
    String(axfer?.["asset-id"]) === asset &&
    axfer?.receiver === payTo &&
    axfer?.amount >= atomicAmount
  ) {
    // verified — serve resource
  }
}

---

EURD decimals

EURD has 2 decimal places:

EUR	Atomic units
0.10	10
0.50	50
1.00	100

---

Whitelisting requirement

EURD and EURQ are MiCA-regulated stablecoins. Both sender and receiver Algorand addresses must be KYC-whitelisted before they can send or receive these tokens.

Whitelisting is done through the Quantoz EURD Wallet app — link your Algorand address to your verified account.

---

Facilitator endpoints

https://x402algo.ai.quantozpay.com

Endpoint	Description
GET /health	Liveness check
GET /supported	Supported schemes, networks, ASA IDs
POST /verify	Validate a signed transaction group (no on-chain action)
POST /settle	Validate + submit transaction group to Algorand mainnet