Withdrawal lifecycle

​

Status

​

Where money goes

• Fiat withdrawals. See Settlement times for the submission cut-off per currency and rail. Submissions after a cut-off are processed the next banking day.
• Stablecoin withdrawals. See Supported networks for the per-stablecoin chain matrix. Once broadcast, transactionHash on the withdrawal identifies the on-chain transaction.

​

Polling pattern with adaptive backoff

// `signRequest({ method, url, body })` mints a fresh JWT AND a fresh X-Request-Signature
// per call. JWT TTL is 60s; the schedule below reaches 5min ticks and ~25 min total wall-clock,
// so a captured JWT/signature would expire mid-loop. See Rate limiting → Handling rate limits pattern:
// https://docs.openfx.com/v3/rate-limiting#handling-rate-limits-pattern
async function waitForWithdrawal(withdrawalId, signRequest) {
  // Start at 5s; double up to 5min cap. Total wait ~25 min before giving up.
  const delays = [
    5_000, 10_000, 20_000, 40_000, 80_000, 160_000, 300_000, 300_000, 300_000,
  ];
  const url = `https://api.openfx.com/v3/fx/withdrawals/${withdrawalId}`;
  for (const delay of delays) {
    // Mint per tick: even the first interval (5s) is fine, but by the second iteration
    // we are well past the 60s JWT TTL — and the signature is bound to the JWT's nonce.
    const signed = signRequest({ method: "GET", url });
    const res = await fetch(url, { headers: signed.headers });
    const w = await res.json();
    if (w.data?.status === "COMPLETED") return w;
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error(
    "Withdrawal not COMPLETED after backoff exhausted; consider webhook delivery.",
  );
}

​

When a withdrawal is stuck

​

Step 1 — read the trace ID

​

Step 2 — re-fetch the resource

# Also requires an `X-Request-Signature` header — see /v3/authentication.
curl https://api.openfx.com/v3/fx/withdrawals/<uuid> \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE"

​

Step 3 — match the state against the rail clock

• Fiat USD via Fedwire: submissions after 4:30 PM ET batch the next business day.
• Fiat EUR via SEPA: submissions after 12:30 PM London time batch the next business day.
• Stablecoin on Ethereum: network congestion can delay confirmation 10+ minutes.

​

Step 4 — check for background blockers

​

Step 5 — check the error catalog for synchronous failures

• Validation codes (WITHDRAWAL_INVALID_*, WITHDRAWAL_ADDRESS_*): fix root cause, retry with new Idempotency-Key. The original key + original body would replay the same failure.
• State codes (WITHDRAWAL_INSUFFICIENT_BALANCE, WITHDRAWAL_PENDING_DEPOSIT_REQUIRED): clear the blocking state, retry with new key.
• Write-path 500s (WITHDRAWAL_INITIATION_FAILED): indeterminate — GET /v3/fx/withdrawals/{id} first to confirm whether the withdrawal was actually created before retrying with the same key. See Idempotency → Crash recovery.
• INTERNAL_ERROR (500): follow its cataloged retry strategy and include the response X-Trace-Id if you contact support.

​

Step 6 — file a support ticket

• The X-Trace-Id from the original POST
• The id (readable, wtd_-prefixed) of the stuck withdrawal
• Current status
• The Idempotency-Key used
• Timestamps: createdAt from the resource and your client-side request time

​

Don’t do this

• Replay a rejected withdrawal with the same Idempotency-Key. The cached response is the rejection. Use a fresh key after fixing the root cause.
• Poll faster than every 5s. It won’t make a SWIFT wire arrive sooner; it will trip RATE_LIMIT_EXCEEDED.
• Assume unsettled means stuck. Settlement times defines the windows; treat unsettled past the window as the alert threshold, not unsettled itself.

​

Common mistakes

• Fixed-interval polling at 5s. Fine for the first minute; wasteful for a fiat withdrawal that spans banking hours.
• Polling without an upper bound. Always have a “give up and alert” condition.

​

What’s next