Wallets - Assistable.ai Docs

A Direct account spends from a wallet to run chat and voice. There are two balance planes:

Workspace wallet — what the spend gate reads. Fund this to let the account actually run AI.
Sub-account wallet — a per-sub balance you can track separately.

All amounts are integer cents. The wallet endpoints need the billing:read scope (balance) and billing:update scope (credit/debit) — a key with only subaccounts:* scopes cannot move funds.

Check balances

curl https://api.assistable.ai/v3/subaccounts/sub_123/wallet \
  -H "Authorization: Bearer ask_live_xxx"

{
  "data": {
    "subAccountId": "sub_123",
    "subAccountBalanceCents": 2500,
    "subAccountBalanceDollars": 25,
    "workspaceBalanceCents": 10000,
    "workspaceBalanceDollars": 100
  },
  "error": null,
  "request_id": "req_…"
}

Credit a wallet

curl https://api.assistable.ai/v3/subaccounts/sub_123/wallet/credit \
  -H "Authorization: Bearer ask_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000, "target": "workspace", "idempotency_key": "topup-2026-06-18-a" }'

Field	Required	Notes
`amount_cents`	yes	Amount to move, in integer cents (1–100,000,000).
`target`	no	`workspace` (default — the spend-gate plane) or `subaccount`.
`description`	no	Audit note stored on the ledger transaction.
`idempotency_key`	yes	Repeating a credit/debit with the same key returns the original result without moving funds again.

The response reports the resulting balance and whether it was an idempotent replay:

{
  "data": {
    "subAccountId": "sub_123",
    "target": "workspace",
    "direction": "credit",
    "amountCents": 5000,
    "balanceCents": 15000,
    "balanceDollars": 150,
    "replayed": false
  },
  "error": null,
  "request_id": "req_…"
}

Debit a wallet

POST /v3/subaccounts/{id}/wallet/debit takes the same body and claws funds back. A debit can never drive a balance negative — if the target plane doesn’t have enough, it returns 409 insufficient_balance and no funds move.

The idempotency_key is required on every credit and debit. If a request times out and you retry with the same key, the wallet moves exactly once.

​Check balances

​Credit a wallet

​Debit a wallet

Check balances

Credit a wallet

Debit a wallet