Skip to main content
OpenFX runs Sandbox and Live on the same base URL (api.openfx.com). Which environment you hit is determined by the API key you authenticate with. Each key is bound to one environment server-side. A request can also carry an X-App-Mode header (SANDBOX or LIVE) matching that key’s environment. Omit it and the request defaults to SANDBOX, so a Live key must send X-App-Mode: LIVE explicitly or the request fails with 403 AUTH_API_KEY_SANDBOX_REQUIRED. Any other value returns 400 INVALID_APP_MODE. Sandbox API keys carry a sandbox_ prefix; Live keys are unprefixed, so you can tell the two apart at a glance. Sandbox and Live use the same endpoints, code paths, and rate-limit ceiling; the difference is real-vs-simulated funds and the key prefix. Code validated in Sandbox therefore follows the same API contract, traffic pattern, and rate limits in Live.

​
Sandbox vs Live

Sandbox and Live share the same rate-limit ceiling as separate buckets, so a traffic pattern validated in Sandbox carries over directly. See Rate limiting for the back-off pattern.

​
Sample request

A Sandbox call differs from a Live call by the sandbox_-prefixed key and the X-App-Mode value; everything else, including the required X-Request-Signature, is the same.
Use the interactive API reference playground with Sandbox credentials only. Never paste a Live key or Live X-App-Mode value into a browser-based tool. Use a language sample with your own request-signing code for Live calls instead.
The JWT in each case was minted with the matching environment’s API key (Sandbox keys carry a sandbox_ prefix; Live keys don’t). See Authentication for the minting flow.

​
Safety net: wrong-environment errors

If your key doesn’t match the environment you’re trying to reach, OpenFX rejects the request instead of silently doing the wrong thing: you can’t accidentally execute a Live trade with Sandbox credentials, or vice versa. Both codes return AUTHORIZATION_ERROR / 403: the request authenticated successfully, but the key isn’t valid for this environment. An X-App-Mode value other than LIVE or SANDBOX returns 400 INVALID_APP_MODE, and details.allowed lists the accepted values. Full entries live in the v3 error catalog.

​
Going live

The full pre-launch list lives in the Live checklist. The minimum cutover from a working Sandbox integration is:
1

Swap credentials

Replace the Sandbox name and privateKey in your secrets store with the Live values from the dashboard.
2

Set X-App-Mode to LIVE

Send X-App-Mode: LIVE on every request. An omitted header defaults to SANDBOX, and a Live key then returns 403 AUTH_API_KEY_SANDBOX_REQUIRED. Wire the value from the same config that selects your key.
3

Update webhook signing key

Live webhook signing secrets are prefixed whsec_ (Sandbox secrets are sandbox_whsec_…). Point your verifier at the Live signing secret.
Run end-to-end through Sandbox first. Identical endpoints, code paths, and rate limits mean what works in Sandbox works in Live, including load patterns tested against the 300 req/10s ceiling.

​
Common mistakes

  • Mixing credentials in the same process. Two key pairs (one Sandbox, one Live) stored in two distinctly-named secrets. Never read OPENFX_KEY and hope it’s the right one.
  • Assuming Sandbox data persists. Sandbox may be reset periodically; don’t seed long-running test workflows with Sandbox IDs you expect to still exist next month.
  • Hard-coding the base URL. It’s the same in both environments, but writing api.openfx.com as a literal in two places will trip you up the day OpenFX adds a regional endpoint.
  • Sending an X-App-Mode value that doesn’t match the key. The header and the key’s bound environment must agree. Wire it from the same environment-aware config that selects your key, not a hard-coded constant.

​
What’s next

Live checklist

Full pre-launch checklist: keys, IP allowlist, monitoring.

Authentication

JWT minting flow with code samples in Node, Python, Java, C++, and Go.

Errors

AUTH_* codes and recovery patterns.