Authentication

Two credentials, two questions

Player-scoped endpoints carry both an HMAC signature and a session token, and the two are not redundant. The signature and the IP allowlist answer where this call came from; the session answers which player it is for. Dropping either one collapses a property you want: with only a session, a leaked token could be spent from any address on the internet; with only a signature, the player id would be back to travelling as a parameter that anything in your stack could set.

It also decides how much an error is allowed to tell you, and that turns out to be the practical benefit. Signature failures stay deliberately indistinguishable — a wrong key, a skewed clock and a replayed nonce all answer the same bare 401, because anything finer would let a stranger probe. A session failure is answered after the signature verified, so by then the caller has already proved it holds your secret and calls from your address: it is you, and there is nothing left to leak by being specific. That is why session_required and session_invalid exist as separate, explicit codes while the HMAC layer has exactly one.

Headers

There is no X-Player-Id row, and its absence is enforced rather than documented: the header is refused on the whole of /b2b/v1, including the merchant-dimension endpoints that never used it. That breadth is on purpose — it was a written part of this contract, so “we removed every send” has to be checkable in one place rather than argued endpoint by endpoint.

Taking a session

This is the one call where you name a player, and it is the only one. It is signed like any other B2B request and carries no session of its own — it is the call that gets you one.

POST /b2b/v1/auth/session
X-Api-Key:    ak_9dc9a497...
X-Timestamp:  1767225600
X-Nonce:      b6f3c2e1-4a5d-4c9e-9f10-2b8a7d6e5c40
X-Signature:  <hex HMAC-SHA256 over the six-field canonical>
Content-Type: application/json

{"player_id":"player-1001"}

# Content-Type: application/json is not optional here. Without it the body is
# not bound at all and the call answers 400 bad_request with an empty player_id.

{
  "session_token": "0Xy1mQ8pR2vK7hN4tS6wZ3bJ5cF9dG1aL8eU0iO2yT4",
  "expires_in": 1800,
  "absolute_expires_at": "2026-08-18T12:00:00Z",
  "player_id": "player-1001",
  "currency": "EUR"
}

Keeping it alive

Ordinary calls slide the idle window on their own, so a busy session needs nothing. What POST /b2b/v1/auth/refresh adds is a way to slide it without making a business call, and to read back what the operator currently believes about the session. It takes HMAC and the Bearer, like any other player-scoped endpoint, and echoes the player_id the session resolves to — the value to assert against your own record if you want to catch a mis-wired session early.

There is no logout. To end a session, take a new one for that player — the previous one dies in the same call. Sessions also end on their own when a player is frozen, which is what makes freezing take effect rather than waiting out the window.

Taking a session creates the player

There is no endpoint that registers a player. The first session taken for a given player_id creates that player under your merchant, and every session after it resolves to the same record. An id the operator has never seen is therefore not an error — so a typo, a changed id format, or a staging id leaking into production does not fail loudly. It quietly opens a second account with no positions and no history, and the player you meant is still sitting where you left it. Treat the id the way you would a primary key: derive it once, never reformat it.

Creation is also where the player's ledger currency is decided, and it is decided once. It is taken from your currency_base at that moment and never revisited — the lookup only runs on the create path. Your base currency is fixed at onboarding and no endpoint changes it, so in practice this is not something you can trip over through the API; it matters because it makes the base currency a decision to get right before you onboard anyone rather than after. If currency_base cannot be read or is empty at that moment, the call refuses with 409 merchant_currency_unset and creates nothing. It used to fall back to USDT; that fallback is gone, because a guessed currency is written into the ledger permanently and cannot be corrected once the player exists.

The shape of the id is validated, and knowing exactly how much is validated is what stops you designing around the wrong risk. It must match ^[A-Za-z0-9._-]{1,64}$: letters, digits, dot, underscore and hyphen, at most 64 characters. Anything outside that — a space, an accent, an @, an id longer than the column — is refused with 400 invalid_player_id before anything is created, so it fails loudly and a corrected retry works.

What is not checked is whether two ids you consider different mean different players. The uniqueness check is case-insensitive, so Player1 and player1 are the same account, while player_1 is a different one. That is the part that bites: inside the permitted character set, the same class of typo sometimes merges and sometimes forks, and neither outcome returns an error. Derive the id once, from a source you control, and never reformat it downstream.

One more id-shaped failure is distinct from all of these and does return an error: a frozen player answers player_forbidden (403), at the moment you take the session and again on any call made with a session they held when they were frozen.

