Forem: VirtualSMS

x402 SMS Verification: Pay-Per-Call OTP for Autonomous Agents

VirtualSMS — Sat, 02 May 2026 08:43:23 +0000

TL;DR

AI agents need to spend money. Operators don't want to manage API keys for every agent. HTTP 402 Payment Required + Coinbase x402 facilitator = agent pays once, gets api_key + balance, spends down on real services. Here's how I wired it on our SMS verification API, with working Python code.

What is x402?

HTTP 402 has been a "reserved for future use" status code in the spec since 1997. In 2025, Coinbase (with Cloudflare and others) built the x402 protocol on top of it — a standard way to settle USDC micropayments inline with HTTP requests.

The flow is dead simple from an agent's perspective:

Agent makes a normal POST to your endpoint
Server returns 402 Payment Required with a JSON manifest listing accepted networks (Base / Solana / Polygon), token (USDC / USDT), amount, and recipient address
Agent (using x402-fetch or a similar SDK) signs an EIP-3009 authorization, retries with the X-PAYMENT header
Server verifies via the Coinbase facilitator, settles on-chain, returns 200 OK with whatever the agent paid for

No API keys exchanged out-of-band. No paid tier flow. No human in the loop.

Why deposit-first instead of per-call?

The "obvious" x402 design is: every API call returns 402, agent pays per request. We tried it. It doesn't work for variable-priced services.

SMS verification ranges from $0.05 (cheap-country Discord) to $5 (premium WhatsApp on a high-block carrier). If x402 charges a flat $0.10 per call, you either:

Lose money on the $5 service (you charged $0.10, paid the carrier $5)
Rip off the agent on the $0.05 service (you charged $0.10, retail is $0.05)

Per-call flat-fee only works for fixed-cost services. For variable-priced retail, you need deposit-first:

Agent deposits $X via x402 (one 402 → settle → 200 cycle)
Agent gets api_key + balance
Agent uses api_key on the normal REST endpoints, debited at retail prices
Refunds (when SMS doesn't arrive within timeout) credit back to the api_key balance

Same protocol surface from the agent's perspective (one 402 dance), real retail pricing on the back end.

The endpoint

POST /api/v1/x402/topup

An empty body returns the manifest:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "token": "USDC",
      "maxAmountRequired": "5000000",
      "resource": "https://virtualsms.io/api/v1/x402/topup",
      "description": "Top up VirtualSMS API balance — pay $5.00 USDC on base, receive API key + $5.00 balance",
      "payTo": "0xfEc54264350d97d9b63f9Cc415BAF708C4695F32",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "error": "Payment required"
}

Three networks accepted: Base USDC, Solana USDC, Solana USDT. $2 minimum deposit, $5 default, $10,000 max.

Working agent code

