BlooBank API Documentation

A Wallet is the BlooBank platform’s unit of balance and the isolation boundary for every payment order, ledger entry, and webhook event. This page documents the resource model; for the operational mental model, see Wallet overview.

Resource

{
  "id":         "wal_2NhVqRtYbHmRdZ4vG6qAeL",
  "kind":       "Tenant.Wallet",
  "walVersion": 1,
  "status":     "ACTIVE",
  "name":       "production-main",
  "selfName":   "wallets/production-main",
  "createdAt":  "2026-01-15T10:30:00.000Z",
  "updatedAt":  "2026-01-15T10:30:00.000Z",
  "etag":       "9f3b2c1d8a7e6f5b4a3c2d1e0f9e8d7c6b5a493827160504e3d2c1b0a9f8e7d6"
}

Field	Type	Notes
`id`	string	Server-assigned, immutable (`wal_…`). Use as database key.
`kind`	string	Always `Tenant.Wallet`.
`walVersion`	integer	Snapshot version. Increments on each mutation.
`status`	enum	`ACTIVE` or `DISABLED`. See Wallet lifecycle.
`name`	string	RFC 1035 DNS label. 1–63 lowercase chars. Globally unique. Immutable.
`selfName`	string	`wallets/<name>` — portable, base-URL-free reference.
`createdAt` / `updatedAt`	string	UTC ISO 8601 with millisecond precision.
`etag`	string (hex)	Content fingerprint. Reserved for optimistic concurrency.

Endpoints

Operation	Method	Path	Idempotent?
List wallets	`GET`	`/wallets`	✅
Create wallet	`POST`	`/wallets`	❌ (uniqueness via `name`)
Get wallet	`GET`	`/wallets/{wallet}`	✅
Update wallet	`PUT`	`/wallets/{wallet}`	✅
Get balance	`GET`	`/wallets/{wallet}/balance`	✅

Path parameter — `{wallet}`

All sub-resource endpoints accept the wallet in the path as either its id (wal_…) or its name (production-main). Both resolve to the same wallet.

Wallet overview

Mental model, balance breakdown, use cases.

Wallet lifecycle

State machine — ACTIVE, DISABLED, transitions.

Resources & naming

id, selfName, etag, walVersion across all resources.

Amounts & currency

How balance is represented.

Introduction

Conventions

Wallets

Payment Orders

Wallets

Resource

Endpoints

Path parameter — `{wallet}`

Wallet overview

Wallet lifecycle

Resources & naming

Amounts & currency

​Resource

​Endpoints

​Path parameter — {wallet}

​Related concepts

Wallet overview

Wallet lifecycle

Resources & naming

Amounts & currency

Resource

Endpoints

Path parameter — `{wallet}`

Related concepts