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)
/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"
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
| Command | Who | Description |
|---|---|---|
/group enable | Anyone (first = admin) | Create the group wallet |
/group | Anyone | View balance, address, members, recent activity |
/contribute <amount> | Anyone | Transfer cUSD from personal to group wallet |
/group_withdraw <addr> <amt> | Admin only | Withdraw from group to external address |
/threshold <0-100> | Admin only | Set 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
| Status | Daily Limit | How to Get |
|---|---|---|
| Unverified | $20/day | Default for all new users |
| Self-Verified | $200/day | Complete the /verify flow |
How to Verify
- Type
/verifyin Telegram or WhatsApp - Tap the verification link — the Self app opens
- Scan your passport with NFC (~30 seconds)
- 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
| Detail | Value |
|---|---|
| Self Agent ID | #48 (Celo Sepolia) |
| Agent Address | 0x9480a88916074D9B2f62c6954a41Ea4B9B40b64c |
| Scope | toppa-verify |
| Callback Endpoint | POST /api/verify |
| Status Endpoint | GET /api/verify/status |
| SDK | @selfxyz/core |
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 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
| Detail | Value |
|---|---|
| Service fee | 1.5% of product cost |
| Payment currency | cUSD (Celo Dollar) or USDC on Celo |
| Payment network | Celo Mainnet |
| Transaction max age | ~1 hour (720 blocks) |
| Amount tolerance | 0.2% (for gas rounding) |
| Replay protection | Each tx hash can only be used once |
| Auto-refund | If service fails after payment, cUSD is returned to payer |
| Rate limit | 10 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
- Request — Send a normal POST request to a paid endpoint (no headers needed).
- 402 Response — Toppa returns HTTP 402 with: price in cUSD, recipient wallet address, and network.
- Pay on-chain — Transfer the exact cUSD amount to the recipient address on Celo.
- Retry with proof — Resend the same request with the tx hash in the
X-PAYMENTheader. - Fulfillment — Toppa verifies the payment on-chain, executes the service, and returns the result.
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
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Recipient phone number (local or international format) |
countryCode | string | Yes | ISO 3166-1 alpha-2 country code (e.g. NG, KE, GH) |
amount | number | Yes | Amount 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
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Recipient phone number |
countryCode | string | Yes | ISO country code |
amount | number | Yes | Amount in cUSD |
operatorId | number | Yes | Operator 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"
}
}
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
| Field | Type | Required | Description |
|---|---|---|---|
billerId | number | Yes | Biller ID (from GET /billers/:cc) |
accountNumber | string | Yes | Meter number, smartcard number, or account ID |
amount | number | Yes | Amount in cUSD. Must be within the biller's min/max range. |
countryCode | string | Yes | ISO 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"
}
}
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
| Field | Type | Required | Description |
|---|---|---|---|
productId | number | Yes | Gift card product ID (from discovery endpoints) |
amount | number | Yes | Amount in cUSD. FIXED products require an exact denomination; RANGE products accept any value within min/max. |
recipientEmail | string | Yes | Email address for delivery (also returned in response) |
quantity | number | No | Number 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"
}
}
"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 Param | Values |
|---|---|
type | ELECTRICITY_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
| Status | Meaning | Common Causes |
|---|---|---|
200 | Success | Service executed, result in body |
400 | Bad Request | Missing/invalid fields, amount out of range, invalid phone number, biller not found |
402 | Payment Required | No X-PAYMENT header, or payment verification failed (wrong amount, expired tx, replay detected) |
429 | Rate Limited | Exceeded 10 requests per 5 minutes from the same payer address |
500 | Server Error | Upstream provider failure (Reloadly). Payment is auto-refunded. |
Common Validation Errors
| Error | Cause | Fix |
|---|---|---|
Could not detect operator for +234... | Invalid phone number or unsupported operator | Verify the phone number and country code match |
MTN Nigeria only accepts fixed amounts: 0.50, 1.00... | Amount doesn't match FIXED denominations | Use GET /operators/:cc to see valid amounts |
Biller ID 42 not found in NG | Wrong biller ID or country mismatch | Use GET /billers/:cc to find valid billers |
Gift card product 5678 not found | Invalid or delisted product | Search again with GET /gift-cards/:cc |
Amount outside range 1.00-50.00 cUSD | Amount exceeds operator/biller limits | Check min/max in discovery response |
Payment already used | Transaction hash was already submitted | Send 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
| Tool | Type | Description |
|---|---|---|
get_operators | Free | List mobile operators by country code |
detect_operator | Free | Auto-detect operator from phone number |
get_billers | Free | List utility billers by country (filterable by type) |
get_gift_cards | Free | List gift card brands for a country |
search_gift_cards | Free | Search gift cards by brand name |
get_promotions | Free | Active promotions for a country |
get_countries | Free | All supported countries |
get_fx_rate | Free | FX rate for a country |
convert_currency | Free | Convert between cUSD and local currency |
send_airtime | Paid | Send airtime (returns order for x402 payment) |
send_data | Paid | Send data bundle (returns order for x402 payment) |
pay_bill | Paid | Pay utility bill (returns order for x402 payment) |
buy_gift_card | Paid | Buy gift card (returns order for x402 payment) |
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
| Method | Description |
|---|---|
tasks/send | Submit a new task. Returns task status + artifacts. |
tasks/get | Check task status by ID. |
tasks/cancel | Cancel 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
- View on Agentscan
- View on 8004scan
- Registration JSON
- View on Karma
- Self Protocol — Agent #48 (
0x9480a889...0b64c)
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
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_polltool - 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.
- 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)
- 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
- 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
- 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.
Links & Resources
Everything you need to explore, integrate, or contribute.