FX-as-a-service

# Also requires an `X-Request-Signature` header — compute it via one of the
# language helpers in /v3/authentication. Shell signing is impractical; this
# cURL shape is here to show the request body, not as a copy-paste sample.
curl -X POST https://api.openfx.com/v3/fx/quotes \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "buyCurrency": "EUR",
    "sellCurrency": "GBP",
    "sellAmount": "1000.00",
    "quoteForSeconds": 15
  }'

// Generate the key when the user clicks "confirm" and stash it.
// On any retry of this same logical execution, reuse it.
const tradeKey = randomUUID();

// `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.
async function executeConfirmed(quoteId, tradeKey, signRequest) {
  const url = "https://api.openfx.com/v3/fx/trades";
  const body = JSON.stringify({ quoteId: quoteId });
  const signed = signRequest({ method: "POST", url, body });
  return fetch(url, {
    method: "POST",
    headers: { ...signed.headers, "Idempotency-Key": tradeKey },
    body: signed.body,
  }).then((r) => r.json());
}

# $LAST_SEEN_CURSOR is the opaque pagination.prevCursor from your previous run.
# Pass it verbatim — do not decode it.
# Also requires an `X-Request-Signature` header — see /v3/authentication.
curl "https://api.openfx.com/v3/fx/trades?limit=100&endingBefore=$LAST_SEEN_CURSOR" \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE"

// `signRequest({ method, url, body })` returns { headers, body } with a freshly minted JWT
// AND a freshly computed X-Request-Signature each call; see Rate limiting → Handling rate limits pattern.
async function* allTrades(signRequest) {
  let cursor = null;
  while (true) {
    const url = new URL("https://api.openfx.com/v3/fx/trades");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("startingAfter", cursor);
    const signed = signRequest({
      method: "GET",
      url: url.toString(),
    });
    const page = await fetch(url, { headers: signed.headers }).then((r) =>
      r.json(),
    );
    for (const trade of page.data) yield trade;
    if (page.pagination.nextCursor === null) return;
    cursor = page.pagination.nextCursor; // opaque token, round-trip verbatim
  }
}

import { randomUUID } from "node:crypto";

// POST /api/conversions/quote
// Body shape: { buyCurrency, sellCurrency, side: 'buy' | 'sell', amount }
// where `side` tells us which leg the user is anchoring (buyAmount vs sellAmount).
async function quoteForUser(req, res) {
  const { buyCurrency, sellCurrency, side, amount } = req.body;
  const url = "https://api.openfx.com/v3/fx/quotes";
  const body = JSON.stringify({
    buyCurrency: buyCurrency,
    sellCurrency: sellCurrency,
    // oneOf{buyAmount, sellAmount} — exactly one
    ...(side === "buy" ? { buyAmount: amount } : { sellAmount: amount }),
    quoteForSeconds: 15,
  });
  const signed = signRequest({ method: "POST", url, body });
  const { data: quote } = await fetch(url, {
    method: "POST",
    headers: { ...signed.headers, "Idempotency-Key": randomUUID() },
    body: signed.body,
  }).then((r) => r.json());

  // Persist {quoteId, user_id, displayed_rate, expiresAt} for audit.
  await db.quotes.create({ ...quote, user_id: req.user.id });
  res.json(quote);
}

// POST /api/conversions/execute
async function executeForUser(req, res) {
  const { quoteId, client_request_id } = req.body;

  // Reuse the same key if the client retries this execution.
  const tradeKey = await db.executions.upsertKey(client_request_id);

  const url = "https://api.openfx.com/v3/fx/trades";
  const body = JSON.stringify({ quoteId });
  const signed = signRequest({ method: "POST", url, body });
  const { data: trade } = await fetch(url, {
    method: "POST",
    headers: { ...signed.headers, "Idempotency-Key": tradeKey },
    body: signed.body,
  }).then((r) => r.json());

  await db.trades.create({ ...trade, user_id: req.user.id });
  res.json(trade);
}