> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Subscription and top-up

> x402 Subscription and top-up: subscribe an agent and add credits via USDC on Base or Solana.

# x402 Subscription and top-up

<Warning>
  Agent subscription is in beta. Plans, minimums, and networks may change.
</Warning>

This guide covers how to subscribe an agent to a paid plan and add credits via top-up using the **x402** rail — paying in USDC on Base or Solana.

***

## How It Works

Agent access is built on two things: a **plan** and **credits**.

* A **plan** (Startup, Growth, or Enterprise) sets your agent's credit limit and billing cycle. You pay the plan price once per period.
* **Credits** are consumed by API usage. When credits run low, top up to add more without changing your plan.
* Your **wallet** is your identity. The same wallet used to subscribe is used for status checks and top-ups.
* After subscribing, you receive an `api_key` (for `Authorization` headers) and a `user_id` (used as `agent_id` for top-ups). Store both.

***

## Pricing

| Plan           | Monthly               | Yearly                  |
| -------------- | --------------------- | ----------------------- |
| **Startup**    | \$50                  | \$400                   |
| **Growth**     | \$400                 | \$4,200                 |
| **Enterprise** | \$750 base + variable | \$7,200 base + variable |

Enterprise pricing includes a base fee plus a variable component based on usage. Contact the Mobula team for a quote.

Top-ups are a minimum of **\$20 USDC** and go directly to Mobula.

<Info>
  The **\$0.001 USDC** charged on subscription status checks is a facilitator fee for x402 protocol settlement — it does not go to Mobula.
</Info>

***

## Endpoints

All endpoints are under `https://api.mobula.io`.

| Endpoint                                      | What it does                                                 | Cost                    |
| --------------------------------------------- | ------------------------------------------------------------ | ----------------------- |
| `GET /agent/x402/subscription`                | Returns plan status, credits, and API keys for the wallet    | \$0.001 USDC            |
| `GET /agent/x402/subscribe`                   | Creates or renews the agent; returns `api_key` and `user_id` | Plan price              |
| `GET /agent/x402/top-up`                      | Adds credits to the agent's limit                            | `amount_usd` (min \$20) |
| `GET /agent/x402/api-keys/create`             | Creates a new API key for this agent                         | \$0.001 USDC            |
| `DELETE /agent/x402/api-keys/revoke?api_key=` | Revokes an API key for this agent                            | \$0.001 USDC            |

Per-endpoint reference: [x402 Get subscription status](/guides/x402-agent-subscription) · [x402 Subscribe to a plan](/guides/x402-agent-subscribe) · [x402 Top up credits](/guides/x402-agent-topup) · [x402 Create API key](/guides/x402-agent-api-key-create) · [x402 Revoke API key](/guides/x402-agent-api-key-revoke)

***

## Check Plan Status

Every flow starts with a call to `GET /agent/x402/subscription`. This costs \$0.001 USDC and returns the current state of the wallet before taking any action.

| Condition                                   | What to do                                   |
| ------------------------------------------- | -------------------------------------------- |
| `plan_active === true` and plan is not Free | Already subscribed — do not subscribe again  |
| `plan_active !== true`                      | No active plan — subscribe before topping up |

The scripts below handle this check automatically.

```http theme={null}
GET /agent/x402/subscription HTTP/1.1
Host: api.mobula.io
```

***

## Subscribe to a Plan

Subscribing creates (or renews) your agent and returns an `api_key` and `user_id`.

**Flow:**

1. Call `GET /agent/x402/subscription` → pay \$0.001 USDC → check plan status.
2. If `plan_active === true` and plan is not Free → stop, already subscribed.
3. Otherwise → call `GET /agent/x402/subscribe?plan=...&payment_frequency=...` → receive **402** with the plan price.
4. Sign the payment and retry with the `x-payment` header → **200 OK** returns `api_key` and `user_id`.

```http theme={null}
GET /agent/x402/subscribe?plan=startup&payment_frequency=monthly HTTP/1.1
Host: api.mobula.io
```

**Store both returned values:**

| Value     | Use                                        |
| --------- | ------------------------------------------ |
| `api_key` | `Authorization` header on all API requests |
| `user_id` | `agent_id` parameter when topping up       |

***

## Top Up Credits

Top up to add credits to your agent's limit without changing the plan. Minimum **\$20 USDC**.

**Flow:**

1. Call `GET /agent/x402/subscription` → pay \$0.001 USDC → confirm plan is active.
2. If `plan_active !== true` → subscribe first before topping up.
3. Otherwise → call `GET /agent/x402/top-up?agent_id=<user_id>&amount_usd=<amount>` → receive **402** with the payment amount.
4. Sign the payment and retry with the `x-payment` header → **200 OK** returns `credits_added` and `new_credits_limit`.

```http theme={null}
GET /agent/x402/top-up?agent_id=<user_id>&amount_usd=20 HTTP/1.1
Host: api.mobula.io
```

***

## Learn more

External **x402** references:

* **[x402 (CDP)](https://docs.cdp.coinbase.com/x402/welcome)** — Protocol overview, facilitators, and SDKs
* **[x402.org](https://www.x402.org/)** — Open standard for HTTP-native payments

***

## Using Your API Key

Once subscribed, authenticate all data requests with your `api_key`:

```bash theme={null}
curl 'https://api.mobula.io/api/1/market/data?asset=ethereum' \
  -H 'Authorization: <your_api_key>'
```