Conventions

The response envelope

Every successful response is wrapped in the same three fields. Your payload is always under data:

{
  "success": true,
  "data": { "…the endpoint's documented object…": "…" },
  "timestamp": "2026-09-02T10:15:28.114Z"
}

There is no code and no request id at this layer. Pagination lives inside data, not beside it.

Errors are shaped differently: flat, with a statusCode and a code. They are documented in full on Errors. Branch on the HTTP status first, then on code. Never on message.

Idempotency

Every route that moves money or creates a resource requires an idempotency key that you choose. There is no server-minted fallback. A request without a key is refused rather than executed.

Sending the key

Put it in the Idempotency-Key header:

Idempotency-Key: acme-deposit-2026-09-02-0001

Routes that take a JSON body also accept it as an idempotencyKey body field. Sending both is allowed only when they are identical. A disagreement is refused.

Which routes require one

Three routes take no body: POST /accounts/{id}/iban, POST /accounts/{id}/close and POST /sub-clients/{id}/close. They accept the key only as the header.

What happens on a repeat

The comparison is a fingerprint of the parameters, and it is exact:

• "100" and "100.00" are different requests.
• The same body with a different x-on-behalf-of is a different request. The header is part of the fingerprint.
• Naming a subAccountId and omitting it are different requests.

How long a key is remembered

On the five money routes a key is spent forever, so plan a key scheme that never needs to reuse one. On the resource routes, do not rely on a key to deduplicate something you might resend a week later. Make your own externalRef the identity instead.

Rate limits

Requests are counted per principal, not per key. Rotating a key or holding several does not raise your ceiling.

The limit is configured per client. Ask partners@threecomma.group if you need more. Back off to the start of the next minute and resend with the same idempotency key.

If rate limiting itself is unavailable, requests are refused with a 503 rather than let through unmetered. Nothing was attempted. Retry.

Versioning

The version is the /partner/v1 path segment. Within v1, changes are additive only:

• New endpoints.
• New optional request fields.
• New response fields.

A breaking change gets a new path segment. It is never a silent change to an existing one. Build your client to ignore unknown response fields rather than fail on them, and an additive release will not require a change.

While the API is a testnet pilot this rule has had two recorded exceptions, both response fields removed from GET /positions; each is listed under Removed in the changelog.

The machine-readable specification is updated together with every change to the API surface, so it always describes the current contract.

Amounts and scales

Every amount crossing this API is a decimal string: in a request, in a response, and inside an error's details.

{ "amount": "1000.00", "settledShares": "1024.518330000000000000000000" }

Never a JSON number, never base units, never exponential notation. A JSON number cannot represent every decimal amount exactly.

One exception: the share figures on a statement (shares, openingShares, closingShares, runningShares) are exact integers in the share token's base units. They are still strings.

There is no decimals field anywhere in this API. Read the string, parse it with a decimal library, and do not infer a scale from the digits a value happens to carry.

Amounts come back normalised rather than echoed: a submitted "1000.00" is returned as "1000". Compare amounts numerically, never by string equality.

Pagination

Three list endpoints paginate, with an opaque forward cursor:

The page sits inside data:

{
  "success": true,
  "data": {
    "items": [ { "…": "…" } ],
    "nextCursor": "f39b0c74-51ae-4d82-9b06-3c7e2a5d1f80"
  },
  "timestamp": "2026-09-02T10:15:28.114Z"
}

nextCursor is null on the last page. Stop on that, not on an empty items array. Treat the cursor as opaque: do not parse it, construct one, or persist it across runs.

GET /sub-accounts and GET /webhooks are not paginated. They return every row, oldest first.

Timestamps

Every timestamp is an ISO 8601 string in UTC with milliseconds:

2026-09-02T10:15:28.114Z

That applies to the envelope's timestamp, every createdAt / settledAt / occurredAt on a response, and the from and to filters on GET /transfers. A field documented as nullable that reads null means not yet: settledAt is null until the money lands.

Pilot disclosure