# Prepaid Wallet

> The Aerostack prepaid wallet — deposit credits for bot conversations, agent endpoint runs, and paid marketplace calls. Costs deducted automatically.

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

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

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

**Response:**

```json
{
  "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.

```bash
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:**

```json
{
  "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:

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

**Response:**

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

  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.

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

**Response:**

```json
{
  "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.

```bash
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.

  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

```bash
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.

  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

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

**Response:**

```json
{
  "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 |