Skip to main content

​
x402 Subscription and top-up

Agent subscription is in beta. Plans, minimums, and networks may change.
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

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.
The $0.001 USDC charged on subscription status checks is a facilitator fee for x402 protocol settlement — it does not go to Mobula.

​
Endpoints

All endpoints are under https://api.mobula.io. Per-endpoint reference: x402 Get subscription status · x402 Subscribe to a plan · x402 Top up credits · x402 Create API key · x402 Revoke API key

​
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. The scripts below handle this check automatically.

​
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.
Store both returned values:

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

​
Learn more

External x402 references:
  • x402 (CDP) — Protocol overview, facilitators, and SDKs
  • x402.org — Open standard for HTTP-native payments

​
Using Your API Key

Once subscribed, authenticate all data requests with your api_key: