app.iomarkets/topup

Official9 tools

by iomarkets

Travel eSIMs and mobile top-ups paid in USDC via x402. A technology demonstration, limited pilot.

app.iomarkets/topup — Model Context Protocol (MCP) Server

This MCP server, app.iomarkets/topup, provides access to travel eSIMs for 197 destinations and airtime top-ups in 150+ countries. Payments are handled in USDC via x402. The server exposes 8 tools to support these top-up workflows.

🛠️ Key Features

Travel eSIMs for 197 destinations
Airtime top-ups in 150+ countries
USDC payments via x402
8 tools available

🚀 Use Cases

Adding travel eSIM data for supported destinations
Performing mobile airtime top-ups across supported countries

⚡ Developer Benefits

Focused tool set (8 tools) for eSIM and airtime top-ups
Consistent payment method (USDC via x402)

⚠️ Limitations

Limited to eSIM destinations and airtime top-up coverage within the stated counts (197 destinations, 150+ countries).

Captured live from the server via tools/list.

lookup_phone

Identify the country and mobile operator of a phone number and list the top-up offers available for it. Free. The operator is DETECTED from the number range and is a guess: MVNOs (Tesco Mobile, Giff Gaff, Lebara, Voxi, Sky…) resolve to the host network they ride on. Read the detected brand back to the human and have them confirm it before buying, and use `other_brands` to correct it — a voucher bought for the wrong network delivers successfully and cannot be redeemed or refunded.

Parameters1

phone

string

required

E.164, e.g. +919876543210

