Toppa / Docs
User Guides

Getting Started

Toppa is an AI agent on Telegram and WhatsApp that lets you buy airtime, data, pay utility bills, and purchase gift cards using cUSD on the Celo blockchain. No sign-up, no KYC.

1. Open the Bot

Telegram: Search for @toppa402Bot on Telegram or click this link. Press Start to begin.

WhatsApp: Message the Toppa WhatsApp number and send /start to begin.

A cUSD wallet is automatically created for you. You'll see your wallet address in the welcome message.

2. Fund Your Wallet

Send cUSD (Celo Dollar) to your wallet address. You can also deposit CELO, USDC, USDT, or cEUR and use /swap to convert to cUSD. Get tokens from:

  • Valora — mobile-first Celo wallet
  • MiniPay — Opera's embedded Celo wallet
  • Any Celo-compatible wallet — MetaMask, Celo Terminal, etc.
  • Exchanges — Binance, Coinbase (withdraw to Celo network)
Tip: You can ask Toppa for your wallet address anytime by typing "what's my wallet address?" or "balance". Use /wallet to see all token balances.

3. Start Using Toppa

Just type what you need in plain language — or send a voice note and Toppa will transcribe it automatically. Toppa understands English, French, Yoruba, Swahili, and more. Examples:

"Send ₦2000 airtime to my sister" "Buy a $10 Netflix gift card" "Pay my DStv subscription" "Check my balance"
Voice notes: Record a voice message on Telegram or WhatsApp and Toppa will transcribe and act on it — no typing needed.

4. Using Toppa in Groups

Add Toppa to a Telegram or WhatsApp group. In groups, Toppa only responds when:

  • You @mention the bot (e.g., @toppa402bot send airtime)
  • You reply to one of the bot's messages
  • You use a command (e.g., /wallet, /group)

Commands like /help, /wallet, and /group always work without @mentioning.

Airtime & Data

Top up any phone number in 170+ countries with 800+ mobile operators. Toppa auto-detects the operator from the phone number.

Sending Airtime

Tell Toppa the amount and recipient — type it out or send a voice note. You can use local currency or USD:

"Send $5 airtime to +234 802 1234 567" "Top up my sister's phone with ₦1000" "Recharge +254 712 345 678 with 500 KES"

Toppa will show you an order confirmation with the exact cUSD cost. Confirm to proceed.

Buying Data Plans

Request data bundles the same way:

"Buy 2GB data for my number" "Send 1GB MTN data to +234 803 000 0000"

Using Saved Contacts

Once you've saved a contact (see Smart Memory), you can use names instead of numbers:

"Send airtime to mom" "Buy data for my brother"

Utility Bills

Pay electricity, water, TV subscriptions (DStv, GOtv, Startimes), and internet bills directly from chat.

How It Works

Tell Toppa what bill you want to pay:

"Pay my DStv subscription" "Pay electricity bill for meter 12345678" "Renew my GOtv"

Toppa will look up available billers in your country and ask for any required details (meter number, smart card number, etc.).

Supported Billers

Billers vary by country. Use the Playground on the landing page to browse available billers by country, or ask Toppa directly:

"What bills can I pay in Nigeria?" "Show me electricity providers in Kenya"

Gift Cards

Purchase from 300+ brands — Amazon, Steam, Netflix, Spotify, PlayStation, Xbox, Google Play, Apple, and more.

Buying a Gift Card

"Buy a $25 Steam gift card" "Get me a Netflix gift card for $15" "I want an Amazon gift card"

Toppa will show available denominations and the cUSD price. After you confirm, the gift card code is delivered right in the chat.

Browsing Available Cards

"What gift cards do you have?" "Show me gaming gift cards"

Group Wallets

Create a shared wallet for your Telegram or WhatsApp group. Pool funds, vote on spending, and track contributions — all on-chain.

Enabling a Group Wallet

Add Toppa to your group and run:

/group enable

The first person to run this becomes the group admin. A unique Celo wallet is created for the group.

Contributing Funds

Any member can transfer cUSD from their personal wallet to the group wallet:

/contribute 5 /contribute 10.50

Contributors are automatically tracked. View contributions with /group.

Spending from the Group Wallet

