BlooBank API Documentation

Every resource in the BlooBank API carries a consistent set of identifier and metadata fields. Learning this shape once gives you a mental model that applies to every endpoint — wallets, payment orders, and any resource added in the future.

The standard envelope

Every resource includes these fields:

{
  "id": "wal_2NhVqRtYbHmRdZ4vG6qAeL",
  "kind": "Tenant.Wallet",
  "walVersion": 1,
  "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	Purpose
`id`	string	Server-assigned, opaque, immutable primary key. Prefixed by resource type (`wal_`, `ord_`). Safe for logs, audit trails, and database foreign keys.
`kind`	string	Resource type discriminator (`Tenant.Wallet`, `Payment.Order`). Useful when polymorphic events or logs include resources of mixed types.
`<resource>Version`	integer	Monotonic snapshot version. Increments on every content mutation. Used for ordering historical snapshots.
`name`	string	Human-readable, caller-supplied identifier (e.g., the DNS label of a wallet). Unique within the resource type.
`selfName`	string	Canonical relative resource name in the URL hierarchy (e.g., `wallets/production-main/paymentOrders/ord_…`).
`createdAt` / `updatedAt`	string (ISO 8601)	UTC timestamps in `YYYY-MM-DDTHH:mm:ss.sssZ` format.
`etag`	string (hex)	Content fingerprint of the resource. Reserved for optimistic concurrency control via `If-Match` in a future release.

Two flavors of identifier

Most BlooBank resources expose two identifiers, and choosing the right one for your use case matters.

id

Server-assigned. Opaque (wal_2NhVqRtYbHmRdZ4vG6qAeL). Immutable. Use as your database key.

name

Caller-supplied during creation. Human-readable (production-main). Use in URLs and human-facing flows.

The API accepts either id or name in path parameters for most endpoints — e.g., GET /wallets/{wallet} works with both wal_… and production-main. Internally, the API resolves the name to the id before processing.

Naming rules

name follows RFC 1035 DNS label rules:

Rule	Detail
Length	1–63 characters
Allowed characters	`a-z`, `0-9`, `-`
First character	Must be a letter
Last character	Must be alphanumeric
Case	Lowercase only
Uniqueness	Globally unique within the resource type
Mutability	Immutable after creation. Attempting to change it returns `LABEL_IMMUTABLE`.

✓ production-main
✓ wallet-1
✓ tenant-acme-prod
✗ Production-Main      (uppercase)
✗ -wallet               (leading dash)
✓ wal-                 ✗ wallet-               (trailing dash — wait, that's also wrong)
✗ 1-wallet              (leading digit)

Versioning fields

Different resources expose different *Version fields — walVersion for wallets, ordVersion for payment orders. The pattern is the same:

Starts at 1 on creation.
Increments by 1 on every mutation of the resource’s tracked content.
Useful when reasoning about historical snapshots from event streams.

*Version is for tracking content changes, not concurrency control. For optimistic concurrency, use etag with the If-Match header (when the feature lands).

The `selfName` convention

selfName is the canonical relative name of the resource — the path you would use to reference it inside the API. Examples:

Resource	`selfName`
Wallet	`wallets/production-main`
Payment order	`wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ`

Compare with the full URL:

https://txengine.bloobank.com/txengine/v1/wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ
                                          ^                                                              ^
                                          └──────────────── this part is selfName ──────────────────────┘

selfName is what you would log or persist when you need a portable, base-URL-agnostic reference.

Timestamps

All timestamps are ISO 8601 in UTC with millisecond precision:

2026-01-15T10:30:00.000Z

The trailing Z is required. The API never returns timestamps in local time. See Date & time for client-side parsing notes.

`etag` — reserved

Every resource carries an etag — a hex-encoded SHA-256 fingerprint of the resource content. Today it is informational only. In a future release, it will support optimistic concurrency control via the If-Match request header:

PUT /wallets/production-main HTTP/1.1
If-Match: 9f3b2c1d8a7e6f5b4a3c2d1e0f9e8d7c6b5a493827160504e3d2c1b0a9f8e7d6
Content-Type: application/json

{ "status": "DISABLED" }

When this lands, requests with a stale etag will fail fast with a clear error rather than overwriting a concurrent modification.

Amounts & currency

How money is represented across the API.

Date & time

UTC, ISO 8601, and request-signing clock skew.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Resources & naming

The standard envelope

Two flavors of identifier

id

name

Naming rules

Versioning fields

The `selfName` convention

Timestamps

`etag` — reserved

Next

Amounts & currency

Date & time

​The standard envelope

​Two flavors of identifier

id

name

​Naming rules

​Versioning fields

​The selfName convention

​Timestamps

​etag — reserved

​Next

Amounts & currency

Date & time

The standard envelope

Two flavors of identifier

Naming rules

Versioning fields

The `selfName` convention

Timestamps

`etag` — reserved

Next