VirtualSMS Python SDK

What is VirtualSMS?

Official Python SDK for the VirtualSMS API. VirtualSMS is an account verification platform for individuals, developers, and AI agents: one-time SMS verification, dedicated number rentals, matching-country proxies, and private cloud browser sessions (beta), all behind one API, one MCP server, and one prepaid balance. This SDK is a native Python client over the REST API, backed by real carrier-issued mobile numbers (real physical SIM cards, not VoIP) across 2500+ services in 145+ countries.

Built for developers and AI agents: REST API, hosted MCP server, SDKs.

This package talks to https://virtualsms.io/api/v1 directly. It is not a drop-in client library for any other verification service; version 2.0.0 is a from-scratch rewrite, replacing the v1.x package that wrapped a legacy dispatcher.

Installation

pip install virtualsms

Quick start

from virtualsms import VirtualSMS

# Get your API key at https://virtualsms.io (Settings -> API Keys)
client = VirtualSMS("vsms_your_api_key")

# 1. Check balance
balance = client.get_balance()
print(f"Balance: ${balance['balance_usd']:.2f}")

# 2. Buy a number for WhatsApp verification in the UK
order = client.create_order("wa", "GB")
print(f"Use this number: {order['phone_number']}")

# 3. Wait for the verification code
result = client.wait_for_sms(order["order_id"])
if result["success"]:
    print(f"Code: {result['code']}")
else:
    print("Timed out, try get_sms(order_id) again later or cancel_order(order_id) for a refund.")

Full API reference: virtualsms.io/docs

Capabilities

1. One-time SMS verification. Receive a code for a service like WhatsApp, Telegram, Discord, or a dating app, on demand, from $0.05 per code.
2. Dedicated number rentals. Hold one number for 1-30 days and receive SMS from any service on that number, from $0.25/day.
3. Matching-country proxies. Pair a number with an IP from the same country, across 190+ proxy countries, from $1.10/GB.
4. Private cloud browser sessions (beta). Start a country-matched browser in a live viewer for the signup step itself, invite-only.

Why real SIM cards

VirtualSMS runs on real carrier-issued mobile numbers, backed by real physical SIM cards, not VoIP. Services like WhatsApp, Telegram, Discord, and dating apps run a carrier lookup before they send a code, and VoIP or virtual numbers fail that check more often than a real SIM does. A physical SIM on a real carrier network reads like any other phone on that network, carriers like Vodafone, O2, and T-Mobile depending on the country, which is part of why VirtualSMS holds a 95%+ success rate across 2500+ services in 145+ countries.

What this SDK covers

All 46+ non-gated REST v1 methods across seven groups: activations/orders, rentals (full-access and platform tiers), proxies, account, one session-start method, one standalone public tool, and webhooks.

Group	Examples
Activations / Orders	list_services, get_price, create_order, wait_for_sms, cancel_order, swap_number, search_services, find_cheapest
Rentals	rentals_available, create_rental, list_rentals, extend_rental, cancel_rental
Proxies	list_proxy_catalog, buy_proxy, rotate_proxy, set_proxy_targeting, generate_proxy_endpoint
Account	get_balance, get_profile, get_transactions, get_stats
Session	start_manual_registration_session (invite-only beta)
Tools	check_number
Webhooks	list_webhooks, create_webhook, update_webhook, test_webhook, list_webhook_deliveries

Not covered (by design, gated on the API itself): release_rental (fee policy pending), interactive browser session control beyond starting one, and account registration/login (account creation is a web-only flow).

Rentals

Two tiers, identical refund terms (full refund within 20 minutes of purchase, before the first SMS):

# Full Access: local SIM inventory, works with any service
rental = client.create_rental(tier="full_access", country="GB", duration_hours=24, service="wa")

# Platform: sourced via our global supplier network, locked to one service per number
rental = client.create_rental(tier="platform", country="GB", duration_hours=24, service="wa")

client.extend_rental(rental["rental_id"], duration_hours=24)
client.cancel_rental(rental["rental_id"])

Proxies

catalog = client.list_proxy_catalog()
proxy = client.buy_proxy(pool_type="residential", gb=1, country_code="GB")
usage = client.get_proxy_usage(proxy["proxy_id"])
endpoint = client.generate_proxy_endpoint(proxy["proxy_id"], country_code="GB")
print(endpoint["endpoints"][0])

Errors

