Agent Number

POST /subscribe

Subscribe to a persistent phone number

Description

Pay $1800/year via x402 (USDC on Base) or MPP to acquire a persistent US phone number bound to your wallet address. Re-paying with the same wallet renews and keeps the same number — the response will set `renewed: true`.

A bare `POST /subscribe` (no payment header) returns `HTTP 402` with a payment challenge in the body listing every accepted scheme + asset. **Always read the challenge — don't hardcode amounts or addresses**. Production settles in USDC on Base mainnet.

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.

Authentication

None. Public endpoint, no auth required.

Code samples

Pick your runtime. Every sample is in the page source — switching tabs is for your eyes.

curl https://agentnumber.really.com/subscribe \
  --request POST \
  --header 'X-PAYMENT: <X-PAYMENT>' \
  --header 'Authorization: <Authorization>'

Headers

NameTypeDescription
X-PAYMENT string Base64-encoded x402 EIP-3009 transferWithAuthorization signature. Present after the agent has parsed the 402 challenge and signed.
Authorization string MPP path: `Payment <base64-credential>` carrying a Tempo TIP-20 charge. Mutually exclusive with `X-PAYMENT`.

Responses

200 Subscription confirmed (new or renewed).

{
  "token": "an_123xyz123xyz123xyz123xyz123xyz",
  "number": "+15555550123",
  "expires_at": "2027-04-30T18:24:01.000Z",
  "renewed": false
}

402 Payment required. Body lists every accepted scheme + asset for the current environment. Sign per `accepts[]` and retry with `X-PAYMENT` or `Authorization: Payment`.

{
  "x402Version": 2,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "amount": "1800000000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x0000000000000000000000000000000000000000",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    }
  ]
}

503 Number pool exhausted. Check `/availability` and join `/waitlist`.

{
  "error": "pool_exhausted",
  "message": "No phone numbers currently available.",
  "check_availability": "/availability",
  "join_waitlist": "/waitlist",
  "available": 0
}