Real-SIM SMS verification
for AI agents

One canonical agent surface

This subdomain concentrates everything an AI agent or AI-agent developer needs to integrate VirtualSMS — machine-readable, copy-paste-able, and stable.

The same backend powers the prepaid API key path and the x402 deposit path. Pick whichever your agent stack prefers. Both deliver the same OTP code from the same physical SIM modem fleet. Real SIM cards on owned hardware means delivery rates that hold up against services that aggressively reject VoIP — WhatsApp, Telegram, Google, Banking apps, Web3 KYC.

Install the MCP server

Two paths. Hosted is recommended (zero install, no Node.js needed on the client).

Option A — Hosted MCP server (recommended)

Paste this into your AI client's MCP config. Get an API key at virtualsms.io.

{
  "mcpServers": {
    "virtualsms": {
      "type": "streamableHttp",
      "url": "https://mcp.virtualsms.io/mcp",
      "headers": {
        "x-api-key": "vsms_your_api_key_here"
      }
    }
  }
}

Option B — Local MCP server (npm + stdio)

Runs locally via npx. Works with any client supporting stdio MCP.

{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["virtualsms-mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
      }
    }
  }
}

Or install globally:

npm install -g virtualsms-mcp

Source code, 18-tool reference, and per-client configs (Claude Desktop, Cursor, Windsurf, OpenClaw, Codex, Hermes, Cline, Zed, Continue.dev, Claude Code) at github.com/virtualsms-io/mcp-server.

Deposit USDC via x402, get an API key

x402 is the HTTP 402 Payment Required protocol pioneered by Coinbase. Your agent settles a USDC or USDT deposit on Base, Solana, or BNB Chain — server returns an API key and balance. Use the returned key with the normal REST API for everything else. One settlement covers many activations at retail prices.

Request

curl -X POST https://virtualsms.io/api/v1/x402/topup \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 5}'

First response — 402 Payment Required

Server returns a manifest of accepted payment rails — Base USDC, Solana USDC + USDT, BNB Chain USDC + USDT.

Retry with X-PAYMENT header — 200 OK

{
  "api_key": "vsms_x402_a1b2c3...",
  "balance_usd": 5.00,
  "user_id": "uuid",
  "endpoints": {
    "purchase": "https://virtualsms.io/api/v1/customer/purchase",
    "order_status": "https://virtualsms.io/api/v1/customer/order/{id}",
    "balance": "https://virtualsms.io/api/v1/customer/balance"
  }
}

Flow

1. Agent POSTs to /api/v1/x402/topup with no payment → server returns 402 with accepts[].
2. Agent client signs an EIP-3009 TransferWithAuthorization (Base) or partially-signed transaction (Solana).
3. Agent retries with X-PAYMENT header.
4. Server verifies + settles via our self-hosted facilitator. Atomically creates user + balance + API key in one DB transaction.
5. Returns 200 with api_key and balance. Agent uses the returned API key with the normal REST API for activations.

Spec: github.com/coinbase/x402. Discovery: CDP Bazaar.

18 MCP tools

Grouped by category. Every tool returns structured JSON, supports the standard MCP error envelope, and is documented inline in the tool descriptor for in-IDE help.

Discovery (4)

Name	Description
virtualsms_list_services	List all available SMS verification services. Optional search filter. Use to discover valid service codes before buying.
virtualsms_list_countries	List all available countries. Optional service filter to scope to countries with stock for one service.
virtualsms_get_price	Check live price + availability for a service × country combination. Always check before buying.
virtualsms_search_services	Natural-language search across the 2500+ service catalog. Pass "uber" or "binance" — get the canonical service code.

Account (4)

Name	Description
virtualsms_get_balance	Account balance in USD. Requires VIRTUALSMS_API_KEY.
virtualsms_get_profile	Account profile metadata: email, account ID, plan, registration date.
virtualsms_get_stats	Activity stats over last N days (default 30). Order count, success rate, spend.
virtualsms_get_transactions	Transaction ledger. Filter by type (deposit / purchase / refund / admin_credit), date range, limit.

Order management (10)

