Idempotency

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

import { randomUUID } from "node:crypto";

// `signRequest({ method, url, body })` returns { headers, body } with a freshly minted JWT
// AND a freshly computed X-Request-Signature each call. See the Authentication guide.
// See Rate limiting → Handling rate limits pattern (the canonical reference):
// https://docs.openfx.com/v3/rate-limiting#handling-rate-limits-pattern
//
// Two distinct lifetimes inside this function:
//   - Idempotency-Key: minted ONCE per logical operation; reused on every retry of that operation.
//   - JWT + signature: minted ONCE per HTTP attempt; never reused. JWT TTL is 60s and the X-Request-Signature is bound to the JWT's nonce, so both rotate together.
async function executeTradeWithRetry(quoteId, signRequest, maxAttempts = 3) {
  const idempotencyKey = randomUUID();
  const url = "https://api.openfx.com/v3/fx/trades";
  const body = JSON.stringify({ quoteId: quoteId });

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const signed = signRequest({ method: "POST", url, body });
    const res = await fetch(url, {
      method: "POST",
      headers: {
        ...signed.headers,
        "Idempotency-Key": idempotencyKey, // stable across attempts
      },
      body: signed.body,
    });

    if (res.ok) return res.json();

    const { error } = await res.json();

    // 409: the original is still PROCESSING. Wait and retry the same key.
    // Retry-After is seconds to wait, not an epoch timestamp.
    if (error.code === "IDEMPOTENCY_IN_FLIGHT") {
      const retryAfterHeader = res.headers.get("retry-after");
      const retryAfter =
        retryAfterHeader === null ? NaN : Number(retryAfterHeader);
      const waitMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 5000;
      await new Promise((r) => setTimeout(r, waitMs));
      continue;
    }

    throw error; // Anything else is terminal for this attempt loop
  }

  // Every attempt was IDEMPOTENCY_IN_FLIGHT.
  // Surface that to the caller instead of returning undefined.
  throw new Error("Retry budget exhausted");
}

import json
import uuid
import requests

# `sign_request(method, url, body)` returns (headers, body_bytes) with a freshly minted JWT
# AND a freshly computed X-Request-Signature each call. See Authentication.
# `db` is your app's persistence layer

def execute_trade(quoteId, db, sign_request):
    # Save key FIRST, in case we crash before the API call returns
    idempotency_key = str(uuid.uuid4())
    db.save_pending_trade(quoteId=quoteId, idempotency_key=idempotency_key)

    url = 'https://api.openfx.com/v3/fx/trades'
    # Serialize once: the same bytes are signed and sent.
    body = json.dumps({'quoteId': quoteId}).encode('utf-8')
    headers, body_bytes = sign_request('POST', url, body)

    try:
        resp = requests.post(
            url,
            headers={**headers, 'Idempotency-Key': idempotency_key},
            data=body_bytes,
            timeout=30,
        )
        resp.raise_for_status()
        db.mark_completed(idempotency_key, resp.json())
        return resp.json()
    except requests.RequestException:
        # On restart, recovery loop will retry with the saved idempotency_key
        raise

CREATE TABLE idempotent_writes (
  key            TEXT PRIMARY KEY,         -- the Idempotency-Key sent to OpenFX
  endpoint       TEXT NOT NULL,            -- e.g. "POST /v3/fx/trades"
  request_body   JSONB NOT NULL,           -- exact body for replay
  status         TEXT NOT NULL,            -- "PENDING" | "SUCCEEDED" | "FAILED"
  resource_id    TEXT,                     -- populated on success (readable, typed-prefix ID, e.g. tde_5W7guYdHT24JFnRQrZN9y8)
  response_body  JSONB,                    -- cached for audit
  http_status    INTEGER,                  -- 2xx / 4xx / 5xx received
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  completed_at   TIMESTAMPTZ
);

-- Partial index keeps the recovery sweep O(PENDING rows) regardless of history.
CREATE INDEX idx_idem_pending ON idempotent_writes (created_at)
  WHERE status = 'PENDING';

