Agent Number — developer documentation
Persistent US mobile phone numbers for AI agents, issued by REALLY (a real wireless carrier). One subscription gives your agent a number that handles both SMS and voice. Pay once in USDC; your wallet is the account identity.
Why this exists
Most "phone number for an AI" services are VOIP wrappers around Twilio. Agent Number is different: the numbers we issue are real cellular mobile numbers on live wireless spectrum. Two-factor codes deliver. Carrier-verified voice works. Downstream services treat them like real consumer lines, because they are.
You connect via MCP (Model Context Protocol, recommended for agent runtimes) or REST (for HTTP-first clients). The same operations are available either way.
Where to start
| If you're … | Read |
|---|---|
| New here, evaluating | Quickstart → 2-minute round-trip from zero to a working number |
| Building an agent with Anthropic / OpenAI / etc. | MCP integration |
| Building a server-side integration | API reference below + Auth |
| Setting up payment | Payment — x402 and MPP rails |
| Adding voice (calls, not just SMS) | Voice |
Surface at a glance
One hostname, three namespaces:
- Product-level (root):
/subscribe,/auth,/auth/nonce,/availability,/waitlist,/number,/demo,/mcp,/openapi.json - SMS-specific:
/sms/send,/sms/receive,/sms/messages - Voice-specific:
/voice/dial,/voice/hangup,/voice/presence/<phone>(WebSocket),/voice/stream/<call_id>(WebSocket)
Trust signals
- Parent brand: really.com
- Consumer iOS app: REALLY on the App Store
- Real cellular carrier — not VOIP, not Twilio-resold
API reference
Browse per-endpoint pages — each one carries the full request / response schema, code samples in nine languages (curl, JS, Node, Python, Go, PHP, Ruby, Rust, Java), and every status code. Pick the endpoint you care about from the sidebar, or start with one of these:
POST /subscribe— the entry point: pay, receive a token + numberPOST /sms/send— outbound SMSGET /sms/receive— inbound SMS (atomic claim; MCPreceive_smsfor long-poll)POST /voice/dial— outbound voice calls
Programmatic clients: the canonical machine-readable spec is at
/openapi.json.