Data Model
The three things that make Agent Number work: numbers, subscriptions, and tokens. They map to one another in fixed ways — knowing the relationships removes most questions a developer has on day one.
Number
A real US mobile number. Issued from a pool. While the subscription is active the number is yours; when the subscription expires the number goes back to the pool unless renewed by the original wallet.
Subscription
A one-year-paid binding between a wallet and a number. Created by
POST /subscribe after a successful x402
or MPP payment. Renew by paying again with the same wallet — the
number stays the same and renewed: true comes back
in the response.
Token
An opaque bearer string. Required on every authenticated request. Rotated every time the wallet recovers via signature (every prior token is revoked, fresh one issued).
How they relate
| From | To | Cardinality |
|---|---|---|
| Wallet | Subscription | 1 : 1 active at a time |
| Subscription | Number | 1 : 1 (one number per active sub) |
| Subscription | Tokens | 1 : N (re-mintable, all revocable) |
What this means in practice
- If you lose a token, recover via
POST /auth/nonce+POST /auth— the wallet's signature is enough. - If you lose access to the paying wallet, you cannot recover the number. There is no admin override. Use a durable wallet you control long-term.
- Two agents on the same subscription can each hold their own bearer (mint a new one whenever you need it). Recovery rotates every existing token, so multi-agent setups need to re-auth in lockstep.
Where to go next
- Auth — bearer tokens + recovery
- Payment — x402 + MPP rails
- GET /number — confirm which number a token is bound to