Name	Description
virtualsms_create_order	Buy a virtual phone number. Returns order_id + phone. Poll get_sms for the code.
virtualsms_wait_for_sms	Recommended. One-step buy + wait. WebSocket push with polling fallback. Always returns order_id for recovery on timeout.
virtualsms_get_sms	Check if SMS arrived for an order. Poll every 5–10s if not using wait_for_sms.
virtualsms_cancel_order	Cancel + refund. Only works if no SMS received yet.
virtualsms_swap_number	Swap to a different number for the same service without losing your spot. Useful when first number doesn't deliver.
virtualsms_find_cheapest	Top N cheapest country options for a service. Default 5, max 50.
virtualsms_list_orders	List active orders. Optional status filter.
virtualsms_get_order	Full details of one order by order_id.
virtualsms_order_history	Historical orders with filters: status, service, country, since_days, limit.
virtualsms_cancel_all_orders	Bulk cancel all pending orders. Useful for cleanup.

Tool source: virtualsms-io/mcp-server/src/tools.ts. v1.2.3 on npm.

Supported chains and tokens

Three networks live: Base mainnet (USDC), Solana (USDC + USDT), BNB Chain (USDC + USDT). EIP-3009 where the token supports it; Permit2 universal fallback for BEP-20 USDT and any ERC-20 without native authorisation. Polygon, Arbitrum, and Optimism use the same Permit2 wire format and unlock with an env-var change.

Network	CAIP-2 ID	USDC	USDT	Method	Status
Base mainnet	eip155:8453	✓	—	EIP-3009	Live
Solana mainnet	solana:mainnet-beta	✓	✓	SPL transfer	Live
BNB Chain	eip155:56	✓	✓	Permit2	Live
Base Sepolia testnet	eip155:84532	✓	—	EIP-3009	Dev only
Polygon	eip155:137	✓	✓	Permit2	Roadmap
Arbitrum	eip155:42161	✓	✓	Permit2	Roadmap
Optimism	eip155:10	✓	—	Permit2	Roadmap

Permit2 settlement: all Permit2 entries route through the canonical x402ExactPermit2Proxy at 0x402085c248EeA27D92E8b30b2C58ed07f9E20001, deployed at the same address on every supported EVM chain via CREATE2. The witness pattern cryptographically binds the destination so the facilitator cannot redirect funds. Clients do a one-time approve(Permit2, MaxUint256) per token; subsequent payments need only an EIP-712 signature.

