> ## 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.

# Resources & naming

> How resources are identified — id, selfName, etag, kind, and version fields.

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:

```json theme={"dark"}
{
  "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.

<CardGroup cols={2}>
  <Card title="id" icon="hashtag">
    Server-assigned. Opaque (`wal_2NhVqRtYbHmRdZ4vG6qAeL`). Immutable. **Use as your database key.**
  </Card>

  <Card title="name" icon="tag">
    Caller-supplied during creation. Human-readable (`production-main`). **Use in URLs and human-facing flows.**
  </Card>
</CardGroup>

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`. |

```text theme={"dark"}
✓ 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.

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

## 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](/get-started/concepts/date-and-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:

```http theme={"dark"}
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

<CardGroup cols={2}>
  <Card title="Amounts & currency" icon="coins" href="/get-started/concepts/amounts-and-currency">
    How money is represented across the API.
  </Card>

  <Card title="Date & time" icon="clock" href="/get-started/concepts/date-and-time">
    UTC, ISO 8601, and request-signing clock skew.
  </Card>
</CardGroup>