Every method raises a typed subclass of VirtualSMSError:

from virtualsms import VirtualSMS, InsufficientBalanceError, NoNumbersError, BadApiKeyError, RateLimitedError

client = VirtualSMS("vsms_your_api_key")
try:
    order = client.create_order("wa", "GB")
except NoNumbersError:
    print("No stock for this service/country right now.")
except InsufficientBalanceError:
    print("Top up at https://virtualsms.io")
except BadApiKeyError:
    print("Bad API key.")
except RateLimitedError:
    print("Slow down and retry later.")

A server error (5xx) on a mutating call (purchase, cancel, rotate, extend, etc.) is never retried automatically by this SDK, because the operation may have completed server-side despite the error. Verify with a read call (list_orders, get_order, list_rentals) before retrying by hand. GET requests get a bounded automatic retry (up to 3 attempts) on network errors and 5xx responses only.

Examples

See examples/ for complete, runnable scripts: an activation flow, a rental flow, and a proxy flow.

AI agents and MCP

This SDK is the API-client half: a typed wrapper an application or agent framework calls directly. The hosted MCP server is the separate agent-facing half, exposing the same capabilities as MCP tools for MCP-compatible clients like Claude and Cursor. Use this SDK when you're writing code that calls VirtualSMS; use the MCP server when an AI agent needs to call VirtualSMS itself without a code layer in between.

FAQ

What is VirtualSMS?

VirtualSMS is an account verification platform for individuals, developers, and AI agents. It combines one-time SMS verification, dedicated number rentals, matching-country proxies, and private cloud browser sessions behind one API, one MCP server, and one prepaid balance.

Does VirtualSMS use real SIM cards or VoIP numbers?

VirtualSMS uses real carrier-issued mobile numbers, backed by real physical SIM cards, not VoIP. Many services, including WhatsApp, Telegram, Discord, and dating apps, reject VoIP and virtual numbers at signup; a real physical SIM on a real carrier network passes that check far more often, which is reflected in a 95%+ success rate.

Which services and countries does VirtualSMS support?

VirtualSMS covers 2500+ services across 145+ countries for SMS verification and number rentals, plus matching-country proxies across 190+ proxy countries. Coverage spans messaging apps, social platforms, marketplaces, dating apps, and financial services.

Can I rent a number, or only buy one-time codes?

Both. Buy a single one-time code from $0.05, or rent a dedicated number for 1-30 days from $0.25/day to receive SMS from any service on that number for the rental window.

Does VirtualSMS work with AI agents and MCP?

Yes. VirtualSMS exposes a hosted MCP server plus a REST API and official SDKs in nine languages, so an AI agent can request a number, wait for a code, or manage a rental the same way a developer would call the API directly.

How much does VirtualSMS cost?

Pricing is pay-as-you-go from one prepaid balance: SMS verification from $0.05 per code, number rentals from $0.25/day, and proxies from $1.10/GB. There is no subscription requirement.

Is there a free API key?

Yes. Creating a VirtualSMS account issues an API key immediately, at no cost. You only spend from your prepaid balance when you place an order: an activation, a rental, or a proxy.

Links

Product

• Homepage: virtualsms.io
• Docs: virtualsms.io/docs
• MCP server: virtualsms.io/mcp
• Pricing: virtualsms.io/pricing
• REST API: virtualsms.io/api/v1
• Other SDKs: PHP · Node.js · Ruby · .NET · Go · Rust · Swift · Java
• GitHub: github.com/virtualsms-io

Ecosystem

VirtualSMS's MCP server is listed across the major MCP directories:

• Official MCP registry: io.github.virtualsms-io/sms (registry.modelcontextprotocol.io)
• Glama: VirtualSMS on Glama
• Smithery: smithery.ai/servers/virtualsms/virtualsms-mcp
• mcp.so: mcp.so/servers/mcp-server-virtualsms-io
• npm (MCP server package): virtualsms-mcp

Development

Run sh scripts/check-positioning.sh before committing copy changes. It fails on stale service or country counts and other banned positioning wording.

pip install -e ".[dev]"
pytest

Migrating from v1.x

v1.x wrapped a legacy sms-activate-compatible dispatcher (getBalance, getNumber, getStatus, etc). v2.0.0 is a full rewrite talking to /api/v1/* REST endpoints directly and is not backward compatible with the v1.x method names. See CHANGELOG.md for the full method mapping.

License

MIT