When someone asks to spend from the group wallet (e.g., "buy airtime from the group wallet"), Toppa creates a poll for members to vote on. The action executes automatically when the approval threshold is reached.

  • Telegram: Native Telegram polls — vote directly in the chat
  • WhatsApp: Native WhatsApp polls — same experience

Group Commands

CommandWhoDescription
/group enableAnyone (first = admin)Create the group wallet
/groupAnyoneView balance, address, members, recent activity
/contribute <amount>AnyoneTransfer cUSD from personal to group wallet
/group_withdraw <addr> <amt>Admin onlyWithdraw from group to external address
/threshold <0-100>Admin onlySet poll approval percentage (default 70%)

Poll Governance

All group spending goes through democratic polls:

  • Default threshold: 70% approval needed
  • Polls auto-expire after 24 hours
  • If enough "No" votes make approval impossible, the poll is rejected immediately
  • Admin can bypass polls for urgent withdrawals via /group_withdraw

Multi-Currency Deposits

Deposit any supported Celo token and auto-swap to cUSD. No need to hold only cUSD.

Supported Tokens

  • cUSD — Celo Dollar (primary currency, no swap needed)
  • CELO — Native Celo token
  • USDC — USD Coin on Celo
  • USDT — Tether on Celo
  • cEUR — Celo Euro

How to Swap

After depositing any token, run:

/swap

Toppa will automatically convert all non-cUSD tokens to cUSD using Uniswap V3 on Celo. You'll see a summary of what was swapped and your new cUSD balance.

Viewing All Balances

Use /wallet to see balances for all supported tokens, not just cUSD.

Reports & Statements

Generate PDF or Excel expenditure reports for your personal transactions or group activity.

Generating a Report

Ask Toppa in natural language:

"Generate my statement as PDF" "Send me an Excel report for this month" "Group spending report as PDF"

Toppa generates the report and delivers it as a document right in the chat.

What's Included

  • Transaction list — Date, type, description, amount, status, TX hash
  • Summary — Total spent, breakdown by category (airtime/data/bills/gift cards)
  • Date range — Filter by start/end date, or get all transactions
  • Group reports — Shows group contributions, withdrawals, and poll outcomes

Smart Memory

Toppa remembers your contacts, preferences, and transaction history across sessions. No manual setup needed.

Saving Contacts

Toppa learns contacts naturally from your conversations:

"My sister's number is +234 802 123 4567" "Save +254 712 000 000 as my brother"

Once saved, use the name in future requests: "Send airtime to my sister".

Preferences

Toppa learns your preferences over time:

  • Preferred operator (MTN, Airtel, Safaricom, etc.)
  • Default currency and amounts
  • Confirmation preferences

Transaction History

Ask about past transactions anytime:

"Show my last 5 transactions" "How much have I spent this week?"

Scheduled Payments

Set up recurring payments and Toppa handles them automatically. The heartbeat engine checks every 15 minutes.

Setting Up a Schedule

"Send mom ₦1000 airtime every Friday" "Pay my DStv on the 15th of every month" "Remind me to buy data every Monday"

Managing Schedules

"Show my scheduled payments" "Cancel the Friday airtime schedule"

Proactive Alerts

Toppa's heartbeat engine will proactively message you when:

  • A bill is coming due soon
  • A scheduled payment is about to execute
  • There are relevant promotions on your favorite operators
  • Your wallet balance is running low

Identity Verification

Verify your identity with Self Protocol to unlock higher spending limits. No KYC, no personal data — just a quick passport scan using zero-knowledge proofs.

Spending Tiers

StatusDaily LimitHow to Get
Unverified$20/dayDefault for all new users
Self-Verified$200/dayComplete the /verify flow

How to Verify

  1. Type /verify in Telegram or WhatsApp
  2. Tap the verification link — the Self app opens
  3. Scan your passport with NFC (~30 seconds)
  4. Done! Your limits upgrade automatically

How It Works

Self Protocol uses zero-knowledge proofs from your passport's NFC chip. This means:

  • No personal data is shared with Toppa — we only receive a proof of uniqueness
  • Sybil-resistant — one passport can only verify one account (nullifier-based)
  • No KYC process — no documents to upload, no waiting for approval
  • Valid for 1 year — then you can re-verify

Self Protocol Details

