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 API key path and the x402 pay-per-call 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.

Pay per SMS verify in USDC

x402 is the HTTP 402 Payment Required protocol pioneered by Coinbase. Your agent pays with a USDC signature on Base mainnet — no API key, no signup, no prepaid balance.

Request

curl -X POST https://virtualsms.io/api/v1/x402/sms-verify \
  -H "Content-Type: application/json" \
  -d '{
    "service": "telegram",
    "country": "US",
    "max_price_usd": 0.50
  }'

First response — 402 Payment Required

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://virtualsms.io/api/v1/x402/sms-verify",
    "description": "SMS verification with real SIM card. Receive OTP for any service in 145+ countries.",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "100000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x...",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USDC", "version": "2" }
  }],
  "extensions": {}
}

Retry with X-PAYMENT header — 200 OK

POST /api/v1/x402/sms-verify HTTP/1.1
Content-Type: application/json
X-PAYMENT: <base64(payment-payload)>

{ "service": "telegram", "country": "US" }

→ HTTP/1.1 200 OK
X-PAYMENT-RESPONSE: <base64(settlement-response)>

{
  "phone_number": "+14155552671",
  "code": "12345",
  "country": "US",
  "service": "telegram",
  "delivered_in_seconds": 8
}

Flow

1. Agent POSTs to /api/v1/x402/sms-verify with no payment → server returns 402 with accepts[].
2. Agent client (e.g. x402-axios, x402-fetch) signs an EIP-3009 TransferWithAuthorization.
3. Agent retries with X-PAYMENT header.
4. Server verifies via Coinbase CDP facilitator, executes buy_number → wait_for_code internally.
5. Server settles on-chain (Base mainnet, ~2s), returns 200 with phone + OTP code.

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)

Account (4)

Order management (10)

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

Supported chains and tokens

Launch configuration is single-chain (Base mainnet) for first-mover simplicity. Multi-chain expansion follows real agent demand.

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

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

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