Prepaid Wallet

The Aerostack wallet is a prepaid balance that covers variable-cost operations: bot conversations, agent endpoint executions, and paid marketplace tool calls. Fund it via Stripe, and costs are deducted automatically as you use the platform.

How the Wallet Works

1. Deposit funds into your wallet via Stripe checkout ($5 minimum, $500 maximum per deposit)
2. Use bots, agents, and marketplace tools — costs deduct from your balance automatically
3. Monitor your balance and transaction history via the API or dashboard
4. Auto-reload (optional) to maintain a minimum balance without manual top-ups

Wallet Balance: $25.00
  |
  Bot conversation  → -$0.02
  Agent execution   → -$0.05
  Tool call (paid)  → -$0.01
  |
Wallet Balance: $24.92

Check Your Balance

API

curl https://api.aerostack.dev/api/balance \
  -H "Authorization: Bearer YOUR_JWT"

Response:

{
  "balance_cents": 2500,
  "currency": "usd",
  "auto_reload": {
    "enabled": false,
    "threshold_cents": null,
    "amount_cents": null
  },
  "lifetime_deposited_cents": 10000,
  "lifetime_spent_cents": 7500
}

The balance_cents field is your current spendable balance in cents (e.g. 2500 = $25.00).

Dashboard

Navigate to Settings > Billing > Wallet in the Aerostack Dashboard to see your balance, recent transactions, and auto-reload configuration.

Deposit Funds

Create a Stripe checkout session to add funds to your wallet.

curl -X POST https://api.aerostack.dev/api/balance/deposit \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 2500,
    "success_url": "https://app.aerostack.dev/settings/billing?deposit=success",
    "cancel_url": "https://app.aerostack.dev/settings/billing"
  }'

Parameters:

Response:

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Redirect the user to the returned URL to complete the Stripe checkout. After payment, the user is redirected to your success_url.

Verify Deposit

After Stripe redirects back to your success_url, verify the deposit was credited:

curl "https://api.aerostack.dev/api/balance/verify?session_id=cs_live_..." \
  -H "Authorization: Bearer YOUR_JWT"

Response:

{
  "deposited": true,
  "amount_cents": 2500
}

Transaction History

View your wallet transaction history with pagination.

curl "https://api.aerostack.dev/api/balance/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_JWT"

Response:

{
  "transactions": [
    {
      "id": "txn-uuid-1",
      "type": "deposit",
      "amount_cents": 2500,
      "description": "Stripe deposit",
      "created_at": 1710500000
    },
    {
      "id": "txn-uuid-2",
      "type": "debit",
      "amount_cents": -5,
      "description": "Bot conversation: support-bot",
      "created_at": 1710500100
    },
    {
      "id": "txn-uuid-3",
      "type": "debit",
      "amount_cents": -12,
      "description": "Agent execution: code-reviewer",
      "created_at": 1710500200
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Query Parameters:

Transaction Types

Auto-Reload

Configure automatic wallet top-ups to avoid running out of balance during active usage.

curl -X POST https://api.aerostack.dev/api/balance/auto-reload \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold_cents": 500,
    "amount_cents": 2500
  }'

Parameters:

Example: With threshold_cents: 500 and amount_cents: 2500, when your balance drops below $5.00, Aerostack automatically charges your Stripe payment method for $25.00.

Disable Auto-Reload

curl -X POST https://api.aerostack.dev/api/balance/auto-reload \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Spending Caps

You can set per-bot spending caps to prevent runaway costs:

• Per-conversation cap — maximum wallet spend per individual conversation
• Daily cap per bot — maximum wallet spend per bot per day
• Monthly cap per bot — maximum wallet spend per bot per month

When a cap is reached, the bot responds with a friendly message indicating the spending limit has been reached for the period.

Minimum Balance Warnings

The dashboard shows warnings when your wallet balance is low:

When your balance reaches $0.00, pay-per-use operations (bot conversations, agent executions, paid tool calls) are paused. Your bots and agents remain configured but respond with a “wallet empty” message until you deposit more funds.

Developer Earnings

If you publish tools, functions, or agents on the Aerostack marketplace, your earnings accumulate in a separate developer balance.

How Creator Earnings Work

1. A consumer calls your paid marketplace tool
2. The consumer’s wallet is debited for the tool price
3. Your developer balance is credited (minus the marketplace fee)
4. Accumulated earnings can be paid out via Stripe Connect

View Earnings

curl https://api.aerostack.dev/api/community/earnings \
  -H "Authorization: Bearer YOUR_JWT"

Response:

{
  "balance_cents": 4200,
  "lifetime_earned_cents": 15000,
  "lifetime_paid_out_cents": 10800,
  "pending_payout_cents": 4200
}

Payout Schedule

Earnings are paid out via Stripe Connect on a configurable schedule:

• Manual — request payouts from the dashboard
• Weekly — automatic payout every Monday
• Monthly — automatic payout on the 1st of each month

Minimum payout threshold: $10.00.

BYOK (Bring Your Own Key)

When you configure your own LLM API keys, wallet deductions for LLM-powered operations are eliminated:

You still pay your LLM provider directly for API usage. BYOK eliminates the Aerostack markup, giving you the raw provider pricing.

Configure BYOK keys in Settings > AI > API Keys in the dashboard.

API Reference