# Agent Number by REALLY

Sandbox: persistent SMS phone numbers for AI agents.

## 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 $1000
USDC per year via x402 (or via MPP) and receive a dedicated US phone
number bound to your wallet address. Integrate via MCP
(https://sandbox.agentnumber.really.com/sms/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://sandbox.agentnumber.really.com/sms/availability — free, no auth. Returns {"available": N}.
- POST https://sandbox.agentnumber.really.com/sms/waitlist — free, no auth. Body {"email": "..."} to be
  notified when the next pool opens.

## Endpoints

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

## Discovery

- https://sandbox.agentnumber.really.com/sms/.well-known/x402.json — x402 service descriptor
- https://sandbox.agentnumber.really.com/sms/.well-known/mpp.json — MPP service descriptor
- https://sandbox.agentnumber.really.com/sms/.well-known/ai-plugin.json — AI plugin manifest
- https://sandbox.agentnumber.really.com/sms/.well-known/claude.json — Claude plugin manifest
- https://sandbox.agentnumber.really.com/sms/openapi.json — OpenAPI 3.0 spec
- https://sandbox.agentnumber.really.com/sms/skills.json — agent skills manifest
- https://sandbox.agentnumber.really.com/sms/agents.txt — agent access policy
- https://sandbox.agentnumber.really.com/sms/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://sandbox.agentnumber.really.com/sms/subscribe

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

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

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

## Example: send SMS

  curl -X POST https://sandbox.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://sandbox.agentnumber.really.com/sms/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://sandbox.agentnumber.really.com/sms/auth \
    -H "Content-Type: application/json" \
    -d '{"wallet": "0x...", "nonce": "'$NONCE'", "signature": "0x..."}'

## Pricing

$1000/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