BlooBank API Documentation

The BlooBank API uses a single time representation everywhere: UTC ISO 8601 with millisecond precision. There are no time zones in the API contract — the burden of localization sits on your client.

Timestamps in responses

Every timestamp returned by the API is formatted:

YYYY-MM-DDTHH:mm:ss.sssZ

Examples:

2026-01-15T10:30:00.000Z
2026-01-15T10:31:24.512Z

The trailing Z (denoting UTC) is always present. The API never emits offsets like -03:00.

Parsing

All mainstream languages parse this format natively:

Language	Idiom
JavaScript	`new Date(response.createdAt)`
Python	`datetime.fromisoformat(response['createdAt'].replace('Z', '+00:00'))` (3.10+)
Go	`time.Parse(time.RFC3339Nano, response.CreatedAt)`
Java	`OffsetDateTime.parse(response.getCreatedAt())`
Rust	`chrono::DateTime::parse_from_rfc3339(&response.created_at)`

Display

Format with the user’s locale on the client side:

new Intl.DateTimeFormat('pt-BR', { dateStyle: 'long', timeStyle: 'medium', timeZone: 'America/Sao_Paulo' })
  .format(new Date(response.createdAt));
// "15 de janeiro de 2026 07:30:00"

Timestamps in requests

Most request bodies do not carry timestamps — those are server-assigned. The single exception is the signed X-Access-Timestamp header carrying the request time.

`X-Access-Timestamp`: milliseconds, not seconds

The signing protocol uses Unix epoch milliseconds, not seconds. A 2026-era timestamp is 13 digits, not 10:

1736553600123     ✓ milliseconds (correct)
1736553600        ✗ seconds (wrong — returns TIMESTAMP_INVALID)

Clock-skew tolerance: ±10 seconds

The Access Protocol rejects any request whose X-Access-Timestamp is more than ±10 seconds from server time. This is tighter than typical cloud SDKs (which allow minutes), and it is non-negotiable.

Run NTP on every host that signs requests. Hosts without time synchronization will see intermittent TIMESTAMP_SKEW_EXCEEDED (HTTP 401) errors that look random to your application logs.

Why so strict?

Tight clock-skew tolerance reduces the window in which a captured request can be replayed. Combined with the 1-hour deduplication of X-Access-Request-Id, the protocol is robust against replay attacks without requiring nonce challenges or session tokens.

Common failure modes

Symptom	Cause	Fix
`TIMESTAMP_INVALID` (HTTP 400)	Sent seconds instead of milliseconds.	Multiply by 1000.
`TIMESTAMP_SKEW_EXCEEDED` (HTTP 401)	Host clock drifted.	Enable `chronyd` / `ntpd`; verify with `chronyc tracking`.
Random intermittent `TIMESTAMP_SKEW_EXCEEDED`	NTP refresh interval too long, or virtualized hosts with paused clocks.	Force a re-sync (`chronyc makestep`); check VM clock-drift settings.
`TIMESTAMP_SKEW_EXCEEDED` only at deploy	Generating the timestamp at code-build time, not request-send time.	Read the clock once per request, immediately before signing.

Server time as a fallback

If you cannot run NTP (e.g., shared CI runners), you can approximate by reading server time once and computing an offset. The server time is conveyed in the Date response header on every response — including error responses — so you can extract it from a previous call.

const serverDate = new Date(response.headers.get('Date')); // RFC 7231 HTTP-date format
const offsetMs = serverDate.getTime() - Date.now();
// Use offsetMs as a correction term for subsequent requests

This is a last-resort fallback, not a substitute for proper NTP.

Time zones

The API contract has no notion of time zones. Every absolute moment is UTC. Convert at the edges:

Server → User: UTC timestamp → user’s local time on the client.
User → Server: parse user input in their local timezone → UTC ISO 8601 → send.

For filtering by date ranges, convert your user’s date selection to UTC before constructing the filter expression:

const startOfDay = new Date('2026-01-15T00:00:00-03:00').toISOString();
// "2026-01-15T03:00:00.000Z"

const filter = `createdAt>=${startOfDay}`;

Sign a request

Where X-Access-Timestamp fits in the canonical request.

Filtering

How to filter list endpoints by date ranges.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Date & time

Timestamps in responses

Parsing

Display

Timestamps in requests

`X-Access-Timestamp`: milliseconds, not seconds

Clock-skew tolerance: ±10 seconds

Why so strict?

Common failure modes

Server time as a fallback

Time zones

Next

Sign a request

Filtering

​Timestamps in responses

​Parsing

​Display

​Timestamps in requests

​X-Access-Timestamp: milliseconds, not seconds

​Clock-skew tolerance: ±10 seconds

​Why so strict?

​Common failure modes

​Server time as a fallback

​Time zones

​Next

Sign a request

Filtering

Timestamps in responses

Parsing

Display

Timestamps in requests

`X-Access-Timestamp`: milliseconds, not seconds

Clock-skew tolerance: ±10 seconds

Why so strict?

Common failure modes

Server time as a fallback

Time zones

Next