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 real-SIM inventory. Real, carrier-issued SIM cards 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, 40-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.

40 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.

Activation and account (18)

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 and availability for a service x country combination. Always check before buying.
virtualsms_find_cheapest	Top N cheapest country options for a service, sorted by price, with real stock counts.
virtualsms_search_services	Natural-language search across the 2500+ service catalog. Pass "uber" or "binance", get the canonical service code.
virtualsms_get_balance	Account balance in USD. Requires VIRTUALSMS_API_KEY.
virtualsms_get_profile	Account profile metadata: email, Telegram link, balance, lifetime spend, total orders, active API keys.
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.
virtualsms_create_order	Buy a virtual phone number. Returns order_id + phone. Poll get_sms for the code.
virtualsms_get_sms	Check if SMS arrived for an order. Poll every 5-10s if not using wait_for_sms.
virtualsms_wait_for_sms	Recommended. Block until the SMS lands on an existing order, or until timeout. WebSocket-backed with polling fallback. Always returns order_id for recovery on timeout.
virtualsms_get_order	Full details of one order by order_id, including every received message.
virtualsms_list_orders	List active orders. Optional status filter. Essential for crash recovery.
virtualsms_order_history	Historical orders with filters: status, service, country, since_days, limit.
virtualsms_cancel_order	Cancel and refund. Only works if no SMS received yet. 120s cooldown after purchase.
virtualsms_cancel_all_orders	Bulk cancel all pending orders. Useful for cleanup.
virtualsms_swap_number	Swap to a different number for the same service and country without losing your spot. No extra charge, 120s cooldown.

Rentals (9)

Keep a number by the day instead of buying a single verification. Rentals run from $0.25/day, 1 to 30 days.

Name	Description
virtualsms_rentals_pricing	Full Access tier pricing: durations and prices.
virtualsms_rentals_available	Countries with rental stock, counts, and pricing, per tier. Call this for the live list before quoting a price.
virtualsms_rentals_services	Services available for Platform-tier rental in a country, with stock and price.
virtualsms_rentals_price	Retail price for a service, country, and duration combination.
virtualsms_create_rental	Rent a number. Check availability and price first.
virtualsms_list_rentals	Your rentals across both tiers, filterable by status.
virtualsms_get_rental	Full detail for one rental: tier, number, service lock, status, expiry, SMS.
virtualsms_extend_rental	Extend an active rental. Charges the current catalog price.
virtualsms_cancel_rental	Full refund within 20 minutes of purchase and before any SMS.

Proxy (10)

Matching-country proxies so the number and the IP agree. Three pools (residential, mobile, datacenter) across 190+ proxy countries, from $1.10/GB.

Name	Description
virtualsms_list_proxy_catalog	Pool types, countries, and price per GB. Start here.
virtualsms_list_proxy_locations	Cities, states, ASNs, or ZIPs for a pool type plus country. No purchase required.
virtualsms_buy_proxy	Purchase proxy traffic in GB. Returns credentials and remaining balance.
virtualsms_list_proxies	Your proxies with remaining GB and credentials. Returns proxy_id values.
virtualsms_generate_proxy_endpoint	Build a ready-to-use connection string: country, state, city, ZIP or ASN targeting, rotating or sticky, HTTP or SOCKS5.
virtualsms_rotate_proxy	Request a fresh exit IP for an existing proxy.
virtualsms_test_proxy	Prove a proxy works. Reports exit IP, country, city, ISP, and latency.
virtualsms_get_proxy_usage	Cached GB used and remaining, plus request count, for one proxy.
virtualsms_get_proxy_usage_history	Per-day traffic and request series over the last 7 or 30 days.
virtualsms_set_proxy_targeting	Persist a default geo-targeting on a proxy sub-user.

Other (3)

Name	Description
virtualsms_retry_order	Ask for the SMS to be resent to the same number. Not all order types support it.
virtualsms_check_number	Carrier and line-type lookup for any E.164 number: mobile, landline or VoIP, plus spam risk. No API key required.
virtualsms_start_manual_registration_session	Beta, invite-only. Start a country-matched cloud browser you drive yourself in a live viewer. Join t.me/VirtualSMS_io for access.

Tool source: virtualsms-io/mcp-server/src/tools.ts. v1.3.1 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	✓	N/A	EIP-3009	Live
Solana mainnet	solana:mainnet-beta	✓	✓	SPL transfer	Live
BNB Chain	eip155:56	✓	✓	Permit2	Live
Base Sepolia testnet	eip155:84532	✓	N/A	EIP-3009	Dev only
Polygon	eip155:137	✓	✓	Permit2	Roadmap
Arbitrum	eip155:42161	✓	✓	Permit2	Roadmap
Optimism	eip155:10	✓	N/A	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)	$2.50 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.

Agent directories

Discovery surfaces built for AI agents and agent builders.

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 40 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, carrier-issued SIM cards, not VoIP. VirtualSMS operates a hybrid model: dedicated inventory for premium tier (long-term rentals, high-success services) plus a carrier-vetted global 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 $2.50 deposit covers approximately 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 40-tool reference: github.com/virtualsms-io/mcp-server. This page (virtualsms.io/agents) is the canonical agent-facing entry point with skill.md, llms.txt, and /.well-known/x402.json for machine discovery. Prefer a Model Context Protocol client? Set up the VirtualSMS MCP server for hosted or local install across ten AI clients.

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 dedicated inventory we manage directly; 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.

Does VirtualSMS also handle number rentals, proxies, or private cloud browser sessions?

Yes. The same VirtualSMS account and MCP server also cover dedicated number rentals (1 to 30 days), matching-country residential, mobile and datacenter proxies, and private cloud browser sessions (beta, invite-only). All four capabilities share one API key and one prepaid balance. Join t.me/VirtualSMS_io for cloud browser beta access.

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