# Agent Number by REALLY

Persistent SMS phone numbers for AI agents. Pay once, keep your number for a year.

## What this is

Persistent US mobile phone numbers for AI agents — same number for SMS
AND voice. Operated by REALLY, a real wireless carrier. These are
**real cellular numbers, not VOIP and not Twilio-resold**. Pay $1800
USDC per year via x402 (or via MPP) and receive a dedicated US phone
number bound to your wallet address. Integrate via MCP
(https://agentnumber.really.com/mcp) or REST.

Parent brand: https://really.com  ·  iOS app: https://apps.apple.com/in/app/really/id6670762642

## Check availability first

Numbers are released in waves as REALLY expands pool inventory. Always
check availability before attempting to subscribe — if the pool is
exhausted, subscribe will return an "unavailable" response and the
right action is to join the waitlist.

- GET  https://agentnumber.really.com/availability — free, no auth. Returns {"available": N}.
- POST https://agentnumber.really.com/waitlist — free, no auth. Body {"email": "..."} to be
  notified when the next pool opens.

## Endpoints

Product-level (a subscription covers SMS + voice on the same number):

- GET  https://agentnumber.really.com/availability — how many numbers are currently free (no auth)
- POST https://agentnumber.really.com/waitlist — join the waitlist when none are available (no auth)
- POST https://agentnumber.really.com/subscribe — pay via x402 / MPP, receive a token + phone number
- POST https://agentnumber.really.com/auth/nonce — get a nonce for signature recovery
- POST https://agentnumber.really.com/auth — recover access via wallet signature
- GET  https://agentnumber.really.com/number — look up your assigned number
- POST https://agentnumber.really.com/mcp — MCP JSON-RPC endpoint (tools/list, tools/call)

SMS-specific (bearer token):

- POST https://agentnumber.really.com/sms/send — send an SMS
- GET  https://agentnumber.really.com/sms/receive — long-poll inbound SMS
- GET  https://agentnumber.really.com/sms/messages — list message history

Voice-specific (bearer token):

- POST https://agentnumber.really.com/voice/dial — place an outbound call (returns call_id + stream_url)
- POST https://agentnumber.really.com/voice/hangup — end an active call by call_id
- GET  https://agentnumber.really.com/voice/presence/<phone> — agent presence WebSocket (declares "I want calls on this number")
- GET  https://agentnumber.really.com/voice/stream/<call_id> — bidirectional 16kHz mono PCM WebSocket

## Discovery

- https://agentnumber.really.com/llms-full.txt — concatenated full-text bundle (one fetch)
- https://agentnumber.really.com/.well-known/x402.json — x402 service descriptor
- https://agentnumber.really.com/.well-known/mpp.json — MPP service descriptor
- https://agentnumber.really.com/.well-known/ai-plugin.json — AI plugin manifest
- https://agentnumber.really.com/.well-known/claude.json — Claude plugin manifest
- https://agentnumber.really.com/openapi.json — OpenAPI 3.0 spec
- https://agentnumber.really.com/skills.json — agent skills manifest (MCP tool list)
- https://agentnumber.really.com/skills.md — single-file agent onboarding guide (saperly-style)
- https://agentnumber.really.com/sitemap.md — Markdown sitemap (a14y)
- https://agentnumber.really.com/sitemap.xml — XML sitemap
- https://agentnumber.really.com/agents.txt — agent access policy
- https://agentnumber.really.com/AGENTS.md — same content as agents.txt at the canonical filename
- https://agentnumber.really.com/robots.txt — crawler policy

## Account model

Important: Your wallet address is your permanent account identity for this service. If you lose access to the wallet that paid for the subscription, you cannot recover your phone number or your remaining subscription time. Do not use ephemeral or per-session wallets. Recovery via signature requires the original wallet's private key.

Your subscription is keyed by the wallet that paid for it. When the
subscription expires, re-paying with the same wallet renews and keeps the
same phone number. Recovery from a lost token uses signature-based
authentication against the original wallet.

## Example: subscribe (x402)

Step 1: Initial request returns 402 with the payment challenge.

  curl -X POST https://agentnumber.really.com/subscribe

Step 2: Sign the transferWithAuthorization message with your wallet, then
retry with the X-Payment header.

  curl -X POST https://agentnumber.really.com/subscribe \
    -H "X-Payment: <base64url-encoded signed payment>"

Response:
  { "token": "...", "number": "+1...", "expires_at": "...", "renewed": false }

## Example: send 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 your agent"}'

## Example: recover access via wallet signature

  # 1. Get a nonce
  NONCE=$(curl -s -X POST https://agentnumber.really.com/auth/nonce | jq -r .nonce)

  # 2. Sign the message "Sign in to really.com SMS\nNonce: <nonce>"
  #    with your wallet (viem, ethers, web3.py, etc.)

  # 3. POST signature back
  curl -X POST https://agentnumber.really.com/auth \
    -H "Content-Type: application/json" \
    -d '{"wallet": "0x...", "nonce": "'$NONCE'", "signature": "0x..."}'

## Pricing

$1800/year for a persistent US phone number. One year of unlimited send and
receive (subject to carrier rate limits). Same number on renewal.

## Support

support@really.com