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.

Programmatic clock-skew check: `GET /time`

If you cannot run NTP (e.g., shared CI runners), the preferred programmatic check is the unauthenticated GET /time endpoint, which returns the server’s current time. Because it requires no signature, you can call it even when every signed request is failing with TIMESTAMP_SKEW_EXCEEDED:

Record your local clock immediately before and after calling GET /time.
Compute the offset: offsetMs = serverTime - localMidpoint (the midpoint of the two local readings compensates for network latency).
Apply the offset when signing: generate X-Access-Timestamp as Date.now() + offsetMs.
Re-measure periodically — local clocks drift.

See the endpoint reference for the exact response shape. As a fallback when calling GET /time is not convenient, the server time is also conveyed in the Date response header on every response — including error responses — at whole-second precision:

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

Both techniques are correction terms for hosts you cannot synchronize — proper NTP remains the primary recommendation for infrastructure you control.

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

Webhooks

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

Programmatic clock-skew check: `GET /time`

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

​Programmatic clock-skew check: GET /time

​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

Programmatic clock-skew check: `GET /time`

Time zones

Next