IoMarkets Topup (demo)

IoMarkets Topup — real-world checkout for AI agents on Algorand

Demo only: payments are switched off and nothing can be bought. This is a technology demonstration, not a commercial service.

Your AI agent can buy real things — and send money. In the pilot today: travel eSIMs and mobile airtime/data top-ups. Prepaid bills and international payments (bank / mobile money / UPI payouts via a licensed partner) are built and supplier-gated. Everything is paid per order in USDC on Algorand via x402. No account, no API key, no card. Money settles on-chain first, goods ship second, failures refund on-chain automatically, and every terminal order carries an ed25519-signed receipt anyone can verify.

Built for the Global x402 Challenge (Algorand Foundation × GoPlausible). Pilot: https://iomarkets.app · agent docs: /agent.md · ledger: /v1/ledger · receipt spec: docs/RECEIPTS.md

How it works

agent ── GET /v1/lookup?phone=+91…  ─▶ operator + offers                      (free)

agent ── POST /v1/quote {type, offerId, recipient, amount} ─▶ quoteId, price (free, 10-min lock) agent ── POST /v1/orders {quoteId} ─▶ 402 + exact USDC amount (x402) agent ── …signs Algorand USDC payment, retries with PAYMENT-SIGNATURE ─▶ facilitator settles on-chain server ── order created ONLY after settlement ─▶ supplier purchase ─▶ delivered | failed → on-chain refund agent ── GET /v1/orders/{id} ─▶ status, confirmation (operator ref / eSIM LPA), signed receipt, txids

Trust model (what makes agents use it extensively)

• No order without a settled payment — the order row is created from the facilitator's settlement txid.
• Exact pricing — the 402 challenge carries the quoted amount; a quote pays once and expires in 10 min.
• Automatic refunds — supplier failure ⇒ USDC returned to the paying address on-chain, note = order id.
• Signed receipts — {order, amount, payer, settlement txid, refund txid} signed with a published ed25519 key (pnpm verify receipts/ .json --online checks the signature *and* both transactions on Algorand). The same check is an endpoint anyone can call — POST /v1/verify — and it verifies receipts from any server that adopts the format, not just ours. The format is a spec: docs/RECEIPTS.md.
• Public ledger — every order, outcome and txid (recipients hashed).
• Abuse posture — $50/order (goods), $200/payment (payouts), $200/payer/day, sanctioned destinations refused, replay guard, rate limits; payouts need a sender record and a partner KYC reference above $100/day (src/compliance.ts).
• Key hygiene — the server holds one hot key (refund float, daily-capped); PAY_TO is an address only; secrets come from files / systemd encrypted credentials, never .env (see src/keys.ts).

Run it

pnpm install --frozen-lockfile --ignore-scripts

cp .env.example .env # PAY_TO, RECEIPT_* (pnpm gen-key), SUPPLIER=mock to start pnpm dev # http://127.0.0.1:3000 (NETWORK=mainnet — the facilitator serves mainnet) pnpm test && pnpm typecheck

The batch payout console (web/ — React + TanStack Start, installed with bun).

pnpm install:web && pnpm build:web # → web/dist/client, served by the SAME process at /pay pnpm dev:web # or: vite with HMR on http://127.0.0.1:8080/pay/ , /v1 proxied to :3000 AGENT_MNEMONIC_FILE=~/.secrets/agent.mnemonic pnpm buy --phone +919876543210 --amount 100 # real USDC pnpm check-bazaar # listed after the first settled payment

Mock supplier rules for demos: a phone ending `0000` fails (→ refund path), `1111` is delivered after polling.

Agent integrations

• .claude-plugin/plugin.json — Claude Code plugin: this skill + the hosted MCP server, zero setup for the user.
• server.json — MCP registry manifest (remotes → https://iomarkets.app/mcp); needs the deploy live + a DNS TXT record proving the app.iomarkets namespace.
• skills/iomarkets-topup/SKILL.md — the single shared skill for OpenClaw, Hermes and Claude Code (agentskills format); publishing to each hub is a copy, not a fork (skills/README.md).
• pnpm mcp — MCP server (stdio) with lookup_phone, list_offers, quote, buy, order_status, verify_receipt, ledger, create_pay_link.
• Bazaar: the paid route declares discovery metadata + the x402-global-challenge tag; it is indexed on first settlement.

Layout

src/app.ts          HTTP surface + x402 wiring (dynamic price = quote, preflight hook, post-settle order creation)

src/orders.ts quote → paid → fulfilling → delivered | failed → refunded (single-flight, resumable) src/suppliers/ types · mock · zendit · reloadly · composite (goods + payouts) · payout-partner (skeleton) src/compliance.ts payout gate (sanctions, caps, sender, KYC threshold) src/receipt.ts ed25519 receipts src/refunds.ts on-chain refunds (daily cap) src/db.ts node:sqlite src/keys.ts secret sources (file / systemd cred / env) src/growth.ts pay links · proof pages · referral routes src/referrals.ts margin share, reserve-first payouts src/mcp.ts MCP server src/client/paying.ts x402 paying fetch with budget scripts/ gen-key · new-wallet · optin-usdc · buy · verify-receipt · check-bazaar docs/RECEIPTS.md the signed-receipt format, as a spec other sellers can adopt deploy/entrypoint.sh container entrypoint: refuses to start on a config that cannot take money