Ysra Docs

Wallet

Read the account wallet, set its budget, add credit and page through the ledger. Every amount is a decimal string.

On this page

The wallet is account-wide: it belongs to your organisation when you are a member of one, and to you otherwise. Sessions reserve from it while they run and settle what they spend.

No payment integration

Adding credit is an administrative action. Ledger entries record payment_provider: null; nothing here is a purchase.

A new wallet starts with enforced: false and keeps per-session budgets until the owner sets a budget or adds credit.

Get the wallet#

GET /developer/account/wallet

200 OK · DeveloperCreditAccountRead
{
  "id": "3f6c…",
  "owner_kind": "client",        // "client" or "user"
  "owner_id": "a41e…",
  "currency": "USD",
  "budget_usd": "200.000000",
  "reserved_usd": "10.000000",
  "spent_usd": "18.250000",
  "available_usd": "171.750000", // budget − reserved − spent
  "enforced": true,
  "version": 3,
  "created_at": "2026-09-01T08:12:44Z",
  "updated_at": "2026-09-26T17:03:10Z"
}

Show available_usd to people, not a per-session cap.

Set the budget#

PUT /developer/account/wallet

Sets the total budget — not a delta. The new budget cannot be lower than spent_usd + reserved_usd.

budget_usd string required
The new total budget, as a decimal string: "200.00".
idempotency_key string required
Unique per logical action, up to 255 characters. Reuse it when retrying the same action.
expected_version integer optional
The version you last read. Omit it on the first write.
note string optional
Recorded on the ledger entry.
Request
{
  "budget_usd": "200.00",
  "idempotency_key": "budget-2026-09-27-7f3a",
  "expected_version": 2,
  "note": "Q4 engineering budget"
}
Status Meaning
200 Updated. The body is the new wallet.
409 Version conflict, or the budget is below what is already committed.
422 Validation failed.
503 The execution account is temporarily unavailable. Retry with backoff.

Add credit#

POST /developer/account/wallet/credits

Adds an amount to the current budget.

amount_usd string required
The amount to add, as a decimal string.
idempotency_key string required
As above.
note string optional
Recorded on the ledger entry.

List ledger entries#

GET /developer/account/wallet/ledger

Newest first. Page backwards with the last entry's id as before.

before uuid optional
Return entries older than this entry. An unknown id returns 404.
limit integer optional
1–500. Default 100.

Each entry has an id, a kind, the amount_usd, the wallet balances after it (budget_after_usd, reserved_after_usd, spent_after_usd, available_after_usd) and, where relevant, the session and task it belongs to.

kind Written when
budget_set The total budget changes.
credit_added Credit is added.
reserve A session reserves funds before running.
reserve_release Unused reservation is returned.
spend Work is settled.
YsraDocs