// `signRequest({ method, url, body })` returns { headers, body } with a freshly minted JWT
// AND a freshly computed X-Request-Signature each call. See Authentication.
async function recoverPendingWrites(signRequest) {
  const stale = await db.idempotent_writes.findAll({
    where: { status: "PENDING", created_at: { lt: minutesAgo(2) } },
  });

  for (const row of stale) {
    const [method, path] = row.endpoint.split(" ");

    // Server TTLs: quotes and reverse-quotes 30min; trades, settle, and reverse 24h; withdrawals 7 days.
    // If we're past the window, alert and skip: replaying would create a NEW op.
    if (isPastTtl(path, row.created_at)) {
      await alert(`stale idempotent row past TTL: ${row.key}`);
      continue;
    }
    // isPastTtl: returns true when (now - createdAt) >= the endpoint's server TTL minus a safety margin.
    // function isPastTtl(path: string, createdAt: Date): boolean {
    //   const ttlMs =
    //     path.endsWith('/quotes') || path.endsWith('/reverse-quote') ? 25 * 60 * 1000 // 25min (server 30min)
    //   : path.endsWith('/trades') || path.endsWith('/settle') || path.endsWith('/reverse')
    //                                   ? 20 * 60 * 60 * 1000      // 20h    (server 24h)
    //   : path.endsWith('/withdrawals') ? 6 * 24 * 60 * 60 * 1000  // 6d     (server 7d)
    //   :                                 24 * 60 * 60 * 1000;
    //   return Date.now() - createdAt.getTime() >= ttlMs;
    // }

    const url = `https://api.openfx.com${path}`;
    const requestBody = JSON.stringify(row.request_body);
    // Re-sign on every replay: the JWT nonce is single-use and the signature is bound to it.
    const signed = signRequest({ method, url, body: requestBody });
    const res = await fetch(url, {
      method,
      headers: {
        ...signed.headers,
        "Idempotency-Key": row.key, // ← critical: same key
      },
      body: signed.body,
    });
    const body = await res.json();

    await db.idempotent_writes.update(row.key, {
      status: res.ok ? "SUCCEEDED" : "FAILED",
      resource_id: res.ok ? body.data.id : null,
      response_body: body,
      http_status: res.status,
      completed_at: new Date(),
    });
  }
}

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Trace-Id: 4bf92f3577b34da6a3ce929d0e0e4736
Content-Type: application/json

{ ... cached response body ... }

import { randomUUID } from "node:crypto";
// `signRequest({ method, url, body })` returns { headers, body } with a freshly minted JWT
// AND a freshly computed X-Request-Signature per call. `db` is your persistence layer.
// JWT TTL is 60s; this flow can run for minutes (poll loop) so the JWT + signature are minted
// per HTTP attempt, never captured once. See Rate limiting → Handling rate limits pattern:
// https://docs.openfx.com/v3/rate-limiting#handling-rate-limits-pattern

async function withdraw({
  withdrawalAccountId,
  amount,
  currency,
  signRequest,
}) {
  // 1. Save key first (same crash-safety reasoning as the recovery pattern above).
  const idempotencyKey = randomUUID();
  await db.savePendingWithdrawal({
    idempotencyKey,
    withdrawalAccountId,
    amount,
    currency,
  });

  // 2. Create. Verify the POST succeeded before polling, otherwise
  // withdrawal.id is undefined and the loop below silently misbehaves.
  const createUrl = "https://api.openfx.com/v3/fx/withdrawals";
  const createBodyBytes = JSON.stringify({
    withdrawalAccountId: withdrawalAccountId,
    withdrawalAmount: amount,
    currency,
  });
  const createSigned = signRequest({
    method: "POST",
    url: createUrl,
    body: createBodyBytes,
  });
  const createRes = await fetch(createUrl, {
    method: "POST",
    headers: { ...createSigned.headers, "Idempotency-Key": idempotencyKey },
    body: createSigned.body,
  });
  const createBody = await createRes.json();
  if (!createRes.ok) {
    // Leave the row in `PENDING` so the recovery worker can retry with the same key.
    const err = createBody.error;
    throw new Error(
      `API error: ${err.code} — ${err.message} (trace ${createRes.headers.get("x-trace-id")})`,
    );
  }
  // Both POST and GET wrap the resource in { data: ... }; unwrap it.
  let withdrawal = createBody.data;

  await db.markCreated(idempotencyKey, withdrawal.id);

  // 3. Poll until terminal. Mint per tick: even a 5s cadence exceeds the 60s JWT TTL
  // by the 13th iteration, and most withdrawals settle well after that.
  while (withdrawal.status === "PENDING") {
    await new Promise((r) => setTimeout(r, 5000));
    const pollUrl = `https://api.openfx.com/v3/fx/withdrawals/${withdrawal.id}`;
    const pollSigned = signRequest({ method: "GET", url: pollUrl });
    const pollBody = await fetch(pollUrl, { headers: pollSigned.headers }).then(
      (r) => r.json(),
    );
    withdrawal = pollBody.data;
  }

  return withdrawal; // terminal: COMPLETED | CANCELLED
}