# VirtualSMS

> Real-SIM SMS verification for AI agents. Temporary phone numbers across 145+ countries and 2500+ services. Pay-as-you-go via x402 USDC deposits, or use a prepaid API key. Operating since 2022 on hybrid infrastructure with real SIM cards on physical hardware (no VoIP).

VirtualSMS gives AI agents the ability to receive OTP codes during account verification flows on services like WhatsApp, Telegram, Google, Uber, Binance, Discord, and 2495 others. Two integration paths share the same backend: a Model Context Protocol (MCP) server with 18 tools, and a topup-first x402 USDC endpoint that issues an API key against an onchain deposit. The MCP server works with Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw, Codex, Hermes, Cline, Zed, and Continue.dev.

## Documentation

- [Agent landing page](https://agents.virtualsms.io/): Canonical entry point for AI agent integration. Hero, install, x402 topup flow, 18-tool reference, pricing, FAQ.
- [skill.md](https://agents.virtualsms.io/skill.md): Single-fetch master reference in markdown — install configs, x402 spec, tool list, pricing, FAQ.
- [API docs](https://virtualsms.io/docs): Mintlify-hosted REST API reference.
- [MCP server README](https://github.com/virtualsms-io/mcp-server): Full per-client install configs, examples, security policy.

## x402 (HTTP 402 Payment Required)

- [x402 discovery file](https://agents.virtualsms.io/.well-known/x402.json): JSON manifest describing the topup endpoint, accepted networks, tokens, and limits.
- [POST /api/v1/x402/topup](https://virtualsms.io/api/v1/x402/topup): Deposit $2-$10000 USDC on Base or Solana, receive an API key + balance. Default quote is $5. Per-activation pricing $0.05-$5 retail is then drawn from balance via the REST or MCP API.

## Package registries

- [npm (MCP)](https://www.npmjs.com/package/virtualsms-mcp): `virtualsms-mcp` v1.2.3 — local stdio MCP server.
- [npm (SDK)](https://www.npmjs.com/package/virtualsms-sdk): JavaScript / TypeScript SDK.
- [PyPI](https://pypi.org/project/virtualsms/): `pip install virtualsms` — Python SDK.
- [Packagist](https://packagist.org/packages/virtualsms/sdk): `composer require virtualsms/sdk` — PHP SDK.
- [RubyGems](https://rubygems.org/gems/virtualsms-sdk): `gem install virtualsms-sdk` — Ruby SDK.
- [NuGet](https://www.nuget.org/packages/VirtualSMS): `dotnet add package VirtualSMS` — .NET SDK.

## MCP directories

- [MCP Registry](https://registry.modelcontextprotocol.io): Canonical MCP registry.
- [mcpmarket.com](https://mcpmarket.com/server/virtualsms): MCP catalog.
- [Glama](https://glama.ai/mcp/servers/virtualsms-io/mcp-server): MCP catalog.
- [LobeHub](https://lobehub.com/mcp/virtualsms-io-mcp-server): MCP marketplace.
- [mcprepository](https://mcprepository.com/virtualsms-io/mcp-server): Indexed.
- [402.ad](https://402.ad/service/1e1c3da6-f889-4b5c-94a0-7506403cdbdc/virtualsms-mcp-server): x402 + MCP catalog.
- [Smithery](https://smithery.ai/servers/virtualsms/virtualsms-mcp): MCP marketplace.

## Curated lists

- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers): Community-maintained list (punkpeye).
- [awesome-codex-skills](https://github.com/ComposioHQ/awesome-codex-skills): Community-maintained list (ComposioHQ).

## Workflow platforms

- [Pipedream](https://pipedream.com/apps/virtualsms): No-code agent automation. App live, component PR open.

## Source code

- [GitHub source](https://github.com/virtualsms-io/mcp-server): MIT licensed. 18 tool definitions in `src/tools.ts`.

## Optional

- [Main site](https://virtualsms.io): Landing page, pricing, signup.
- [MCP overview page](https://virtualsms.io/mcp): Marketing page for the MCP integration.
- [Security policy](https://github.com/virtualsms-io/mcp-server/blob/main/SECURITY.md): Vulnerability disclosure.
- [GitHub org](https://github.com/virtualsms-io): Open source repos (mcp-server, examples, api-docs).