# Wallet

One prepaid wallet per organization, in USD, accounted in integer microdollars on an immutable ledger. Every reserve, settle, release, top-up, bonus and refund is a ledger entry you can read back.

## Balance

```text
GET /v1/wallet
```

```json
{"currency": "USD", "balance": "24.35", "reserved": "0.10", "available": "24.25"}
```

`reserved` is held by in-flight runs; `available` is what new runs can reserve against.

## Transactions

```text
GET /v1/wallet/transactions
```

Newest first, `limit` default 50, max 200:

```json
{
  "items": [
    {
      "id": "txn_...",
      "type": "settle",
      "amount": "-0.05",
      "balance_after": "24.30",
      "reference": "run_...",
      "note": null,
      "created_at": "2026-09-02T09:30:01+00:00"
    }
  ]
}
```

## Top up

```text
POST /v1/wallet/topups/checkout
```

```json
{"amount": "20"}
```

Minimum self-service top-up is $20.00. In production this returns a Stripe Checkout URL:

```json
{"status": "checkout", "checkout_url": "https://checkout.stripe.com/...", "session_id": "cs_..."}
```

The wallet is credited by the verified Stripe webhook once payment succeeds, never by this endpoint's response. In the sandbox (test keys, no Stripe), the same call credits a clearly-labeled simulated top-up so the full flow is testable.

## Auto top-up

```text
GET  /v1/wallet/auto-topup
POST /v1/wallet/auto-topup
```

```json
{"enabled": true, "threshold": "10", "amount": "20"}
```

When the balance drops below `threshold`, the saved card is charged `amount`. Requires Stripe (a completed checkout with a saved payment method); `last_error` in the GET response surfaces a failing card.

## Referrals

```text
GET /v1/referrals
```

Your referral code and link, the program terms, and what your referrals have earned you. The code is minted on first call. The referred workspace gets a bonus on its first qualifying deposit; you earn a share of net revenue on their runs for a limited period ([current terms](/pricing)).