Using x402-fetch (Coinbase's reference SDK):

import os
import time
from x402 import wrap_fetch
from web3 import Account

# Agent's own wallet (separate from the recipient address)
account = Account.from_key(os.environ["AGENT_PRIVATE_KEY"])
fetch = wrap_fetch(account=account, network="base")

# 1. Deposit — single 402 -> settle -> 200 cycle
deposit = fetch("https://virtualsms.io/api/v1/x402/topup", method="POST")
api_key = deposit.json()["api_key"]
balance = deposit.json()["balance_usd"]
print(f"Got api_key with ${balance} balance")

# 2. Buy a number — normal REST, no x402 needed
order = fetch(
    "https://virtualsms.io/api/v1/customer/purchase",
    method="POST",
    headers={"X-API-Key": api_key},
    json={"service": "discord", "country": "id"},
)
order_id = order.json()["order_id"]
phone = order.json()["phone_number"]
print(f"Got number: {phone} (order: {order_id})")

# 3. Poll for SMS
while True:
    status = fetch(
        f"https://virtualsms.io/api/v1/customer/order/{order_id}",
        headers={"X-API-Key": api_key},
    ).json()
    if status.get("sms_received"):
        print(f"OTP: {status['sms_text']}")
        break
    time.sleep(5)

What the API key buys

Once an agent has the api_key + balance, the rest of the API is pure REST:

GET /api/v1/catalog/services — full service catalog (~2,500 services)
GET /api/v1/catalog/countries — 145+ countries with live availability
POST /api/v1/customer/purchase — buy a number for a service+country
GET /api/v1/customer/order/{id} — poll for SMS arrival
POST /api/v1/customer/cancel/{id} — cancel + refund (within the 120s cooldown)

Auth header is X-API-Key. The cooldown between cancel and re-purchase is 120 seconds, server-side.

What surprised me building this

Self-payment works on Base. Coinbase's facilitator allows payer == recipient settlements. Useful for ops smoke tests where you don't want to spin up a separate test wallet.
The manifest needs extra: { name, version } for the EIP-712 domain to validate cleanly across all clients. We caught this mid-test.
Solana token-account initialization matters — wallets without a USDC token account just fail silently. Worth noting in the manifest description.
Variable timeouts per supplier — some services activate in 30 seconds, others in 20 minutes. The agent should poll on a backoff curve, not a tight loop.

Why this matters for AI agents

The whole point of x402 is removing the human from the payment loop. An autonomous agent doing account signups, OTP receipts, or workflow automation can't pause to email an operator for an api_key. With deposit-first x402:

Agent budgets $50 in USDC at the start of a workflow
Agent does whatever — verify accounts, rent numbers, pull OTPs
Agent never asks for credentials or keys

This is the same idea Coinbase had when shipping x402 in the first place: HTTP at scale, but agentic.

Try it

If you're building agent workflows that need SMS verification, the endpoint is live. The manifest is real, settlement works, the code above is exact. Hit /api/v1/x402/info for the current state of accepted networks and price floors.

Full API reference: virtualsms.io/api.

Disclosure: I operate virtualsms.io and built this implementation. Happy to answer questions about the protocol or the SMS verification side in the comments.

Source code & install:

GitHub — virtualsms-io/mcp-server — open-source MCP server
npm — virtualsms-mcp — npx virtualsms-mcp to run locally
Hosted MCP endpoint — StreamableHTTP, zero install
API reference — full REST + sms-activate compatible API

Listed in:

Model Context Protocol Registry (official) — Anthropic-maintained
Smithery (MCP) — quality score 98/100
Smithery (Claude Skill) — Skill format, 20+ agent clients
Glama
mcp.so
Lobehub
ClawHub
AlternativeTo
Cryptwerk (crypto-payments directory)

Related read:

How to Add SMS Verification to Your App with Real SIM Cards — companion dev.to post covering the sms-activate-compatible API + Node.js examples

How to Add SMS Verification to Your App with Real SIM Cards

VirtualSMS — Tue, 14 Apr 2026 11:02:41 +0000

How to Add SMS Verification to Your App with Real SIM Cards

If you're building an app that requires phone verification, you've probably considered Twilio or similar VoIP providers. They work fine for sending SMS — but they fail badly when you need to receive verification codes from services like WhatsApp, Telegram, or banking apps.

Why? Because those services detect and reject VoIP numbers.

In this tutorial, I'll show you how to integrate SMS verification using real physical SIM cards through the VirtualSMS API — and why it matters for QA testing, multi-account management, and automation.

Why Real SIM Cards?

Most SMS APIs give you a virtual number. These numbers:

Get blocked by WhatsApp (90%+ rejection rate)
Get flagged by Telegram, Google, Instagram
Fail on banking/crypto exchange verification
Leave audit trails that link back to VoIP providers

Physical SIM numbers sit in actual hardware modems on real cellular networks. To any service checking the number type, they're indistinguishable from a personal phone.

The VirtualSMS API

VirtualSMS offers two API styles:

Style	Endpoint	Best For
sms-activate Compatible	`/stubs/handler_api.php`	Migrating from DaisySMS, existing bots
Modern REST	`/api/v1/`	New integrations, webhooks, WebSocket

Both require an API key from your VirtualSMS dashboard (Settings → API Keys).

Full API docs: virtualsms.io/api

Quick Start: Get a Number and Receive an SMS

Using curl (sms-activate compatible API)

Step 1: Check your balance

curl "https://virtualsms.io/stubs/handler_api.php?action=getBalance&api_key=YOUR_API_KEY"
# Response: ACCESS_BALANCE:50.30

Step 2: Get a number for WhatsApp

curl "https://virtualsms.io/stubs/handler_api.php?action=getNumber&service=wa&country=187&api_key=YOUR_API_KEY"
# Response: ACCESS_NUMBER:12345:13476711222
# Format: ACCESS_NUMBER:{activationId}:{phoneNumber}

Step 3: Poll for the SMS code

curl "https://virtualsms.io/stubs/handler_api.php?action=getStatus&id=12345&api_key=YOUR_API_KEY"
# Waiting: STATUS_WAIT_CODE
# Received: STATUS_OK:438271

Step 4: Mark as done

curl "https://virtualsms.io/stubs/handler_api.php?action=setStatus&id=12345&status=6&api_key=YOUR_API_KEY"
# Response: ACCESS_ACTIVATION

Using Node.js (Modern REST API)

const API_KEY = 'vsms_your_api_key_here';
const BASE = 'https://virtualsms.io/api/v1';

const headers = { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' };

// Step 1: Rent a number for WhatsApp
const rentResponse = await fetch(`${BASE}/numbers/rent`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ service: 'whatsapp', country: 'US' })
});
const rental = await rentResponse.json();
console.log(`Got number: ${rental.phone} (rental ID: ${rental.rental_id})`);

