# Really SMS

Sandbox: persistent SMS phone numbers for AI agents.

## What this is

A persistent SMS phone number service for AI agents. Pay $1000/year in USDC
via x402 (or via MPP) and receive a real US phone number bound to your
wallet address. Send and receive SMS via REST or via the MCP server at
https://sandbox.agentnumber.really.com/sms/mcp.

## Endpoints

- 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