Prepaid Wallet

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

---

How the Wallet Works

1. Deposit funds into your wallet ($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

Note

BYOK (Bring Your Own Key) eliminates wallet costs for LLM operations. When you provide your own API keys for OpenAI, Anthropic, or other providers, the platform charges $0 for those operations. You pay your LLM provider directly.

---

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 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:

Field	Type	Required	Constraints
amount_cents	number	Yes	Min 500 ($5.00), max 50000 ($500.00)
success_url	string	Yes	Redirect URL after successful payment
cancel_url	string	Yes	Redirect URL if user cancels

Response:

{
  "url": "https://checkout.example.com/..."
}

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

Verify Deposit

After the checkout 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
}

Caution

The success_url and cancel_url must be on an allowed origin (app.aerostack.dev, *.aerostack-admin.pages.dev, or localhost:5173). Other origins are rejected with a 400 error.

---

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": "Wallet 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:

Parameter	Type	Default	Constraints
limit	number	50	1-200
offset	number	0	0+

Transaction Types

Type	Description
deposit	Funds added to wallet
debit	Funds deducted for usage
refund	Funds returned (e.g. failed operation)
earning	Revenue from marketplace (for creators)
payout	Payout to your bank (for creators)

---

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:

Field	Type	Required	Description
enabled	boolean	Yes	Enable or disable auto-reload
threshold_cents	number	No	Reload when balance drops below this (min 0)
amount_cents	number	No	Amount to deposit on each reload (min 500 / $5.00)

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

Note

Auto-reload requires a payment method on file. If the automatic charge fails (e.g. expired card), auto-reload is paused and you receive an email notification.

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.

Note

Spending caps are configured per-bot in the bot settings, not at the wallet level. See the Bots documentation for configuration details.

---

Minimum Balance Warnings

The dashboard shows warnings when your wallet balance is low:

Balance	Warning Level
Below $5.00	Yellow warning banner
Below $1.00	Red critical banner
$0.00	Operations that require wallet balance are blocked

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 to your bank

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 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:

Operation	With Platform Key	With BYOK
Bot conversation (GPT-4)	$0.02-0.10/message	$0.00
Agent execution	$0.05-0.25/run	$0.00
Embedding generation	$0.001/1K tokens	$0.00

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

Endpoint	Method	Description
/api/balance	GET	Current balance and auto-reload config
/api/balance/transactions	GET	Paginated transaction history
/api/balance/deposit	POST	Create checkout session for deposit
/api/balance/verify	GET	Verify deposit after checkout redirect
/api/balance/auto-reload	POST	Configure auto-reload settings