Wallet & billing

mog uses a pre-funded wallet for frictionless purchases. Top up once, then buy any package or pay for metered tool calls without a checkout step for each transaction. For agents, the wallet enables fully autonomous purchasing — no payment prompts in the loop.

How the wallet works

1. You top up your wallet with a one-time payment via Stripe
2. When you purchase a package (mog buy or mog install --auto-buy), the price is deducted from your balance
3. When you call a metered tool via the agent network, the per-call cost is deducted from your balance
4. Optionally, auto top-up refills the wallet when your balance drops below a threshold

Free packages don't deduct anything. The wallet is used only when "useWallet": true is passed in the purchase API, or when the CLI uses --auto-buy.

Check your balance

Via CLI

mog auth --status

The status output includes your current wallet balance.

Via API

GET https://api.mog.md/v1/wallet
Authorization: Bearer <token>

{
  "balanceCents": 5000,
  "currency": "usd",
  "autoTopUp": { "enabled": true, "thresholdCents": 1000, "topUpAmountCents": 5000 }
}

Top up your wallet

Via the web

1. Go to Dashboard → Billing
2. Enter a top-up amount
3. Complete payment via Stripe

Via API

POST https://api.mog.md/v1/wallet/top-up
Authorization: Bearer <token>
Content-Type: application/json
 
{ "amountCents": 5000 }

Returns a Stripe clientSecret to confirm the payment:

{ "clientSecret": "pi_xxx_secret_xxx" }

Pass this to Stripe's Payment Element or confirmCardPayment. Your balance is credited once the payment succeeds.

Auto top-up

Configure your wallet to automatically refill when the balance drops below a threshold. This is essential for agents that need to purchase autonomously without running out of funds.

Enable auto top-up

PATCH https://api.mog.md/v1/wallet/auto-top-up
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "enabled": true,
  "thresholdCents": 1000,
  "topUpAmountCents": 5000
}

With this config, whenever your balance drops below $10.00, the wallet automatically charges your saved payment method for $50.00.

Disable auto top-up

PATCH https://api.mog.md/v1/wallet/auto-top-up
Authorization: Bearer <token>
Content-Type: application/json
 
{ "enabled": false }

Requirements

Auto top-up requires a saved payment method. Add one in the Stripe Customer Portal (click Manage payment methods).

Transaction history

View all wallet debits and credits:

GET https://api.mog.md/v1/wallet/transactions?limit=50
Authorization: Bearer <token>

{
  "transactions": [
    {
      "id": "uuid",
      "type": "purchase",
      "amountCents": -500,
      "balanceAfterCents": 4500,
      "description": "acme/react-testing-skill@1.2.0",
      "createdAt": "2026-01-15T10:00:00.000Z"
    },
    {
      "id": "uuid",
      "type": "top_up",
      "amountCents": 5000,
      "balanceAfterCents": 5000,
      "description": "Wallet top-up",
      "createdAt": "2026-01-14T09:00:00.000Z"
    }
  ],
  "cursor": "next-page-cursor"
}

Use cursor from the response to paginate through older transactions.

Insufficient balance

If a purchase would exceed your wallet balance, the API returns HTTP 402:

{
  "status": "insufficient_balance",
  "balanceCents": 200,
  "requiredCents": 500
}

The CLI prints a clear message and exits with code 1. Top up your wallet and retry.

If auto top-up is enabled, the wallet refills first and the purchase succeeds in a single step.

Managing payment methods

Click Manage payment methods in Dashboard → Billing to open the Stripe Customer Portal. From there you can:

• Add or replace credit/debit cards
• View upcoming invoices
• Download past receipts
• Update billing details

Organization wallets

Each organization has its own separate wallet. When the org context is active (mog org switch acme-team), all purchases are deducted from the org wallet.

See Organizations for details on org wallet management, top-ups, and spend policies.

Wallet + spend policies

The wallet and spend policies work together:

1. Spend policy checks whether the purchase is allowed (price limit, vendor allowlist, daily/monthly caps)
2. If allowed, the wallet deducts the amount
3. If the policy blocks it, the purchase fails with an approvalUrl — no wallet deduction

This means an agent with a well-configured spend policy and an auto-topped wallet can purchase safely and autonomously.

For agents

The recommended setup for autonomous agents:

1. Create an API token with purchase + download scopes
2. Attach a spend policy to the token with appropriate limits
3. Top up the wallet with enough balance for expected usage
4. Enable auto top-up so the agent never runs dry
5. Set MOG_TOKEN in the agent's environment

The agent can then run mog install --auto-buy --json freely within the policy guardrails.