esimker for AI agents

Machine-readable entry points

MCP server

The same calls as tools, for clients that speak the Model Context Protocol: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and the rest. Streamable HTTP, stateless, no OAuth. The catalogue, the checkout flow and minting a wallet need no credentials at all; the wallet tools read the wallet code from an Authorization: Bearer header. The custom connectors of Claude.ai and Claude Desktop cannot send that header yet, so the wallet tools work from Claude Code, Cursor, VS Code and agents built on the SDKs.

# Claude Code
claude mcp add --transport http esimker https://esimker.com/api/mcp
claude mcp add --transport http esimker https://esimker.com/api/mcp --header "Authorization: Bearer <wallet code>"

# Cursor, VS Code, Windsurf and other JSON configs
{ "mcpServers": { "esimker": { "url": "https://esimker.com/api/mcp",
                               "headers": { "Authorization": "Bearer <wallet code>" } } } }

# Claude Desktop and claude.ai: Settings → Connectors → Add custom connector → the URL above
# (a custom connector sends no headers: the catalogue, the checkout flow and create_wallet
#  work there; the wallet tools need a client that can send the Authorization header)

The server's instructions carry the rules below, so a model that connects already knows to confirm the price with the person, to keep the wallet code and the order token private and to reuse client_ref on a retry. Every tool goes through the same API as this page describes: the limits, the sanctions check and the prices are the same.

Buy for a person: the storefront flow

Use this when a human is on the other end and pays themselves. The agent picks the plan, creates the order and hands over the checkout link; the gateway, card or crypto, does the rest. No key is needed.

1. 1
   GET /api/catalog

   Destinations on sale: slug, min_retail, plan_count and the name in 17 languages (names).

2. 2
   GET /api/catalog/{slug}

   The plans of one destination. plans[].id is the plan_id; each plan carries gb, days, retail, daily_unlimited, location_codes and networks.

3. 3
   GET /api/payment-methods

   Which of crypto, card and wallet are open right now.

4. 4
   POST /api/orders

   Creates the order and its checkout; the response is the order token and checkout_url. Hand checkout_url to the person: the gateway takes the card or the coins.

5. 5
   GET /api/orders/{token}

   Poll until status is ready (pending → paid → provisioning → ready). The payload then carries esim.activation_code, esim.iccid, esim.smdp and esim.matching_id.

POST /api/orders
{ "plan_id": 1176, "payment_method": "crypto", "email": "[email protected]", "lang": "en" }

→ { "token": "k3Jd…", "checkout_url": "https://…/invoice/…" }

GET /api/orders/k3Jd…
→ { "status": "ready", "amount_usd": "8.99",
    "plan": { "name": "Turkey 10GB 30Days", "gb": 10, "days": 30, "daily_unlimited": false, "dest_code": "TR" },
    "esim": { "iccid": "89…", "smdp": "rsp.example.com", "matching_id": "ABC-123",
              "activation_code": "LPA:1$rsp.example.com$ABC-123", "status": "RELEASED" } }

• email is optional; when given, the eSIM is also emailed. lang picks the language of the order page and of that email (one of the 17 storefront locales).
• The person can open the order page themselves: https://esimker.com/order?t=… shows the same order with the QR code and the install steps.
• Top-ups: GET /api/topups/{iccid} lists what fits an eSIM we issued, then POST /api/orders with that plan_id and topup_iccid. Remaining data: GET /api/usage/{iccid}.

Buy autonomously: the prepaid wallet

For an agent that has to complete a purchase with nobody at the checkout. A prepaid wallet with no account behind it: the agent mints it, funds it in crypto at an address the API hands back, and every order is charged to the balance and issued at once. Retail prices, 3% cashback on every purchase, a bonus on larger crypto deposits.

1. 1
   POST /api/wallet

   { "accept_terms": true } mints a wallet and returns its secret once: code (32 hex characters) and the same secret as a 12-word phrase. Save the code: it is the only way in, there is no recovery. Rate-limited and geo-blocked like checkout.

