Wallet hooks

Your base URL must be publicly reachable

Before any money command is sent, the operator resolves your wallet_base_url and refuses to open the connection if the host resolves to a loopback, private, link-local or unspecified address, or to an IPv6 unique-local one in fc00::/7. Cloud metadata endpoints such as 169.254.169.254 fall under link-local and are refused with everything else. Only the address that passed the check is dialled, so a name that answers publicly once and privately the next time does not get through either. Redirects are never followed — the URL you register is the URL that is called.

It is worth knowing exactly where that refusal lands, because the two sides of it look nothing alike.

A hook pointed at a VPC-internal name, a private address, or a host reachable from your network but not from the internet produces exactly this, and it looks nothing like a configuration mistake until you know to check.

Co-located deployments where the operator and the wallet genuinely share a private network are handled by an operator-side allowlist, not by anything you can set. If that is your topology, ask the operator to allow your host rather than trying to make the URL public.

The four money hooks

They share one request shape, which makes them look interchangeable. One takes money and three give it back, and which one gives it back is the only record of why — that is what your reconciliation reads later. Implementing all four as a single balance adjustment loses the reason and cannot be recovered afterwards.

• /wallet/bet↓ debit

  A market order fills, or a limit BUY is placed.

  The only hook that takes money. A limit buy debits at placement, not at fill — resting an order costs the stake up front.

• /wallet/payout↑ credit

  A market settles in the player's favour, or a limit SELL fills.

  The winning outcome. Not the same as getting a stake back — this is proceeds.

• /wallet/cashout↑ credit

  The player closes a position early, in full or in part.

  A voluntary exit at the current price. Distinct from a payout because the market has not resolved.

• /wallet/refund↑ credit

  An order is voided, or a resting limit order is cancelled or expires.

  Money returned because the bet never stood. Route it here even if your ledger entry is identical to a payout — the distinction is what tells you later whether a player won or simply got their stake back.

Verifying the signature

The hook canonical hashes the body — this differs from the B2B canonical, which signs the raw body. Do not share a verifier between them.

Five fields, not four. Write commands carry no query string, but the empty RAWQUERY line is still there — drop it and every signature fails, writes included. It exists because GET /wallet/balance passes player_id in the query: signing it is what stops a tampered request from reading another player's balance.

import crypto from "node:crypto";

// canonical = ts + "\n" + METHOD + "\n" + path + "\n" + RAWQUERY + "\n" + sha256hex(body)
function verifyHook(req, rawBody, secret) {
  const ts = req.header("X-Wallet-Ts");
  const got = req.header("X-Wallet-Token");
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // stale
  // GET /wallet/balance has no body: hash the empty string, not undefined.
  const bodyHash = crypto.createHash("sha256").update(rawBody ?? "").digest("hex");
  // RAWQUERY is the raw query string with no leading "?" — "" on writes, which still
  // contributes an empty line. Keys arrive sorted (url.Values.Encode), so compare bytes as received.
  const rawQuery = req.url.includes("?") ? req.url.slice(req.url.indexOf("?") + 1) : "";
  const canonical = [ts, req.method.toUpperCase(), req.path, rawQuery, bodyHash].join("\n");
  const want = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
}

Common request headers

How long you have to answer

Each hook call carries a request timeout configured per merchant, defaulting to 3 seconds. Exceed it and the operator treats the call as a network failure and retries it — so a slow hook does not fail, it duplicates. That is survivable only because you dedupe on idem_key; if you do not, a hook that occasionally takes four seconds will double-charge players.

Retries apply to network errors and 5xx only, with exponential backoff, up to the retry count on your hook configuration — 3 by default. Backoff starts at 100 ms and doubles (100, 200, 400 ms…). Total attempts per command are hard-capped at 8 regardless of how the hook is configured, so one money command reaches you at most eight times within the synchronous window.

Do your slow work — ledger writes, risk checks, third-party calls — before you answer, not after, and answer the same way every time for a given idem_key.

“Not retried” and “finished” are three different questions

A status code is read at three levels, and they do not agree with each other. Reading one rule where there are three is what produces the two classic failures: treating a bounded synchronous window as the lifetime of the command, and expecting a credit to give up the way a debit does.

What your status code means to us

The operator branches on your HTTP status before it looks at your body, and the branch decides whether a money command is retried, failed cleanly, or surfaced as an internal error. Returning a plausible-but-wrong status is the difference between “player has no funds” and “something broke.”