Raw schema

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "description": "E.164, e.g. +919876543210"
    }
  },
  "required": [
    "phone"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_offers

Browse purchasable offers: mobile top-ups, travel eSIMs, prepaid bills, or international payment corridors (bank / mobile money / UPI) for a country. Free. Prices shown are indicative; the quote fixes them.

Parameters5

type	string	required	payout = international payment (bank / mobile money / UPI)
country	string	optional	ISO-3166 alpha-2, e.g. IN
brand	string	optional
limit	integer	optional	page size, default 100; 0 means all
offset	integer	optional	use next_offset from the previous page

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "topup",
        "esim",
        "bill",
        "payout"
      ],
      "description": "payout = international payment (bank / mobile money / UPI)"
    },
    "country": {
      "description": "ISO-3166 alpha-2, e.g. IN",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "brand": {
      "type": "string"
    },
    "limit": {
      "description": "page size, default 100; 0 means all",
      "type": "integer",
      "minimum": 0,
      "maximum": 500
    },
    "offset": {
      "description": "use next_offset from the previous page",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "type"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

quote

Lock a price (10 minutes) for one purchase. Returns quoteId, exact USDC price and what will be delivered. Free. ALWAYS show the human the price and the recipient before buying.

Parameters9

type	string	required
offerId	string	required
phone	string	optional	recipient phone for topup/bill (E.164)
amount	number	optional	for range offers: amount in the recipient's local currency
iccid	string	optional	existing eSIM to top up (optional)
fields	object	optional	bill-pay / payout recipient fields the offer lists in requiredFields (account_number, bank_code, full_name, vpa, iban…)
sender	object	optional	payouts only: the principal (legal name + country); reference = partner KYC id, required above $100/day
payer	string	optional	the Algorand address you will pay from (required for payout compliance when this server holds no wallet)
ref	string	optional	referrer's Algorand address — earns a share of margin if the order is delivered (GET /v1/referrals)

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "topup",
        "esim",
        "bill",
        "payout"
      ]
    },
    "offerId": {
      "type": "string"
    },
    "phone": {
      "description": "recipient phone for topup/bill (E.164)",
      "type": "string"
    },
    "amount": {
      "description": "for range offers: amount in the recipient's local currency",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "iccid": {
      "description": "existing eSIM to top up (optional)",
      "type": "string"
    },
    "fields": {
      "description": "bill-pay / payout recipient fields the offer lists in requiredFields (account_number, bank_code, full_name, vpa, iban…)",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "sender": {
      "description": "payouts only: the principal (legal name + country); reference = partner KYC id, required above $100/day",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "reference": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "country"
      ]
    },
    "payer": {
      "description": "the Algorand address you will pay from (required for payout compliance when this server holds no wallet)",
      "type": "string"
    },
    "ref": {
      "description": "referrer's Algorand address — earns a share of margin if the order is delivered (GET /v1/referrals)",
      "type": "string"
    }
  },
  "required": [
    "type",
    "offerId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_pay_link

Create a checkout link a HUMAN pays from their own Algorand wallet (Pera). Use this when you have no wallet, or when the person should approve and pay themselves: they open the link, see the exact price, sign in their wallet, and the result (the eSIM QR code, or the top-up confirmation) appears on the page. You never hold a key. A top-up link can be paid by anyone — send it to family as 'top up my phone'. An eSIM link delivers to whoever pays. Free. Add `ref` (your Algorand address) to earn a share of margin on each delivered order.

Parameters8

type	string	required
offerId	string	required
phone	string	optional	topup only: recipient phone, E.164
amount	number	optional	for range top-up offers: amount in local currency
note	string	optional	shown on the link page, e.g. 'Your Tokyo trip data'
ref	string	optional	your Algorand address, to earn referral share
max_uses	integer	optional	0 = reusable until expiry; default 1 for topup, 0 for esim
ttl_hours	integer	optional	default 168 (7 days)

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "topup",
        "esim"
      ]
    },
    "offerId": {
      "type": "string"
    },
    "phone": {
      "description": "topup only: recipient phone, E.164",
      "type": "string"
    },
    "amount": {
      "description": "for range top-up offers: amount in local currency",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "note": {
      "description": "shown on the link page, e.g. 'Your Tokyo trip data'",
      "type": "string",
      "maxLength": 140
    },
    "ref": {
      "description": "your Algorand address, to earn referral share",
      "type": "string"
    },
    "max_uses": {
      "description": "0 = reusable until expiry; default 1 for topup, 0 for esim",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
    },
    "ttl_hours": {
      "description": "default 168 (7 days)",
      "type": "integer",
      "minimum": 1,
      "maximum": 720
    }
  },
  "required": [
    "type",
    "offerId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

buy

Get the x402 payment challenge for a quote. This hosted server holds no wallet, so it does NOT spend your money: it returns the exact amount, asset, payTo address and facilitator for you to pay from your own Algorand wallet, then you POST the quote again with your payment signature. Requires prior human confirmation of the quote.

Parameters1

quoteId

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "quoteId": {
      "type": "string"
    }
  },
  "required": [
    "quoteId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

order_status

Check an order. Poll every ~3 s until `terminal` is true: delivered (confirmation + signed receipt), refunded (refund txid + signed receipt) or refund_failed.

Parameters1

orderId

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string"
    }
  },
  "required": [
    "orderId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

verify_receipt

Verify an ed25519-signed receipt: the signature, and — unless you pass onChain:false — both txids against an Algorand indexer. Give it an orderId to check one of this service's own orders, or a receipt object to check ANY receipt in this format, including one issued by another server.

Parameters3

orderId	string	optional	an order on this service
receipt	any	optional	a receipt {payload, signature}, or an order response containing one
onChain	boolean	optional	confirm the txids on chain; default true

Raw schema

{
  "type": "object",
  "properties": {
    "orderId": {
      "description": "an order on this service",
      "type": "string"
    },
    "receipt": {
      "description": "a receipt {payload, signature}, or an order response containing one"
    },
    "onChain": {
      "description": "confirm the txids on chain; default true",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

fx

Indicative USDC → local-currency rate at our sale price, with an estimate for an amount. The quote is the binding price.

Parameters3

to	string	required	ISO-4217, e.g. INR
amount	number	optional
type	string	optional	what the rate is for; default payout

Raw schema

{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "description": "ISO-4217, e.g. INR"
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "type": {
      "description": "what the rate is for; default payout",
      "type": "string",
      "enum": [
        "topup",
        "bill",
        "payout"
      ]
    }
  },
  "required": [
    "to"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ledger

Public delivery ledger: totals, delivered-or-refunded %, volume, countries, recent orders.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Install

Tools (9)

lookup_phonelist_offersquotecreate_pay_linkbuyorder_statusverify_receiptfx

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://iomarkets.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "topup": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://iomarkets.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

app.iomarkets/topup — Model Context Protocol (MCP) Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

lookup_phone

list_offers

quote

create_pay_link

buy

order_status

verify_receipt

fx

ledger

Install

Remote endpoint

Related servers