---
name: really-agent-number
description: Persistent US mobile phone numbers for AI agents — same number for SMS and voice, issued by REALLY (a real wireless carrier). Pay once in USDC via x402 or MPP; your wallet address is the permanent account identity. Real cellular numbers, not VOIP and not Twilio-resold.
metadata:
  product: "Agent Number"
  provider: "REALLY"
  homepage: "https://agentnumber.really.com"
  mcp: "https://agentnumber.really.com/mcp"
  openapi: "https://agentnumber.really.com/openapi.json"
  parent_brand: "https://really.com"
  ios_app: "https://apps.apple.com/in/app/really/id6670762642"
---

# Agent Number by REALLY

Persistent US mobile phone numbers for AI agents. One number does both
SMS and voice. Integrate via MCP or REST.

## What makes this different

Agent Number is operated by **REALLY**, a real wireless carrier. The
numbers issued here are **real cellular mobile numbers** on live
wireless spectrum — **not VOIP, not Twilio-resold**. Agents and their
users get the trust properties real mobile numbers provide:
two-factor codes are deliverable, carrier-verified voice calls work,
and downstream services treat the number as a genuine consumer line.

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)

## Quick start

Fastest path from zero to a working phone number:

```bash
# 1. Check how many numbers are free right now (no auth).
curl https://agentnumber.really.com/availability
# → {"available": 12}

# 2. If available > 0, subscribe. This is a payable endpoint:
#    a bare POST returns a 402 challenge describing the two
#    payment rails we accept (x402 and MPP).
curl -X POST https://agentnumber.really.com/subscribe
# → 402 + JSON body with payment instructions

# 3. Pay per the challenge (see "Payment" section below), then
#    repeat the POST with the payment header. Response gives you
#    a phone number + a bearer token.

# 4. Send your first SMS.
curl -X POST https://agentnumber.really.com/sms/send \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -d '{"to": "+15551234567", "body": "Hello from my agent"}'
```

## No numbers available right now?

Number pools are released in waves as REALLY expands inventory.

```bash
# Join the waitlist (free, no auth).
curl -X POST https://agentnumber.really.com/waitlist \
  -H "content-type: application/json" \
  -d '{"email": "you@example.com"}'
# → {"status": "added", "registered_at": "..."}
```

Also keep polling `GET /availability` — when `available > 0`
the subscribe path is open again.

## Account model

Your wallet address is the **permanent account identity**. The
subscription, the phone number, and the bearer token are all bound
to the wallet that paid for the subscription.

- If you lose the bearer token, you can recover access by signing a
  challenge with the original wallet (see Auth flow below).
- If you lose access to the paying wallet, you **cannot** recover
  the phone number or remaining subscription time.
- Do not use ephemeral / per-session wallets for paying. Use a
  durable wallet you control long-term.

## Discover available operations

Two equivalent surfaces — use whichever your runtime supports. Both
live at the service root and cover SMS and voice:

- **MCP** (streamable-http): `https://agentnumber.really.com/mcp`
  Call `tools/list` to get the full tool catalog with schemas.
- **REST**: `GET https://agentnumber.really.com/openapi.json`
  OpenAPI, same operations, HTTP-first.

Current MCP tools (as of writing): `list_services`,
`check_availability`, `try_demo`, `join_waitlist`, `subscribe`,
`auth_nonce`, `auth`, `get_number`, `send_sms`, `receive_sms`,
`list_messages`, `place_call`, `hangup_call`.

`try_demo` is a free, no-auth simulated walkthrough — it returns
canned subscribe + send + receive payloads so you can test your
MCP / REST wiring end-to-end before paying. Call it to confirm
your integration works, then `subscribe` for real.

Voice operations live under `/voice/*` (see below).

## Payment

`POST /subscribe` returns **HTTP 402** when called without a
payment header. The body describes both accepted payment rails:

- **x402**: USDC on Base (Coinbase-verified). Send the
  `X-PAYMENT: <base64>` header.
- **MPP**: USDC on Tempo. Send
  `Authorization: Payment <challenge>`.

Price is **$1800 USDC per year**. After paying, re-POST with the
payment header and you get back `{token, phone_number, ...}`.

## Auth recovery