// Step 2: Poll for SMS (or use webhooks — see below)
const poll = async (rentalId) => {
  while (true) {
    const res = await fetch(`${BASE}/numbers/${rentalId}/status`, { headers });
    const data = await res.json();

    if (data.status === 'received') {
      console.log(`SMS code: ${data.sms_code}`);
      console.log(`Full text: ${data.text}`);
      return data.sms_code;
    }

    // Wait 5 seconds before next check
    await new Promise(r => setTimeout(r, 5000));
  }
};

const code = await poll(rental.rental_id);

// Step 3: Mark as done
await fetch(`${BASE}/numbers/${rental.rental_id}/done`, {
  method: 'POST',
  headers
});

Using Webhooks (No Polling Needed)

Instead of polling every few seconds, register a webhook URL in your dashboard. When an SMS arrives, VirtualSMS sends a POST to your endpoint:

{
  "activationId": 12345,
  "service": "wa",
  "code": "438271",
  "text": "Your WhatsApp code is 438271. Don't share this code.",
  "country": 187,
  "receivedAt": "2026-03-03 14:22:11"
}

This is much more efficient for production systems — zero delay, zero wasted API calls.

Migrating from DaisySMS

DaisySMS shut down in December 2025. If you have existing automation built on their API, VirtualSMS is a drop-in replacement. The API is fully compatible — same action names, same response format, same error codes. One line change:

- const BASE_URL = "https://daisysms.com/stubs/handler_api.php"
+ const BASE_URL = "https://virtualsms.io/stubs/handler_api.php"

No other code changes required.

Use Cases for Developers

QA/Testing: Verify your app's phone verification flow without using personal numbers
Multi-account testing: Test how your service handles multiple registrations
CI/CD pipelines: Automated end-to-end tests that include SMS verification steps
Service monitoring: Check that verification flows work across different countries

Pricing

Activations start at $0.05 per SMS. Rentals (dedicated numbers for 1-90 days) start at $3/day. Full pricing breakdown here.

Payments accepted via cryptocurrency — no credit card needed.

VirtualSMS Resources:

Best SMS Verification Services 2026: https://penzu.com/p/9d5622c72841a2aa
Developer API Tutorial: https://dev.to/virtualsms/how-to-add-sms-verification-to-your-app-with-real-sim-cards-50lc
Руководство на русском: https://teletype.in/@virtualsms/NReaV38zcpW
Why VoIP Numbers Fail: https://telegra.ph/Why-VoIP-Numbers-Fail-for-SMS-Verification-and-What-Actually-Works-in-2026-04-14
DaisySMS Alternative Guide: https://medium.com/@dev_13666/daisysms-shut-down-what-now-the-best-alternative-with-full-api-compatibility-2026-06e484d93d23
VirtualSMS on Grokipedia: https://grokipedia.com/page/VirtualSMS
VirtualSMS on Cryptwerk: https://cryptwerk.com/company/virtualsms/
WhatsApp Verification Guide: https://virtualsms9.wordpress.com/2026/04/14/how-to-get-a-virtual-phone-number-for-whatsapp-verification-2026-guide/
Anonymous SMS Verification: https://virtualsmsio.blogspot.com/2026/04/protect-your-phone-number-anonymous-sms.html
Telegram Without Phone Number: https://www.tumblr.com/virtualsms/813881309501014016/how-to-use-telegram-without-your-personal-phone
VirtualSMS Guide PDF: https://issuu.com/virtualsms/docs/ms_verification_with_real_sim_cards_virtualsms_g
VirtualSMS on AlternativeTo: https://alternativeto.net/software/virtualsms/