Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt

Use this file to discover all available pages before exploring further.

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"
}
FieldTypePurpose
idstringServer-assigned, opaque, immutable primary key. Prefixed by resource type (wal_, ord_). Safe for logs, audit trails, and database foreign keys.
kindstringResource type discriminator (Tenant.Wallet, Payment.Order). Useful when polymorphic events or logs include resources of mixed types.
<resource>VersionintegerMonotonic snapshot version. Increments on every content mutation. Used for ordering historical snapshots.
namestringHuman-readable, caller-supplied identifier (e.g., the DNS label of a wallet). Unique within the resource type.
selfNamestringCanonical relative resource name in the URL hierarchy (e.g., wallets/production-main/paymentOrders/ord_…).
createdAt / updatedAtstring (ISO 8601)UTC timestamps in YYYY-MM-DDTHH:mm:ss.sssZ format.
etagstring (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:
RuleDetail
Length1–63 characters
Allowed charactersa-z, 0-9, -
First characterMust be a letter
Last characterMust be alphanumeric
CaseLowercase only
UniquenessGlobally unique within the resource type
MutabilityImmutable 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:
ResourceselfName
Walletwallets/production-main
Payment orderwallets/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.

​
Next

Amounts & currency

How money is represented across the API.

Date & time

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