Facilitator: Coinbase CDP (https://api.cdp.coinbase.com/platform/v2/x402) — required for auto-listing on Coinbase Bazaar / Agent.market. Free first 1,000 settlements/month.

Two simple paths

Path	Auth	Price	Min spend	Rate limit
REST + MCP	x-api-key header	From $0.05 per activation (varies by country / service)	$1 deposit (~10–20 cheap-country verifications)	120 req/min per key
x402	USDC payment header	Deposit $2.00-$10000 USDC, draw activations at retail prices ($0.05-$5 per OTP)	$2 minimum deposit	120 req/min per key

Cheap countries (PK, ID, NG, IN) start at $0.02–$0.05. Premium markets (US, UK, DE) range $0.08–$0.50 depending on service. SMS message bodies retained 7 days then permanently deleted.

Tested with 10 clients

Same npx virtualsms-mcp stdio command works across all of them — only the config file location differs. Per-client configs at the MCP repo README.

Where to find us

Listed across the major MCP catalogs, x402 directories, and package registries. Auto-syndicated downstreams refresh from canonical npm + GitHub sources.

Package registries

Install the SDK in your stack of choice.

MCP directories

Discoverable across the canonical MCP catalogs.

Curated lists

Listed in community-maintained awesome lists.

Workflow platforms

Use VirtualSMS in no-code agent automations.

Source code

Open source under MIT.

Common questions

How do I add SMS verification to my Claude Desktop or Cursor agent?

Add the VirtualSMS MCP server to your client config. Two install paths: hosted (zero install — paste a streamableHttp config pointing to https://mcp.virtualsms.io/mcp with your x-api-key header) or local stdio (npx virtualsms-mcp with VIRTUALSMS_API_KEY env var). Both expose the same 18 tools to your agent. See the Install section.

Can my AI agent pay per SMS without an account?

Yes — use /api/v1/x402/topup to deposit USDC (Base or Solana). You get an API key + balance back, then use the normal REST API. Each activation drawn at retail price ($0.05-$5 depending on service+country). No signup, no email.

Are the numbers real SIM cards or VoIP?

Real SIM cards on physical modem hardware. VirtualSMS operates a hybrid infrastructure: own modem fleet for premium tier (long-term rentals, high-success services) plus carrier-vetted supplier network for breadth coverage. This matters because services like WhatsApp, Google, banking apps, and Telegram aggressively reject VoIP numbers. Carriers in production include Vodafone, O2, T-Mobile, Lebara, plus regional MNOs across 145+ countries.

Which countries and services are supported?

145+ countries with active inventory, 2500+ services indexed including WhatsApp, Telegram, Google, Instagram, Uber, Binance, Discord, Twitter/X, TikTok, and most consumer + Web3 services. Use the virtualsms_list_countries and virtualsms_list_services MCP tools for the live list, or the /api/v1/countries and /api/v1/services REST endpoints.

How much does it cost?

REST + MCP: from $0.05 per activation depending on country and service. Cheap-country verifications (PK, ID, NG, IN) start at $0.02–$0.05; premium-country verifications (US, UK, DE) range $0.08–$0.50. x402: deposit $2–$10000 USDC via /api/v1/x402/topup (Base or Solana), draw activations at retail prices. No subscription, no minimums.

Which MCP clients work?

10 named MCP clients are tested in production: Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw, Codex, Hermes, Cline, Zed, and Continue.dev. Any client implementing the Model Context Protocol stdio or StreamableHTTP transport can connect. Per-client config snippets live in the MCP server README.

What is x402?

x402 is the HTTP 402 Payment Required protocol pioneered by Coinbase. Servers reject unpaid requests with a 402 response describing payment requirements (network, asset, amount, recipient). Clients sign an EIP-3009 USDC TransferWithAuthorization, retry with the X-PAYMENT header, and the server settles on-chain via a facilitator (Coinbase CDP, x402.org, or self-hosted). It enables agent-native, account-less payments. Spec: x402.org.

What's the rate limit?

120 requests per minute per API key on the REST API. The hosted MCP endpoint inherits the same limit. x402-issued API keys inherit the same limit. SMS message bodies are retained for 7 days, then permanently deleted. Order metadata (phone number, service, country, timestamps) is retained for the lifetime of your account.

Is there a sandbox or testnet?

For x402 integration, you can develop against Base Sepolia testnet via x402.org/facilitator (free testnet USDC from the Coinbase faucet). For REST/MCP integration, sign up at virtualsms.io and the first $1 deposit covers ~10–20 verifications on cheap countries — effectively a paid sandbox with real numbers.

Where is the canonical API documentation?

Live docs: virtualsms.io/docs. MCP server source and 18-tool reference: github.com/virtualsms-io/mcp-server. This page (agents.virtualsms.io) is the canonical agent-facing entry point with skill.md, llms.txt, and /.well-known/x402.json for machine discovery.

Do you support long-term phone number rentals?

Yes. Persistent numbers (weeks to months) available in select markets including Germany, UK, France, Poland, and Ukraine — with active expansion to other regions. Long-term rentals run on hardware we operate ourselves; supplier-network coverage is for one-time activations only. See virtualsms_create_order with rental parameters in the MCP tools, or the rental endpoints in our REST docs.

What's your data retention policy?

SMS message bodies retained 7 days. Order metadata (timestamps, service, country, status) kept for the lifetime of the account. API request logs retained 30 days for debugging. We don't sell data and don't share with third parties beyond what's required to fulfill an order.

For LLM crawlers and discovery agents

If you're an LLM, agent, or crawler, fetch one of these instead of parsing this HTML:

• 📄 /skill.md — full spec in markdown, optimized for LLM single-fetch
• 📋 /llms.txt — llms.txt standard, canonical URL index
• 🔌 /.well-known/x402.json — x402 protocol discovery
• 🗺️ /sitemap.xml — XML sitemap
• 🤖 /robots.txt — all bots welcome