DetailValue
Self Agent ID#48 (Celo Sepolia)
Agent Address0x9480a88916074D9B2f62c6954a41Ea4B9B40b64c
Scopetoppa-verify
Callback EndpointPOST /api/verify
Status EndpointGET /api/verify/status
SDK@selfxyz/core
Don't have the Self app? Download it from self.xyz. The app is free and available on iOS and Android.
Developer Reference

API Overview

Toppa exposes its capabilities through six integration layers. Choose the one that fits your use case.

Protocol Endpoint Auth Best For
x402 api.toppa.cc/* Pay-per-call (cUSD) Agents, automated purchases
MCP api.toppa.cc/mcp None (open) Claude Desktop, Cursor, AI clients
A2A api.toppa.cc/a2a None (open) Agent-to-agent task delegation
REST api.toppa.cc/operators/:cc None (free) Discovery & browsing catalog
Telegram t.me/toppa402Bot Telegram account Human end-users
WhatsApp WhatsApp number WhatsApp account Human end-users

Base URL

https://api.toppa.cc

All endpoints accept and return JSON. No API keys required — paid endpoints use the x402 protocol (HTTP 402 + on-chain payment).

Pricing & Fees

Toppa charges a flat 1.5% service fee on top of the product cost. No hidden charges, no subscriptions.

Fee Formula

total = product_cost + (product_cost × 0.015)

Examples:
  $5.00 airtime  → $5.08 total  ($0.08 fee)
  $25.00 gift card → $25.38 total ($0.38 fee)
  $100 bill payment → $101.50 total ($1.50 fee)

Both the fee and total are rounded to 2 decimal places. The 402 response always returns the exact amount to pay — your agent doesn't need to calculate the fee.

Payment Details

DetailValue
Service fee1.5% of product cost
Payment currencycUSD (Celo Dollar) or USDC on Celo
Payment networkCelo Mainnet
Transaction max age~1 hour (720 blocks)
Amount tolerance0.2% (for gas rounding)
Replay protectionEach tx hash can only be used once
Auto-refundIf service fails after payment, cUSD is returned to payer
Rate limit10 requests per 5 minutes per payer address

x402 Protocol

x402 turns HTTP 402 (Payment Required) into a machine-readable payment flow. Agents pay per API call using cUSD on Celo — no API keys, no accounts, no invoices.

How It Works

  1. Request — Send a normal POST request to a paid endpoint (no headers needed).
  2. 402 Response — Toppa returns HTTP 402 with: price in cUSD, recipient wallet address, and network.
  3. Pay on-chain — Transfer the exact cUSD amount to the recipient address on Celo.
  4. Retry with proof — Resend the same request with the tx hash in the X-PAYMENT header.
  5. Fulfillment — Toppa verifies the payment on-chain, executes the service, and returns the result.
Settlement receipt: After successful fulfillment, the response includes a PAYMENT-RESPONSE header with a Base64-encoded receipt containing the tx hash, network, and payer address.

POST /send-airtime

Send airtime top-up to a mobile phone number. Operator is auto-detected from the phone number.

Request Body

FieldTypeRequiredDescription
phonestringYesRecipient phone number (local or international format)
countryCodestringYesISO 3166-1 alpha-2 country code (e.g. NG, KE, GH)
amountnumberYesAmount in cUSD (not local currency)

Example

# Step 1: Request without payment → 402
curl -X POST https://api.toppa.cc/send-airtime \
  -H "Content-Type: application/json" \
  -d '{"phone": "+2348021234567", "countryCode": "NG", "amount": 5}'

# 402 Response
{
  "price": "5.08",
  "currency": "cUSD",
  "recipient": "0xYOUR_TOPPA_WALLET",
  "network": "celo"
}

# Step 2: Pay 5.08 cUSD on Celo, then retry with proof
curl -X POST https://api.toppa.cc/send-airtime \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: 0xabc123...def456" \
  -d '{"phone": "+2348021234567", "countryCode": "NG", "amount": 5}'

Success Response 200

{
  "status": "success",
  "transactionId": 123456,
  "operatorTransactionId": "OP_789",
  "operatorName": "MTN Nigeria",
  "recipientPhone": "2348021234567",
  "requestedAmount": 5.00,
  "requestedAmountCurrencyCode": "USD",
  "deliveredAmount": 6030,
  "deliveredAmountCurrencyCode": "NGN",
  "discount": 0.15,
  "transactionDate": "2025-06-15T14:30:00Z",
  "pinDetail": null,
  "payment": {
    "productAmount": 5.00,
    "serviceFee": 0.08,
    "total": 5.08,
    "txHash": "0xabc123...def456",
    "payer": "0xPAYER_ADDRESS"
  }
}

JavaScript Example

// Using viem to send cUSD on Celo
import { createWalletClient, http, parseUnits } from 'viem';
import { celo } from 'viem/chains';

const CUSD = '0x765DE816845861e75A25fCA122bb6898B8B1282a';
const TOPPA_API = 'https://api.toppa.cc';

// 1. Get price quote (402 response)
const quoteRes = await fetch(`${TOPPA_API}/send-airtime`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: '+2348021234567',
    countryCode: 'NG',
    amount: 5
  })
});
const quote = await quoteRes.json(); // { price, recipient, ... }

// 2. Send cUSD on-chain
const txHash = await walletClient.writeContract({
  address: CUSD,
  abi: erc20Abi,
  functionName: 'transfer',
  args: [quote.recipient, parseUnits(quote.price, 18)]
});

// 3. Submit payment proof
const result = await fetch(`${TOPPA_API}/send-airtime`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PAYMENT': txHash
  },
  body: JSON.stringify({
    phone: '+2348021234567',
    countryCode: 'NG',
    amount: 5
  })
});
console.log(await result.json()); // { status: 'success', ... }

POST /send-data

Send a mobile data bundle. Requires an operatorId — use GET /operators/:cc to find data operators first.

Request Body

FieldTypeRequiredDescription
phonestringYesRecipient phone number
countryCodestringYesISO country code
amountnumberYesAmount in cUSD
operatorIdnumberYesOperator ID (from GET /operators/:cc). Server validates against country; falls back to auto-detect if invalid.

Example

curl -X POST https://api.toppa.cc/send-data \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: 0xabc..." \
  -d '{
    "phone": "+2348021234567",
    "countryCode": "NG",
    "amount": 2,
    "operatorId": 174
  }'

Success Response 200

{
  "status": "success",
  "transactionId": 123457,
  "operatorName": "MTN Nigeria",
  "recipientPhone": "2348021234567",
  "requestedAmount": 2.00,
  "deliveredAmount": 2412,
  "deliveredAmountCurrencyCode": "NGN",
  "transactionDate": "2025-06-15T14:32:00Z",
  "payment": {
    "productAmount": 2.00,
    "serviceFee": 0.03,
    "total": 2.03,
    "txHash": "0xabc...",
    "payer": "0xPAYER_ADDRESS"
  }
}
Tip: Data operators have data: true or bundle: true in the GET /operators/:cc response. FIXED-type operators require exact denomination amounts; RANGE-type accept any amount within min/max.

POST /pay-bill

Pay a utility bill — electricity, water, TV (DStv, GOtv, Startimes), or internet. Use GET /billers/:cc to find the biller ID first.

Request Body

FieldTypeRequiredDescription
billerIdnumberYesBiller ID (from GET /billers/:cc)
accountNumberstringYesMeter number, smartcard number, or account ID
amountnumberYesAmount in cUSD. Must be within the biller's min/max range.
countryCodestringYesISO country code (server validates biller belongs to this country)

Example

curl -X POST https://api.toppa.cc/pay-bill \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: 0xabc..." \
  -d '{
    "billerId": 42,
    "accountNumber": "1234567890",
    "amount": 10,
    "countryCode": "NG"
  }'

Success Response 200

{
  "status": "success",
  "id": 78901,
  "referenceId": "toppa-bill-1718...",
  "code": "PROCESSING",
  "message": "Bill payment submitted successfully",
  "submittedAt": "2025-06-15T14:35:00Z",
  "finalStatusAvailabilityAt": "2025-06-15T14:40:00Z",
  "payment": {
    "productAmount": 10.00,
    "serviceFee": 0.15,
    "total": 10.15,
    "txHash": "0xabc...",
    "payer": "0xPAYER_ADDRESS"
  }
}
Note: Bill payments may take up to 5 minutes to finalize on the biller's side. The finalStatusAvailabilityAt field indicates when the final status will be available.

POST /buy-gift-card

Purchase a gift card and receive the redeem code(s) in the response. Use GET /gift-cards or search by brand to find product IDs.

Request Body

FieldTypeRequiredDescription
productIdnumberYesGift card product ID (from discovery endpoints)
amountnumberYesAmount in cUSD. FIXED products require an exact denomination; RANGE products accept any value within min/max.
recipientEmailstringYesEmail address for delivery (also returned in response)
quantitynumberNoNumber of cards (default: 1, max: 10)

Example

curl -X POST https://api.toppa.cc/buy-gift-card \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: 0xabc..." \
  -d '{
    "productId": 5678,
    "amount": 25,
    "recipientEmail": "user@example.com"
  }'

Success Response 200

{
  "status": "success",
  "transactionId": 456789,
  "amount": 25.00,
  "discount": 0,
  "currencyCode": "USD",
  "fee": 0,
  "recipientEmail": "user@example.com",
  "product": {
    "productId": 5678,
    "productName": "Steam USD 25",
    "brand": { "brandId": 12, "brandName": "Steam" },
    "country": { "isoName": "US", "name": "United States" }
  },
  "redeemCodes": [
    { "cardNumber": "XXXX-XXXX-XXXX-XXXX", "pinCode": "1234" }
  ],
  "payment": {
    "productAmount": 25.00,
    "serviceFee": 0.38,
    "total": 25.38,
    "txHash": "0xabc...",
    "payer": "0xPAYER_ADDRESS"
  }
}
Redeem codes: Codes are usually available immediately. If they're still being generated, the response will include "redeemCodesNote": "Codes are being generated. Try again in a minute." instead. Use the transaction ID to retrieve codes later.

Discovery APIs

Free, unauthenticated REST endpoints for browsing Toppa's catalog. No x402 payment required. All responses are cached (30 min for operators/billers, 10 min for gift cards).

GET /operators/:countryCode

List all mobile operators for a country. Each operator includes denomination type (FIXED or RANGE), available amounts, FX rates, and logo URLs.

curl https://api.toppa.cc/operators/NG

[
  {
    "operatorId": 174,
    "name": "MTN Nigeria",
    "bundle": false,
    "data": false,
    "denominationType": "RANGE",
    "minAmount": 0.50,
    "maxAmount": 50.00,
    "fixedAmounts": null,
    "fx": { "rate": 1206, "currencyCode": "NGN" },
    "logoUrls": ["https://..."],
    "country": { "isoName": "NG", "name": "Nigeria" }
  }
]

GET /detect-operator/:phone/:countryCode

Auto-detect the mobile operator from a phone number. Returns the full operator object including available plans and pricing.

curl https://api.toppa.cc/detect-operator/08021234567/NG

{
  "operatorId": 174,
  "name": "MTN Nigeria",
  "denominationType": "RANGE",
  "minAmount": 0.50,
  "maxAmount": 50.00,
  "fx": { "rate": 1206, "currencyCode": "NGN" }
}

GET /billers/:countryCode

List utility billers for a country. Optional query param ?type= to filter by type.

Query ParamValues
typeELECTRICITY_BILL_PAYMENT, WATER_BILL_PAYMENT, TV_BILL_PAYMENT, INTERNET_BILL_PAYMENT
curl "https://api.toppa.cc/billers/NG?type=TV_BILL_PAYMENT"

[
  {
    "id": 42,
    "name": "DStv Nigeria",
    "serviceType": "TV_BILL_PAYMENT",
    "countryCode": "NG",
    "minLocalTransactionAmount": 1000,
    "maxLocalTransactionAmount": 50000,
    "localTransactionCurrencyCode": "NGN",
    "fx": { "rate": 1206, "currencyCode": "NGN" }
  }
]

GET /gift-cards/:countryCode

List available gift card brands for a country, grouped by brand with product counts and price ranges.

curl https://api.toppa.cc/gift-cards/US

[
  {
    "productId": 5678,
    "productName": "Steam USD 25",
    "denominationType": "FIXED",
    "fixedSenderDenominations": [10, 25, 50, 100],
    "brand": { "brandId": 12, "brandName": "Steam" },
    "country": { "isoName": "US", "name": "United States" },
    "recipientCurrencyCode": "USD",
    "category": { "id": 3, "name": "Gaming" },
    "redeemInstruction": { "concise": "Redeem at store.steampowered.com" },
    "status": "AVAILABLE"
  }
]

GET /promotions/:countryCode

List active operator promotions and bonus deals for a country.

curl https://api.toppa.cc/promotions/NG

[
  {
    "title": "MTN 2x Bonus Weekend",
    "description": "Get double data on all recharges this weekend",
    "startDate": "2025-06-14",
    "endDate": "2025-06-16"
  }
]

GET /countries

List all supported countries with currency info and calling codes.

curl https://api.toppa.cc/countries

[
  {
    "isoName": "NG",
    "name": "Nigeria",
    "currencyCode": "NGN",
    "currencyName": "Nigerian Naira",
    "currencySymbol": "₦",
    "callingCodes": ["+234"]
  }
]

GET /fx-rate?countryCode=XX

Get the FX rate between USD and the local currency for a country.

curl "https://api.toppa.cc/fx-rate?countryCode=NG"

{
  "rate": 1206,
  "currencyCode": "NGN"
}

GET /reputation

Get Toppa's on-chain reputation score from the ERC-8004 Reputation Registry.

Error Handling

All errors return a JSON body with an error field and an appropriate HTTP status code.

Error Response Format

{
  "error": "Human-readable error message",
  "code": "RELOADLY_ERROR_CODE"   // present for provider errors
}

HTTP Status Codes

StatusMeaningCommon Causes
200SuccessService executed, result in body
400Bad RequestMissing/invalid fields, amount out of range, invalid phone number, biller not found
402Payment RequiredNo X-PAYMENT header, or payment verification failed (wrong amount, expired tx, replay detected)
429Rate LimitedExceeded 10 requests per 5 minutes from the same payer address
500Server ErrorUpstream provider failure (Reloadly). Payment is auto-refunded.

Common Validation Errors

ErrorCauseFix
Could not detect operator for +234...Invalid phone number or unsupported operatorVerify the phone number and country code match
MTN Nigeria only accepts fixed amounts: 0.50, 1.00...Amount doesn't match FIXED denominationsUse GET /operators/:cc to see valid amounts
Biller ID 42 not found in NGWrong biller ID or country mismatchUse GET /billers/:cc to find valid billers
Gift card product 5678 not foundInvalid or delisted productSearch again with GET /gift-cards/:cc
Amount outside range 1.00-50.00 cUSDAmount exceeds operator/biller limitsCheck min/max in discovery response
Payment already usedTransaction hash was already submittedSend a new cUSD payment for a fresh tx hash

MCP Server

Toppa exposes 13 tools via the Model Context Protocol (MCP), allowing AI clients like Claude Desktop and Cursor to execute real-world payments.

Connection

Toppa's MCP server uses Streamable HTTP transport:

# Claude Desktop config (~/.claude/claude_desktop_config.json)
{
  "mcpServers": {
    "toppa": {
      "transport": "streamable-http",
      "url": "https://api.toppa.cc/mcp"
    }
  }
}

Available Tools

ToolTypeDescription
get_operatorsFreeList mobile operators by country code
detect_operatorFreeAuto-detect operator from phone number
get_billersFreeList utility billers by country (filterable by type)
get_gift_cardsFreeList gift card brands for a country
search_gift_cardsFreeSearch gift cards by brand name
get_promotionsFreeActive promotions for a country
get_countriesFreeAll supported countries
get_fx_rateFreeFX rate for a country
convert_currencyFreeConvert between cUSD and local currency
send_airtimePaidSend airtime (returns order for x402 payment)
send_dataPaidSend data bundle (returns order for x402 payment)
pay_billPaidPay utility bill (returns order for x402 payment)
buy_gift_cardPaidBuy gift card (returns order for x402 payment)
How paid tools work in MCP: Paid tools return a payment_required object with the price and recipient address. Your MCP client handles the on-chain payment, then the tool auto-completes the service execution.

A2A Protocol

Google's Agent-to-Agent protocol enables machine-to-machine task delegation. Send tasks to Toppa from other agents using JSON-RPC.

Endpoint

POST https://api.toppa.cc/a2a
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "id": "1",
  "params": {
    "task": {
      "id": "unique-task-id",
      "message": {
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "Send $5 airtime to +2348021234567 in Nigeria"
          }
        ]
      }
    }
  }
}

Task Lifecycle

MethodDescription
tasks/sendSubmit a new task. Returns task status + artifacts.
tasks/getCheck task status by ID.
tasks/cancelCancel a pending task.

Tasks that require payment return with status input-required and an order confirmation artifact. The calling agent must approve and pay before the task completes.

Agent Discovery

GET https://api.toppa.cc/.well-known/agent-card.json

Returns Toppa's agent card with capabilities, supported protocols, and on-chain registration info.

Agent Card & ERC-8004

Toppa is a registered on-chain agent on Celo with a verifiable identity and reputation score, following the ERC-8004 standard.

Agent Card

GET https://api.toppa.cc/.well-known/agent-card.json

{
  "name": "Toppa",
  "description": "AI agent for airtime, data, bills & gift cards",
  "url": "https://toppa.cc",
  "capabilities": {
    "mcp": "https://api.toppa.cc/mcp",
    "a2a": "https://api.toppa.cc/a2a",
    "x402": true
  },
  "registration": {
    "network": "celo",
    "standard": "ERC-8004",
    "agentId": 1870
  }
}

ERC-8004 Registration

Agent #1870 on the Celo blockchain. Provides:

  • On-chain identity — verifiable, immutable registration
  • Reputation score — computed from peer reviews and transaction history
  • Discoverability — other agents find Toppa through the registry

Verification Links

Project

About Toppa

Toppa is an autonomous AI agent that bridges the gap between cryptocurrency and everyday digital services. Built for people who need to send airtime, pay bills, and buy gift cards — but don't have access to traditional banking.

The Problem

Billions of people use mobile money and prepaid services daily. But buying airtime across borders, paying bills in different countries, or purchasing international gift cards requires navigating fragmented systems, currency exchanges, and KYC barriers.

The Solution

Toppa eliminates all of that. Two chat interfaces (Telegram + WhatsApp), one currency (cUSD), zero paperwork. Tell Toppa what you need in plain language — it figures out the operator, calculates the cost, and executes the transaction.

Key Differentiators

  • AI-first, not form-first — No dropdowns, no forms. Just natural language or voice notes.
  • Borderless by default — 170+ countries, 800+ operators, one interface.
  • Agent-native — Built from day one for both humans and AI agents.
  • Crypto-native payments — cUSD on Celo. Fast, cheap, global.
  • Multi-currency — Deposit CELO, USDC, USDT, or cEUR and auto-swap to cUSD via Uniswap V3.
  • Group wallets — Shared wallets with democratic poll-based governance. Configurable thresholds, admin bypass, key export.
  • Scheduled payments — Set up recurring airtime, bills, or gift cards. Heartbeat engine runs automatically with retry on failure.
  • Memory & personality — Learns your contacts, habits, and preferences. "Send airtime to my brother" just works.
  • Reports — PDF and Excel transaction statements. Works for personal and group wallets.
  • Identity verification — Self Protocol ZK proofs tied to passport/ID. No personal data stored. Higher spending limits.
  • Voice support — Send a voice note in English, French, Yoruba, or Swahili. Transcribed via Deepgram in under a second.
  • Open protocols — x402, MCP (13 tools), A2A. Any agent can integrate.
  • On-chain identity — ERC-8004 registered as Agent #1870 on Celo Mainnet.
  • Open source — MIT licensed, fully transparent.

Who It's For

  • Prepaid users in emerging markets — People who buy airtime, data, and pay bills daily but lack access to traditional banking.
  • Diaspora communities — Send airtime and pay bills for family back home without navigating foreign operator websites.
  • Groups and communities — Offices, friend circles, and families pooling money for shared expenses with transparent governance.
  • AI agent developers — Use Toppa as a tool via MCP, A2A, or x402 to give your agent real-world payment capabilities.

Architecture

Toppa uses LangGraph (StateGraph) for its AI agent loop — a structured agent ↔ tools cycle with conditional routing, payment short-circuits, and fidelity checks.

Core Engine

At the center is a LangGraph StateGraph with two nodes: Agent (LLM call) and Tools (execute tool calls). The agent node decides whether to call tools or return a final response. When a paid tool returns a payment_required payload, the loop short-circuits immediately — no extra LLM call needed.

The system includes automatic fallback (Gemini 2.0 Flash → Llama 3.3 70B), post-response fidelity checks, and an iteration cap to prevent runaway loops.

Protocol Stack

Telegram Direct human users
WhatsApp Direct human users
A2A Agent-to-Agent (JSON-RPC)
MCP 13 tools via Streamable HTTP
x402 Pay-per-call REST API
Celo cUSD payments + ERC-8004 identity

Safety Model

Paid tools (airtime, data, bills, gift cards) never execute actual purchases inside the LLM loop. Instead, they return a payment_required JSON payload with an order confirmation. The actual payment and fulfillment happen externally:

  • Telegram — wallet deduction after user confirms via inline buttons
  • WhatsApp — wallet deduction after user confirms
  • x402 — on-chain payment verification before fulfillment
  • MCP/A2A — order confirmation artifact returned for approval

Group Governance

Group wallet spending uses a poll-based governance model:

  • AI agent creates a spending proposal via group_create_poll tool
  • Native platform polls (Telegram or WhatsApp) are sent to the group
  • Members vote; action executes when threshold is met
  • Polls auto-expire after 24 hours

Roadmap

What's been built, what's in progress, and what's coming next. Toppa is a live product with real users — this roadmap reflects where we are and where we're going.

Shipped
  • Telegram bot with natural language processing
  • WhatsApp bot with full feature parity
  • Airtime top-ups for 800+ operators in 170+ countries
  • Data bundle purchases with automatic operator detection
  • Utility bill payments (electricity, internet, TV, water)
  • Gift card purchases from 300+ brands (Amazon, Steam, Netflix, PlayStation, etc.)
  • LangGraph-powered AI agent with 34 tools
  • Group wallets with democratic poll governance
  • Group contribution tracking with private DM receipts
  • Configurable poll thresholds and expiry times
  • Admin bypass, key export, and fund withdrawal for group wallets
  • Multi-currency deposits (cUSD, CELO, USDC, USDT, cEUR) + auto-swap via Uniswap V3
  • PDF and Excel expenditure reports and statements
  • Group transaction reports with full transparency
  • Smart memory — learns contacts, operators, preferences, and habits
  • Heartbeat engine with proactive alerts (upcoming bills, low balance)
  • Scheduled and recurring payments with automatic retry on failure
  • x402 payment protocol for all paid endpoints
  • MCP server with 13 tools for agent integration
  • Google A2A protocol support
  • ERC-8004 on-chain agent registration (Agent #1870 on Celo Mainnet)
  • Free discovery APIs (operators, billers, countries, gift cards)
  • Voice note transcription via Deepgram (English, French, Yoruba, Swahili)
  • @mention filtering in groups — context-aware, ignores unrelated messages
  • AES-256-GCM wallet encryption at rest
  • Identity verification via Self Protocol (ZK proofs, no personal data stored)
  • Tiered spending limits ($20/day default → $200/day verified)
  • Multilingual support (English, French, Yoruba, Swahili)
In Progress
  • Gift card sell pipeline — sell unused gift cards for cUSD (Cardtonic integration)
  • Cross-chain bridge for multi-network deposits (Ethereum, Base, Arbitrum → Celo)
  • Transaction history search and filtering
Near Term
  • Celo MiniPay deep integration — use Toppa directly inside MiniPay
  • Multi-agent orchestration — other AI agents can delegate tasks to Toppa
  • Merchant tools — bulk airtime distribution, business accounts, usage dashboards
  • SDK for third-party developers — npm package to embed Toppa's capabilities
  • Referral system — earn cUSD by inviting users
  • In-chat onboarding tutorial for new users
Long Term
  • P2P transfers — send cUSD to other Toppa users by name or phone number
  • Savings goals — set targets, auto-contribute from balance
  • Micro-lending — borrow small amounts against transaction history
  • More chat platforms — Discord, LINE, Facebook Messenger
  • Fiat on/off ramps — buy cUSD with mobile money (M-Pesa, MTN MoMo)
  • Decentralized governance — community voting on feature priorities
  • Regional expansion — Arabic, Portuguese, Hindi language support
  • Physical goods — top up electricity meters, buy e-vouchers for groceries

Vision

Toppa's goal is to become the default way people in emerging markets interact with digital services. No apps to download, no forms to fill, no banks needed. Just a chat message and a stablecoin wallet. We believe AI agents on public blockchains are the infrastructure layer that makes borderless, instant, low-cost financial services possible for everyone — not just people with bank accounts and credit cards.