> ## 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 OpenFX v2 integrations against an isolated Sandbox environment that mirrors production functionality.

The OpenFX Sandbox environment allows you to test API integrations without affecting production data or real funds. This guide covers everything you need to know 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 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.

```
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 correctly when going live. See [Rate limits](/v2/rate-limits) for details.

## Best practices

1. **Use separate credentials** — Never mix production and Sandbox credentials in your code.
2. **Environment variables** — Store credentials in environment variables, not in source.
3. **Test edge cases** — Use Sandbox to exercise 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.

## 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're 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

<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 x-app-mode header">
    Remove or update the `x-app-mode` header (use `LIVE` or omit entirely).
  </Step>

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

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