VirtualSMS 2.0.0

VirtualSMS .NET SDK

What is VirtualSMS?

Official .NET 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 package wraps the REST API in native C#, 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.

Covers the full customer-facing REST v1 surface: activations/orders (buy a number, poll or wait for the code, cancel/swap/retry), rentals (Full Access and Platform tiers), proxies (catalog, purchase, rotate, targeting, connection-string generation), account (balance, profile, transactions, usage stats), webhooks (create/list/update/delete/test/deliveries), carrier/line-type lookup, and manual-registration browser sessions (invite-only beta).

Install

dotnet add package VirtualSMS

Quickstart

using VirtualSMS;

// 1. Get your API key at https://virtualsms.io/dashboard (Settings -> API Keys)
using var client = new VirtualSMSClient("vsms_your_api_key");

// 2. Buy a number
var order = await client.CreateOrderAsync(service: "wa", country: "GB"); // WhatsApp, UK
Console.WriteLine($"Number: {order.PhoneNumber} (order {order.OrderId})");

// 3. Poll/wait for the code
var result = await client.WaitForSmsAsync(order.OrderId, timeoutSeconds: 120);
if (result.Success)
{
    Console.WriteLine($"Code: {result.Code}");
}
else
{
    Console.WriteLine("No SMS yet -- call GetSmsAsync later or CancelOrderAsync to refund.");
}

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

API coverage

Full docs: virtualsms.io/docs.

Constructor

var client = new VirtualSMSClient(
    apiKey: "vsms_your_api_key",
    options: new VirtualSMSClientOptions
    {
        BaseUrl = "https://virtualsms.io/api/v1", // default; override or set VIRTUALSMS_BASE_URL
        TimeoutSeconds = 30,                       // default
    });

Error handling

Every error the SDK raises derives from VirtualSMSException. Typed subclasses map to HTTP status codes: BadApiKeyException (401), InsufficientBalanceException (402), NotFoundException (404), RateLimitedException (429, never auto-retried), and ServerErrorException (5xx -- IsMutating tells you whether the failed call may have already changed state server-side; if so, verify with a read call like ListOrdersAsync before retrying, never blind-retry a purchase/cancel/rotate/extend). CooldownActiveException is a purely local, no-network-call guard that CancelOrderAsync/SwapNumberAsync throw when the post-purchase cooldown hasn't elapsed yet.

try
{
    var order = await client.CreateOrderAsync("wa", "GB");
}
catch (InsufficientBalanceException)
{
    Console.WriteLine("Top up your balance first.");
}
catch (ServerErrorException ex) when (ex.IsMutating)
{
    // May have gone through despite the error -- verify before retrying.
    var recent = await client.ListOrdersAsync();
}

GET requests get a bounded, automatic retry (up to 3 attempts, exponential backoff) on network errors and 5xx responses. Mutating calls (POST/PATCH/DELETE) are never auto-retried by the SDK.

Rental tiers

Two tiers, both refund-identical (full refund within 20 minutes of purchase, before the first SMS): RentalTier.FullAccess (local SIM inventory, any service) and RentalTier.Platform (sourced via our global supplier network, one service per number, 24/72/168h durations only).

Examples

See examples/ for runnable end-to-end flows: activation (BasicActivation), rental (RentalFlow), and proxy (ProxyFlow).

AI agents and MCP

This SDK is the API-client half: a typed .NET wrapper around the REST API for services and backends that call C# directly. VirtualSMS also runs a separate hosted MCP server so an AI agent (Claude, Cursor, or any MCP-compatible client) can request a number, wait for a code, or manage a rental the same way a developer would call the API directly.

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 223 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

• Homepage: virtualsms.io
• Docs: virtualsms.io/docs
• MCP server: virtualsms.io/mcp
• Pricing: virtualsms.io/pricing
• REST API: virtualsms.io/api/v1

Ecosystem

• Official MCP registry: server id io.github.virtualsms-io/sms
• VirtualSMS on Glama
• Smithery
• mcp.so
• npm: virtualsms-mcp

Other SDKs

• Python: pypi.org/project/virtualsms
• Node.js: npmjs.com/package/virtualsms-sdk
• PHP: packagist.org/packages/virtualsms/sdk
• Ruby: rubygems.org/gems/virtualsms-sdk
• Go, Rust, Swift, Java: all under github.com/virtualsms-io

Development

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

This repo was built without a local .NET SDK -- dotnet build/test/pack run in CI (see .github/workflows/) rather than locally. See PROVENANCE.md for the v1 → v2 rewrite history.

Changelog

2.0.0 -- Breaking change. Full rewrite as a native REST v1 client (https://virtualsms.io/api/v1). The v1.x client talked to the legacy handler_api.php (sms-activate-compatible) dispatcher and covered only balance/number/status/done/cancel/wait; v2 SDKs never call handler_api.php and cover the full 40+ method REST v1 surface (activations, rentals, proxies, account, webhooks, tools, and beta browser sessions). If you're on 1.x, this is not a drop-in upgrade -- method names, the constructor, and the base URL all changed.

License

MIT