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

PlanMonthlyYearly
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.
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.
EndpointWhat it doesCost
GET /agent/x402/subscriptionReturns plan status, credits, and API keys for the wallet$0.001 USDC
GET /agent/x402/subscribeCreates or renews the agent; returns api_key and user_idPlan price
GET /agent/x402/top-upAdds credits to the agent’s limitamount_usd (min $20)
GET /agent/x402/api-keys/createCreates 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 · 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.
ConditionWhat to do
plan_active === true and plan is not FreeAlready subscribed — do not subscribe again
plan_active !== trueNo active plan — subscribe before topping up
The scripts below handle this check automatically. 
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.
GET /agent/x402/subscribe?plan=startup&payment_frequency=monthly HTTP/1.1
Host: api.mobula.io
Store both returned values:
ValueUse
api_keyAuthorization header on all API requests
user_idagent_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.
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) — 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: 
curl 'https://api.mobula.io/api/1/market/data?asset=ethereum' \
  -H 'Authorization: <your_api_key>'