---
title: Payment
description: Agent Number payment — x402 and MPP rails over USDC.
url: https://agentnumber.really.com/docs/payment
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.

# Payment

> Agent Number accepts USDC over two payment rails: x402 (Coinbase-verified, Base) and MPP (Tempo). One year of unlimited SMS + voice for $1800 USDC.

## Pricing

| Item | Cost |
| --- | --- |
| One phone number, 1 year, unlimited SMS + voice | $1800 USDC |
| Check availability (`GET /availability`) | Free |
| Join waitlist (`POST /waitlist`) | Free |
| Pay via x402 or MPP | No surcharge |
| Per-message / per-minute | None during the subscription year |

## The 402 challenge

`POST` `/subscribe` with no payment header returns `HTTP 402` with the x402 challenge body shown below. MPP is reachable on the same endpoint but 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
# {
#   "x402Version": 2,
#   "error": "X-PAYMENT header is required",
#   "accepts": [
#     {
#       "scheme": "exact",
#       "network": "base",
#       "amount": "1800000000",
#       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#       "payTo": "0x...",
#       "maxTimeoutSeconds": 300,
#       "extra": { "name": "USDC", "version": "2" }
#     }
#   ]
# }
```

Parse `accepts[]` to determine the active payment scheme + asset. Production settles in USDC on Base mainnet (x402) or pathUSD on Tempo mainnet (MPP). Don't hardcode — read from the live challenge or discovery file.

## x402 (Coinbase-verified, Base)

x402 is a payment-required HTTP scheme. After parsing the challenge, sign a transferWithAuthorization message authorizing USDC transfer of `amount` from your wallet to `payTo`, then encode + retry:

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

The Coinbase x402 facilitator ([x402.org](https://www.x402.org/)) verifies the signed payment and settles on-chain. Your wallet doesn't need gas — settlement happens via meta-transaction.

## MPP (Tempo) — pathUSD on Tempo mainnet

MPP is an alternative rail using Tempo's payment protocol. Same product, same price; different signing scheme. Build a Tempo charge credential with the [mppx SDK](https://github.com/coinbase/mppx-sdk) and retry with `Authorization: Payment` instead of `X-PAYMENT`:

```bash
curl -X POST https://agentnumber.really.com/subscribe \
  -H "Authorization: Payment <base64-encoded-credential>"
# → 200 (same response shape as the x402 path)
```

Or use the `npx mppx` CLI to auto-handle the 402 → sign → retry end-to-end:

```bash
npx mppx https://agentnumber.really.com/subscribe --method POST
# one-time setup: npx mppx account create
```

OpenAPI advertises MPP support per-operation via `x-payment-info` per the [mpp.dev discovery spec](https://mpp.dev/advanced/discovery):

```json
"x-payment-info": {
  "amount": "1800000000",
  "currency": "0x20c0000000000000000000000000000000000000",
  "description": "One persistent US mobile number, 1-year subscription (SMS + voice)",
  "intent": "charge",
  "method": "tempo"
}
```

## Renewal

Re-paying with the same wallet renews the subscription and keeps the same phone number. The response field `renewed: true` indicates a renewal vs new issuance.

## Common errors

| Status | Meaning |
| --- | --- |
| `402` | Payment required — parse `accepts[]`, sign, retry with `X-PAYMENT` or `Authorization: Payment` |
| `402` on retry | Payment header malformed or signature invalid — verify amount + asset + payTo against the challenge |
| `503` | Number pool exhausted — check `/availability` + `/waitlist` |
| `500` w/ `facilitator_unavailable` | x402 / MPP facilitator returned an error — usually transient, retry |

## 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: [Auth](/docs/auth) · Next: [Voice](/docs/voice) →