---
title: Data Model - Numbers, subscriptions, tokens — Concepts
description: The three primitives Agent Number is built on, and how they relate.
url: https://agentnumber.really.com/docs/concepts/data-model
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.

# 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`](/docs/reference/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`](/docs/reference/auth-nonce) + [`POST /auth`](/docs/reference/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](/docs/auth) — bearer tokens + recovery
- [Payment](/docs/payment) — x402 + MPP rails
- [GET /number](/docs/reference/number) — confirm which number a token is bound to

---

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