2. 2
   X-Wallet-Code: …

   Every wallet request carries the code (the phrase is accepted too). GET /api/wallet is the summary: balance, the deposit rules that apply now, the ledger, the orders with their links.

3. 3
   POST /api/wallet/deposits

   { "amount_usd": 20, "payment_method": "crypto", "currency": "USDTTRC" } opens a top-up. With a currency the answer carries pay: the address, the exact amount in the coin (network fee included) and the address's expiry, about 15 minutes. Send exactly that amount; checkout_url is the hosted page for a person.

4. 4
   GET /api/wallet/deposits/{token}

   Poll until status is paid; the balance moves the moment the network confirms. First deposit from $10, later ones from $1, up to $1000; crypto deposits earn +2% from $25, +3% from $50, +5% from $100.

5. 5
   POST /api/orders

   { "plan_id": 1176, "payment_method": "wallet", "client_ref": "trip-1" } charges the balance and issues at once: no invoice, the order comes back paid, 3% cashback lands on the wallet. client_ref is your own reference: a repeat with the same value returns the same order instead of charging twice. 402 when the balance is short.

6. 6
   GET /api/orders/{token}

   ready with esim.activation_code, usually within a minute.

POST /api/wallet
{ "accept_terms": true }
→ { "code": "3f9a2c1d…", "phrase": "abandon ability … about", "wallet": { "ref": "W-3F9A2C1D", "balance_usd": "0.00", … } }

POST /api/wallet/deposits
X-Wallet-Code: 3f9a2c1d…
{ "amount_usd": 20, "payment_method": "crypto", "currency": "USDTTRC" }
→ { "deposit": { "token": "d7Kq…", "status": "pending", "amount_usd": "20.00", "bonus_usd": "0.00" },
    "checkout_url": "https://gopay.paykilla.com/…",
    "pay": { "currency": "USDTTRC", "network": "Tron", "address": "TCnc…", "amount": "21.815",
             "expires_at": "2026-09-04T12:15:00Z", "confirmations": 19 } }

POST /api/orders
X-Wallet-Code: 3f9a2c1d…
{ "plan_id": 1176, "payment_method": "wallet", "client_ref": "trip-1" }
→ { "token": "p8Qs…", "checkout_url": "https://esimker.com/order?t=p8Qs…" }

If issuing fails for good (failed_provisioning) the wallet is refunded by hand: send us the order token with the wallet's ref, never the code. The same wallet works on the wallet page and in the Telegram bot, so a person can pick up what an agent bought.

Buying through the API, the MCP server or a wallet for your own use, or for the person you act for, is within the acceptable use policy; automated bulk purchasing for resale is not. Partners reselling under their own brand have a separate reseller API: an API key, a discount off retail, white-label delivery. Keys are issued by hand; write to [email protected] with a line about what you are building.

Rules for agents

• Confirm the destination, the plan and the price with the person before you pay or charge a wallet. An eSIM that has not been installed can be refunded in full; an installed or used one is consumed (see the refund policy).
• The order token is the only key to the eSIM. Show the order link to the buyer; do not log it, post it or leave it in a shared context. The activation code is a secret for the same reason: it installs the profile on whichever device scans it first.
• Daily Unlimited plans (daily_unlimited: true) are priced per day: retail is the daily rate, and the order takes period_num, the number of days (1–365, default 7). The amount is the rate times the days.
• When the person visits several countries, check location_codes on the plan: a regional plan lists every country it covers.
• The wallet code is a bearer secret with no recovery: keep it where you keep credentials, never put it in a URL. A wallet balance is spent on eSIMs and never paid back out.
• Retries: reuse client_ref on a wallet purchase; on the storefront flow do not create a second order while the first checkout is open.
• Limits: 10 orders per minute per IP on the storefront flow. POST /api/orders answers 403 from embargoed jurisdictions (sanctions); tell the person instead of retrying.
• We sell data only: no phone numbers, no SMS, no voice. Coverage is 38 destinations, the catalogue is the list.

The fine print: terms, refund policy, acceptable use.