Agent Number

Quickstart

Zero to a working US mobile number in four curl calls. After this you'll have a real phone number tied to your wallet, sending and receiving SMS.

1. Check availability

Numbers release in waves. Always check supply before subscribing: 

curl https://agentnumber.really.com/availability
# → {"available": 12}

If available is 0, jump to Waitlist below. Otherwise continue.

2. Subscribe

POST/subscribe is a payable endpoint. A bare POST returns HTTP 402 with the x402 challenge body. MPP is discoverable separately at /.well-known/mpp.json — clients pick a rail and retry with the matching header (X-PAYMENT for x402, Authorization: Payment for MPP): 

curl -X POST https://agentnumber.really.com/subscribe
# → 402 + JSON body with payment instructions

Pay per the challenge (see Payment), then re-POST with the payment header: 

curl -X POST https://agentnumber.really.com/subscribe \
  -H "X-PAYMENT: <base64-encoded-x402-payment>"
# → 200 + {"token": "...", "number": "+1...", "expires_at": "...", "renewed": false}

The response gives you a phone number, a bearer token, and the expiry timestamp. Store the bearer; use it for every subsequent SMS / voice call.

Wallet warning. Your wallet address is the permanent account identity. If you lose access to the paying wallet, you cannot recover the number or remaining subscription time. Use a durable wallet, not a per-session ephemeral one. See Auth for recovery flow.

3. 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"}'
# → 200 + {"message_id": "...", "status": "queued"}

4. Receive an SMS

/sms/receive returns currently undelivered messages atomically (marks delivered_at so a parallel call doesn't double-deliver). For long-poll behavior, use the MCP receive_sms tool, which polls this primitive: 

curl https://agentnumber.really.com/sms/receive \
  -H "authorization: Bearer <token>"
# → 200 + {"messages": [{"id": ..., "from_number": "...", "body": "...", ...}], "count": 1}

No numbers available?

Number pools release in waves as REALLY expands inventory. Join the waitlist: 

curl -X POST https://agentnumber.really.com/waitlist \
  -H "content-type: application/json" \
  -d '{"email": "you@example.com"}'
# → {"status": "added", "registered_at": "..."}

You can also keep polling /availability — when it returns available > 0, the subscribe path is open again.

What's next

llms.txt OpenAPI MCP server card x402.json mpp.json Agent card Agent skills SKILL.md sitemap.xml Glossary