The canonical string

Join six fields with a single \n — six fields and five separators, not six newlines. PATH is the path only (no query string). RAWQUERY is the query string exactly as sent, without the leading ? (empty string if none). X-Nonce is the value of that header. BODY is the raw request body, or an empty string for GET — signed raw, never hashed.

1. X-Timestampunix seconds, ±300s of server time
   \\n
2. METHODuppercase — POST, GET
   \\n
3. PATHpath only, no query string — the decoded path
   \\n
4. RAWQUERYexactly as sent, no leading ? — "" if none
   \\n
5. X-Nonceunique per request, per API key
   \\n
6. BODYraw bytes as sent — "" for GET, and then the string ends with the newline above

   BODY ends the string — nothing is appended after it

canonical = X-Timestamp + "\n" +
            METHOD      + "\n" +   // uppercase, e.g. POST
            PATH        + "\n" +   // e.g. /b2b/v1/orders  (no query)
            RAWQUERY    + "\n" +   // e.g. status=all  (no leading "?", "" if none)
            X-Nonce     + "\n" +   // unique per request
            BODY                    // raw JSON, or "" for GET

// The Authorization header is NOT here. A session token is presented, not signed:
// it never enters the canonical, so holding one session across many requests and
// re-signing each request are independent of each other.

PATH and RAWQUERY point in opposite directions on purpose, and getting either wrong fails as a 401 — indistinguishable from a bad key, so the afternoon goes into checking credentials that were fine. Rebuilding the query from a parameter map, sorting its keys or re-encoding it all produce a string that differs from the one on the wire.

Two empty things carry weight, and both are worth reading twice because they are the most common reason a correct implementation still fails. An empty RAWQUERY still occupies its line — skipping the line instead of joining an empty value produces a string one newline shorter, and a signature that verifies against nothing. And an empty BODY leaves the canonical ending in a newline, because BODY is last: printf, command substitution and here-strings all strip or add trailing newlines, so a signer that routes the canonical through a shell signs a different string than the one it printed.

Signing — Node.js

import crypto from "node:crypto";

function signB2B({ apiKey, secret, method, path, rawQuery = "", body = "", sessionToken }) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomBytes(16).toString("hex"); // fresh, single-use per request
  // Order is exact, and there are SIX fields: ts, METHOD, PATH, RAWQUERY, X-Nonce, BODY
  const canonical = [ts, method.toUpperCase(), path, rawQuery, nonce, body].join("\n");
  const sig = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
  return {
    "X-Api-Key": apiKey,
    "X-Timestamp": ts,
    "X-Nonce": nonce,
    "X-Signature": sig,
    // Presented, not signed — it is not part of the canonical above.
    ...(sessionToken ? { Authorization: `Bearer ${sessionToken}` } : {}),
    "Content-Type": "application/json",
  };
}

// 1. Take a session. Signed, no Bearer — this is the call that produces one.
const takeBody = JSON.stringify({ player_id: "player-1001" });
const takeRes = await fetch(`${base}/b2b/v1/auth/session`, {
  method: "POST", body: takeBody,
  headers: signB2B({ apiKey, secret, method: "POST", path: "/b2b/v1/auth/session", body: takeBody }),
});
const { session_token, absolute_expires_at } = await takeRes.json();

// 2. Every player-scoped call: signed AND bearing the session.
//    GET with a query — sign RAWQUERY exactly as sent (no leading "?").
//    status on /orders is the integer state (1..4) — a name like "all" is a 400.
const h = signB2B({ apiKey, secret, method: "GET",
  path: "/b2b/v1/orders", rawQuery: "status=2&limit=20", sessionToken: session_token });

//    POST — sign the exact bytes you send
const body = JSON.stringify({ market_id: "mkt_1", side: 1, shares: "10", idem_key: "..." });
const h2 = signB2B({ apiKey, secret, method: "POST",
  path: "/b2b/v1/orders", body, sessionToken: session_token });

// 3. Re-take on 401 session_invalid, and before absolute_expires_at. Cache the token
//    per player, never per process — one process usually serves many players.

Note what step 3 is not: it is not a retry loop around a bare 401. Distinguish the two codes before you re-take, because they mean opposite things about your credentials. A 401 unauthorized means the signature layer refused and a new session will not help; a 401 session_invalid means the signature was fine and a new session is exactly the fix. Re-taking on the first one turns a signing bug into a loop that mints sessions and gets nowhere.