If you lose the bearer token:

```bash
# 1. Ask for a nonce (no body needed; wallet identity is established at step 3).
curl -X POST https://agentnumber.really.com/auth/nonce

# 2. Sign "Sign in to really.com SMS\nNonce: <nonce>" with the wallet's private key (EIP-191).
# 3. POST /auth with {wallet, nonce, signature} to get a fresh bearer token.
#    Response: {token, number, expires_at}. All prior tokens for this wallet are revoked.
```

## Send and receive SMS

After auth, all SMS endpoints use `Authorization: Bearer <token>`.

```bash
# Send
curl -X POST https://agentnumber.really.com/sms/send \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -d '{"to": "+15551234567", "body": "Hello"}'

# Receive (returns immediately with any undelivered messages; use MCP receive_sms for long-poll)
curl https://agentnumber.really.com/sms/receive \
  -H "authorization: Bearer <token>"

# Look up your own number
curl https://agentnumber.really.com/number \
  -H "authorization: Bearer <token>"
# Response includes number, sub_account_id, plan, expires_at.
# Hardware device_id and sim_number are internal and are not exposed.
```

## Voice calls (same number)

Voice on the same number as SMS. There are two WebSocket channels
and they serve different purposes — use both during a call.

- **Presence WS** (`GET /voice/presence/<phone>`) — the signaling
  channel. Open it once and keep it open as long as you want to
  accept incoming calls. The server pushes three JSON event types
  over the call lifecycle: `{event: "ringing", call_id, caller, stream_url}`
  on incoming, `{event: "answered", call_id}` when picked up, and
  `{event: "ended", call_id, missed}` on hangup. The server
  auto-answers on ring; you only need to handle the signals.
- **Stream WS** (`GET /voice/stream/<call_id>`) — the audio
  channel. Open it when you get a `stream_url` (either from the
  presence `ringing` message or from a `POST /voice/dial`
  response). Send agent audio as binary frames; receive caller
  audio the same way. Close it when the call ends.

For outbound: `POST /voice/dial {"phone_number": "+1...", "to": "+1..."}`
returns `{call_id, stream_url, direction, caller, phone_number}`;
open the stream WS and talk. Presence is not required for outbound.
The MCP equivalent is the `place_call` tool — same shape, same response.

To end a call from the agent side: `POST /voice/hangup
{"call_id": "..."}` (or the MCP `hangup_call` tool). Returns once
the hangup is dispatched to the phone; the presence WS will emit
an `ended` event when teardown completes.

During a call both WebSockets can be open simultaneously: presence
keeps listening for more incoming calls, stream carries the audio
for the current one.

Same bearer-token auth as SMS.

## What can go wrong

- **402 on `/subscribe`** — you didn't send the payment header.
  Parse the response body; it describes exactly what to send.
- **401 on bearer-gated endpoints** — token expired or wrong.
  Re-run the auth-recovery flow.
- **`{"available": 0}`** — pool is exhausted. Waitlist is your
  option (above).
- **`/sms/receive` timing out with no message** — normal. It's a
  long-poll; reconnect.
- **SMS not delivered to certain destinations** — international
  destinations may be restricted by the carrier plan. Check the
  response body on `/sms/send` for specific error reasons.

## Discovery

- `https://agentnumber.really.com/.well-known/mcp/server-card.json`
- `https://agentnumber.really.com/.well-known/agent-card.json`
- `https://agentnumber.really.com/.well-known/x402.json`
- `https://agentnumber.really.com/.well-known/mpp.json`
- `https://agentnumber.really.com/llms.txt`
- `https://agentnumber.really.com/sitemap.xml`
- `https://agentnumber.really.com/robots.txt`

## Pricing at a glance

| Item | Cost |
|---|---|
| One phone number, one year, unlimited SMS + voice | $1800 USDC |
| Check availability | Free |
| Join waitlist | Free |
| Pay via x402 or MPP | No surcharge |

No per-message or per-minute fees during the subscription year.

## Support / links

- Product landing: [agentnumber.really.com](https://agentnumber.really.com)
- REALLY: [really.com](https://really.com)
- iOS app: [REALLY on the App Store](https://apps.apple.com/in/app/really/id6670762642)