---
title: Agent Number — developer documentation
description: Agent Number by REALLY — developer documentation. Persistent US mobile phone numbers for AI agents.
url: https://agentnumber.really.com/docs/
doc_version: "1.0.0"
last_updated: "2026-05-15"
---

> ## Documentation index
> Fetch the complete documentation index at: https://agentnumber.really.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/quickstart) → 2-minute round-trip from zero to a working number |
| Building an agent with Anthropic / OpenAI / etc. | [MCP integration](/docs/mcp) |
| Building a server-side integration | [API reference](#api-reference) below + [Auth](/docs/auth) |
| Setting up payment | [Payment](/docs/payment) — x402 and MPP rails |
| Adding voice (calls, not just SMS) | [Voice](/docs/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](https://really.com)
- Consumer iOS app: [REALLY on the App Store](https://apps.apple.com/in/app/really/id6670762642)
- 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`](/docs/reference/subscribe) — the entry point: pay, receive a token + number
- [`POST /sms/send`](/docs/reference/send) — outbound SMS
- [`GET /sms/receive`](/docs/reference/receive) — inbound SMS (atomic claim; MCP `receive_sms` for long-poll)
- [`POST /voice/dial`](/docs/reference/voice-dial) — outbound voice calls

Programmatic clients: the canonical machine-readable spec is at [`/openapi.json`](/openapi.json).

## Sitemap

- [Overview](/docs/)
- [Quickstart](/docs/quickstart)
- [Authentication](/docs/auth)
- [SMS](/docs/sms)
- [Voice](/docs/voice)
- [MCP](/docs/mcp)
- [Payment](/docs/payment)

See the full [sitemap.md](/sitemap.md) for the complete index of docs pages.

---

Next: [Quickstart](/docs/quickstart) →