AbaPay

⚡ AbaPay Protocol

AbaPay is a decentralized, Web3-native utility payment platform built on Base (the default chain) and Celo. It lets users pay for real-world bills — Airtime, Mobile Data, Electricity, Cable TV, Bank Transfers, Education PINs, and International Airtime/Data — using on-chain stablecoins (USDT, USDC, USAT), with instant fiat settlement handled server-side via the VTpass API. Payments can be made directly in the web app, or hands-free through a conversational, autonomous AI agent ("DeAI") on Telegram, WhatsApp, and X — a real on-chain identity under ERC-8004, discoverable on 8004scan.io — that can pay bills unattended, run recurring/scheduled autopay, and settle multi-recipient batch payments, all spending from a bounded, user-revocable on-chain allowance — no custody, no server-side keys.

Designed for low fees, cross-border utility vending (Nigeria + every country VTpass's live international catalogue returns), and mobile-first accessibility — MiniPay, Valora, Farcaster Mini Apps, Coinbase Smart Wallet / Base Account, MetaMask, and any other WalletConnect-compatible wallet (see Supported Wallets & Environments).

Operator: Masonode Technologies Limited (RC 9524980), Nigeria.

🌟 Key Features

• Multi-Chain Payments: Pay bills directly with USDT, USDC, or USAT on Base (Mainnet/Sepolia) or Celo (Mainnet/Alfajores). Base is the default chain; Celo remains fully supported and switchable. The app auto-detects the connected chain and filters/reorders available stablecoins accordingly — USDC leads on Base, USD₮ leads on Celo, and USAT is Celo-mainnet-exclusive.
• Live VTpass Catalogue — nothing about a provider is hardcoded any more: every provider name, logo, and amount limit for airtime, data, electricity, cable and education is fetched live from VTpass (src/lib/vtpassCatalog.ts, served to the browser by /api/providers) rather than from four separate hardcoded lists. The app, chat, MCP and the admin dashboard all read the same in-process cache, so there is exactly one source of truth. See Live provider catalogue below.
• Per-Provider Amount Limits, Enforced Live: the ceiling is VTpass's real published minimium_amount/maximum_amount *per provider*, not one flat number per service — airtime alone ranges MTN ₦200,000 / Glo ₦100,000 / Airtel ₦50,000 / 9mobile ₦50,000, and electricity minimums range ₦100 (Ikeja, Aba) to ₦2,000 (Ibadan). A flat cap either wrongly refused a valid MTN top-up or wrongly accepted an Airtel one that VTpass rejects *after* the user has already paid on-chain.
• International Bill Pay: Users can select a country and pay for foreign airtime/data in that country's own currency and rate — transaction history and receipts reflect the *local* currency, not just Naira. The country list is fetched live from VTpass (/get-international-airtime-countries) on every channel, so the app, chat and MCP can never disagree about which countries are covered.
• Instant Vending: Automated API integration with VTpass for instant token generation, airtime top-ups, and data bundle delivery.
• Education PINs in every channel: WAEC result-checker and WAEC registration PINs are buyable from the app, from chat (Telegram/WhatsApp/X/in-app), and over MCP — not app-only. ⚠️ JAMB is a deliberate honesty caveat: the code path exists end-to-end (intent parsing, profile-ID verification, variation_code handling), but jamb is not enabled on the current VTpass merchant account — VTpass answers {"code":"011","content":{"errors":"Service is Not Valid"}} — so it does not appear in the live catalogue and cannot currently be sold. If the account is enabled for it, it appears automatically with no code change.
• Smart Merchant Verification: Validates electricity meters, smartcard/IUC numbers, and account details *before* accepting crypto payments, eliminating user errors and failed vends.
• AbaPoints Loyalty System: Users earn points pegged 1:1 to stablecoin value spent, trackable via the in-app points badge and a dedicated API endpoint.
• Automatic Refund Safety Net: Failed vends after confirmed on-chain payment are automatically flagged, verified, and refunded on-chain to the user's wallet.
• DND-Fallback SMS: Automated SMS delivery of electricity tokens/PINs, bypassing the Nigerian Do-Not-Disturb (DND) registry for critical transaction alerts.
• Multi-Channel Support & Notifications: Built-in support ticketing, plus webhook integrations for Telegram, WhatsApp, and X (Twitter) so users and admins can transact/get notified from their preferred channel.
• Conversational AI Agent ("DeAI"): A natural-language assistant (/api/deai) that lets users check balances and pay bills via chat-style commands, backed by Claude (Anthropic). Reachable via Telegram, WhatsApp, X, and an in-app chat widget (src/components/AIChat.tsx) on the storefront itself. Understands intent, not just menu numbers — replying "Celo" or "usdt" works exactly like replying "1" or "2" — and shows the live balance and approved agent limit for every token at the moment you're asked to pick one, so you're never choosing blind. If a session goes cold (network drop, abandoned mid-flow) it's recognised and cleaned up automatically rather than left dangling; and if a network hiccup happens right after you enter your PIN, the payment is never silently lost or double-spent — it's tracked through to a confirmed on-chain outcome before the agent reports back.
• Agent-Initiated Payments (AbaPayV3): Users can grant the DeAI agent a bounded, on-chain, revocable spending allowance (setSpendingAllowance) — chosen independently per chain and per stablecoin from the Agent Hub tab — so it can pay bills on their behalf from Telegram/WhatsApp/X with no wallet signature needed at payment time and no custody of user funds. If no allowance is approved for the chain/token a chat payment needs, the agent detects that up front and offers a straight choice: approve it now, or complete this one payment via a signed deep link instead. See AbaPayV3 — agent allowances below.
• Autonomous Scheduling & Autopay Agent: Beyond one-off chat payments, users can ask the DeAI agent to set up recurring bills (monthly/weekly/daily), a one-time future payment ("pay this in 10 minutes"), or a single request covering multiple recipients/accounts at once — the agent groups them by chain/token and settles each leg through the same allowance-bounded relayer, unattended, on schedule, with zero further interaction required from the user.
• On-Chain Attribution: every Celo transaction AbaPay sends (app payments, approvals, the agent relayer, admin vault actions) carries one ERC-8021 suffix with both of our Celo tags (src/lib/attribution.ts): celo_2719403c6aff for the Celo Open Rails hackathon and celo_9d71588659ec for Celo Builders. x402 payments are submitted on-chain by the facilitator, not by AbaPay, so they carry no tag. Base transactions carry Base's own builder code instead.
• On-Chain Agent Identity (ERC-8004): AbaPay's DeAI agent is registered as a real on-chain identity on both Celo and Base via the ERC-8004 "Trustless Agents" registry, so it's discoverable on 8004scan.io / AgentScan — independent of, and unrelated to, how it moves money. See ERC-8004 agent identity below.
• MCP Server (AI Agent Payments): AbaPay is reachable by any MCP-speaking AI client (Claude, or any other agent that supports the Model Context Protocol) as a real tool server — describe_capabilities, check_balance, list_plans, pay_bill, multi-recipient pay_bill_batch, and recurring/one-off schedule_bill/list_schedules/cancel_schedule — over Streamable HTTP JSON-RPC at /api/mcp. This is a fourth channel alongside Telegram/WhatsApp/X, not a new trust boundary: it runs through the exact same allowance-bounded, kill-switch-gated, discount-aware execution pipeline as the chat channels, on either Celo or Base depending on what the linking wallet approved. See MCP Server below.
• MCP OAuth 2.1 (authorize once, not once per conversation): the connector supports a full OAuth 2.1 authorization-code + PKCE (S256) flow with Dynamic Client Registration (/api/oauth/register, /api/oauth/authorize, /api/oauth/token, discovery under /.well-known/). A user authorizes once in a browser — proving their API key and PIN on AbaPay's own hand-rendered consent page — and every future conversation reconnects with a Bearer token instead of retyping an API key. OAuth never authorizes a spend: the PIN is still required on every single pay_bill call, and a Bearer token alone can only read a balance. The api_key tool argument remains the fallback for clients that can't do OAuth.
• `list_plans` — real VTpass plan codes and prices, never guessed: for DATA/CABLE/EDUCATION, list_plans returns the currently purchasable plans with their exact variation_codes and live VTpass prices, and both the tool description and the server instructions tell the client to call it before pay_bill rather than guessing.
• x402 Settlement (main app, both chains): Payments made directly in the web app settle via the x402 HTTP-payment protocol — Celo's own facilitator for USDC/USD₮/USAT on Celo, the Coinbase CDP facilitator for USDC on Base — so they're genuinely indexed on x402scan, not relabeled contract calls. Anything without EIP-3009 uses the on-chain payBill flow, including Base's sponsored-gas path. ⚠️ x402 needs an EIP-3009 transferWithAuthorization signature, which is structurally what a drainer asks for, so some wallet scanners flag it as risky — a known, deliberate trade for x402scan visibility; NEXT_PUBLIC_X402_ENABLED=false opts out. The signature-free agent-initiated flow is untouched either way. See x402 settlement below.
• Dynamic Exchange Engine: Live market rate conversions with admin-configurable exchange rate and automated profit spread calculation, verified server-side to prevent underpayment exploits.
• Executive Admin Dashboard: Real-time monitoring of VTpass fiat balance, on-chain vault balances per token/chain, transaction analytics, manual refund tools, and CSV export — protected behind admin auth.
• Kill Switches That Actually Stop Every Channel: the dashboard's "pause a service" toggles are a two-level model — a per-service master (MASTER_AIRTIME, MASTER_INTERNET, MASTER_ELECTRICITY, MASTER_CABLE, MASTER_EDUCATION, MASTER_INTERNATIONAL) plus a per-provider switch keyed by VTpass serviceID (AIRTIME_mtn, INTERNET_airtel-data, ELEC_ikeja-electric, CABLE_dstv, EDU_waec). A payment is refused when either level is off. src/lib/serviceRules.ts's killSwitchKeysFor() maps an agent intent (+ provider, normalised through resolveServiceId so ELEC_ikeja can't miss ELEC_ikeja-electric) onto exactly those keys, so chat, MCP and the autonomous scheduler now honour the same switches the web app does. See Kill switches below.
• Sponsored Gas on Base: Coinbase Smart Wallet / Base Account users can pay with zero gas fees — the app detects paymaster support via EIP-5792 and batches approval + payment into a single sponsored transaction. Wallets without this capability (MetaMask, WalletConnect, Valora, etc.) transparently fall back to the normal self-paid flow.
• Shareable & Downloadable Receipts: Every receipt can be shared as an image straight to WhatsApp/Telegram/etc. via the device's native share sheet, or saved directly as a PNG or PDF.
• Farcaster Mini App Ready: Ships with Farcaster frame metadata so A