> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs-v3.openfx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox guide

> Test v1 API integrations against an isolated sandbox environment with simulated funds.

<Warning>
  **v1 sunsets December 31, 2026.** Migrate to v2 — see the [migration guide](/v1/migration-v1-to-v2).
</Warning>

The OpenFX Sandbox environment lets you test API integrations without affecting production data or real funds. This guide covers what you need to get started.

## Overview

Sandbox is an isolated testing environment that mirrors production functionality. Use it to:

* Test API integrations before going live
* Validate trading workflows
* Test deposit and withdrawal flows with simulated funds
* Experiment with different trading scenarios

## Getting started

### Obtain sandbox credentials

Contact your admin to create new Sandbox API credentials from the dashboard by switching to the Sandbox environment.

### Authentication

Sandbox uses the same authentication mechanism as production for both API keys and webhooks, with two small differences.

#### API requests

* Sandbox API keys are prefixed with `sandbox_`.
* All requests must include the `x-app-mode: SANDBOX` header.

```http theme={null}
x-app-mode: SANDBOX
```

#### Webhook signing keys

Sandbox webhook signing keys are prefixed with `sandbox_` to distinguish them from production keys. This helps prevent accidentally mixing production and Sandbox webhook handlers.

## Rate limits

Sandbox has the same rate limits as production — **30 requests per second** across all combined endpoints — so your integration behaves the same way when you go live.

## Best practices

<Tip>
  1. **Use separate credentials** — Never mix production and Sandbox credentials in your code.
  2. **Environment variables** — Store credentials in environment variables, not in code.
  3. **Test edge cases** — Use Sandbox to test error handling and edge cases.
  4. **Webhook testing** — Verify your webhook handlers process all event types correctly.
  5. **Pre-launch checklist** — Complete end-to-end testing in Sandbox before going live.
</Tip>

## Differences from production

| Aspect              | Production        | Sandbox                   |
| ------------------- | ----------------- | ------------------------- |
| Real funds          | Yes               | No (simulated)            |
| API key prefix      | None              | `sandbox_`                |
| Webhook signing key | Standard          | `sandbox_` prefix         |
| `x-app-mode` header | `LIVE` or omitted | `SANDBOX` (required)      |
| Base URL            | `api.openfx.com`  | `api.openfx.com`          |
| Data persistence    | Permanent         | May be reset periodically |

## Troubleshooting

**`401 Unauthorized`**

* Verify you are using Sandbox credentials (prefixed with `sandbox_`).
* Confirm the `x-app-mode: SANDBOX` header is included.
* Check that the API key is correctly formatted in the header.

**`404 Not Found`**

* Verify the organization ID in the request path.
* Ensure the endpoint path is correct.

## Moving to production

When you are ready to go live:

<Steps>
  <Step title="Request production credentials">
    Request production API credentials from your admin.
  </Step>

  <Step title="Swap credentials">
    Replace Sandbox credentials with production credentials (remove the `sandbox_` prefix).
  </Step>

  <Step title="Update the app-mode header">
    Remove or update the `x-app-mode` header (use `LIVE` or omit entirely).
  </Step>

  <Step title="Update webhook verification">
    Update webhook signing-key verification to use the production key.
  </Step>

  <Step title="Validate with small transactions">
    Perform final validation with small test transactions.
  </Step>
</Steps>