---
title: Quickstart
description: Agent Number quickstart — from zero to a working US mobile number in 2 minutes.
url: https://agentnumber.really.com/docs/quickstart
doc_version: "1.0.0"
last_updated: "2026-05-15"
---

> ## Documentation index
> Fetch the complete documentation index at: https://agentnumber.really.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

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

If `available` is `0`, jump to [Waitlist](#no-numbers-available) 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](/.well-known/mpp.json) — clients pick a rail and retry with the matching header (`X-PAYMENT` for x402, `Authorization: Payment` for MPP):

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

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

```bash
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](/docs/auth) for the recovery flow.

## 3. Send your first SMS

```bash
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:

```bash
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:

```bash
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

- [MCP integration](/docs/mcp) — connect your agent runtime via Model Context Protocol
- [Voice](/docs/voice) — place and receive voice calls on the same number
- [Auth](/docs/auth) — wallet-signature recovery if you lose your bearer token
- [Full API reference](/docs/#api-reference)

## Sitemap

- [Overview](/docs/)
- [Quickstart](/docs/quickstart)
- [Authentication](/docs/auth)
- [SMS](/docs/sms)
- [Voice](/docs/voice)
- [MCP](/docs/mcp)
- [Payment](/docs/payment)

See the full [sitemap.md](/sitemap.md) for the complete index of docs pages.

---

← Previous: [Overview](/docs/) · Next: [MCP](/docs/mcp) →