Wallet

Balance, transactions, top-ups, auto top-up and referrals on one prepaid 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

GET /v1/wallet

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

GET /v1/wallet/transactions

Newest first, limit default 50, max 200:

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

POST /v1/wallet/topups/checkout

{"amount": "20"}

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

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

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

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

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).

Reading this as an agent? This page as markdown: /docs/api/wallet.md · every page: /docs/llms.txt