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

# Sandbox

> Test your Iron integration against api.sandbox.iron.xyz. Covers sandbox access, differences from production, and simulating transactions.

## Sandbox Location

* **Partner Dashboard:** [https://app.sandbox.iron.xyz](https://app.sandbox.iron.xyz)
* Please reach out to request access to your sandbox environment.

## Differences to Production

The Sandbox is optimized to test and integrate the Iron APIs. Therefore, it has multiple differences compared to the production system in order to make it easy to work with.

* In production, only an administrator can create an API Key (and then give it to an engineer with an Editor role). In the sandbox, an Editor can also create API Keys to make it easy to test.
* In the sandbox, fiat and crypto flows are simulated. Neither real IBANs nor testnet crypto is used. Instead, we offer a [Sandbox API](/reference-sandbox/createsandboxfiattransaction) to create mock incoming fiat or crypto transactions.
* Any accept/reject flow can be controlled by the user. Instead of going through an email flow, there's a convenient control center where the engineer can decide whether to accept or reject customer fiat accounts, Autoramps, etc.
* The sandbox offers a Reset function to remove all data and start from a pristine state.
* The sandbox has additional `/sandbox` [APIs](/reference-sandbox/createsandboxfiattransaction) to fully control all the above features.

## Managing the Sandbox

You can manage the Sandbox in the **Sandbox** area of the [Partner Dashboard](/partner-dashboard).

<Steps>
  <Step>
    Log in to the Partner Dashboard.
  </Step>

  <Step>
    Navigate to **Developer → Sandbox**.
  </Step>
</Steps>

## Sandbox Operations

The following operations are available in the dashboard:

### Manage Pending Fiat Accounts

When a sandbox customer registers a new fiat account, it will be listed here. You can then decide whether to move it to **Registered** or fail the registration.

### Manage Pending Autoramps

When a sandbox customer creates a new Autoramp, it will be listed here. You can then decide whether to **approve** or **reject** it.

### Reset Sandbox

Resetting the sandbox will remove all customers, wallets, fiat accounts, transactions, and Autoramps.

## Sandbox API Key

<Note>
  The Sandbox APIs require an API Key just like the rest.
</Note>

You can create a sandbox API key in your dashboard: [https://app.sandbox.iron.xyz/dashboard/keys](https://app.sandbox.iron.xyz/dashboard/keys)

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.sandbox.iron.xyz/api/sandbox/reset \
    -H "X-API-Key: YOUR-API-KEY" \
    -H "IDEMPOTENCY-KEY: $(uuidgen)"
  ```
</CodeGroup>

<Note>
  Replace `YOUR-API-KEY` with the actual API key you generated. The `X-API-Key` header is required for every request. API Base URL: [https://api.sandbox.iron.xyz](https://api.sandbox.iron.xyz)
</Note>

## Sandbox API

The sandbox offers [additional APIs](/reference-sandbox/createsandboxfiattransaction) that do not exist in production. They let you create mock transactions, control approval flows, and reset your environment.

<Note>
  All paths below are relative to the API base URL: `https://api.sandbox.iron.xyz/api`
</Note>

### Create a Sandbox Transaction

`POST` `/sandbox/transaction`

Creates a transaction directly from an autoramp configuration. This bypasses the normal deposit flow and creates a ramp transaction with the specified amount using the autoramp's currencies, customer, and recipient.

| Field            | Required | Description                                                               |
| ---------------- | -------- | ------------------------------------------------------------------------- |
| `autoramp_id`    | Yes      | The autoramp UUID to create the transaction against                       |
| `amount`         | Yes      | Deposit amount in the autoramp's input currency (decimal string)          |
| `amount_out`     | No       | Output amount. If omitted, calculated from `amount`, `fee`, and `fx_rate` |
| `fee`            | No       | Fee amount (defaults to 0.25% of `amount`)                                |
| `fx_rate`        | No       | Exchange rate (defaults to `1.0`)                                         |
| `initial_state`  | No       | Starting state: `Pending`, `Completed`, or `Failed`                       |
| `input_currency` | No       | Override the input currency (Fiat or Crypto object)                       |
| `source`         | No       | Override the transaction source (bank account or wallet)                  |
| `transaction_id` | No       | Deterministic transaction UUID instead of auto-generated                  |
| `deposit_id`     | No       | Deterministic deposit UUID instead of auto-generated                      |

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.sandbox.iron.xyz/api/sandbox/transaction" \
    -H "Content-Type: application/json" \
    -H "IDEMPOTENCY-KEY: $(uuidgen)" \
    -H "X-API-Key: $API_KEY" \
    -d '{
      "autoramp_id": "d3c2b1a4-e5f6-78a9-0123-fedcba654321",
      "amount": "100"
    }'
  ```
</CodeGroup>

**Example response:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "id": "7d834f68-cea8-496a-8eae-bb0772365028",
    "autoramp_id": "d3c2b1a4-e5f6-78a9-0123-fedcba654321",
    "amount_in": "100",
    "currency_in": "EUR",
    "amount_out": "99.75",
    "currency_out": "EURC",
    "customer_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "state": "Pending",
    "created_at": "2026-01-15T10:30:00Z"
  }
  ```
</CodeGroup>

### Update Sandbox Transaction State

`PUT` `/sandbox/transaction/{id}/state`

Transition a sandbox transaction to a different state for testing purposes.

| Field   | Required | Description                                       |
| ------- | -------- | ------------------------------------------------- |
| `state` | Yes      | Target state: `Pending`, `Completed`, or `Failed` |

<CodeGroup>
  ```bash Bash theme={null}
  curl -X PUT "https://api.sandbox.iron.xyz/api/sandbox/transaction/<transaction_id>/state" \
    -H "Content-Type: application/json" \
    -H "IDEMPOTENCY-KEY: $(uuidgen)" \
    -H "X-API-Key: $API_KEY" \
    -d '{ "state": "Completed" }'
  ```
</CodeGroup>

### Update Identification Status

`POST` `/sandbox/identification/{id}`

Approve or reject a pending customer identification. In production, Iron's compliance team handles this review.

| Field      | Required | Description                          |
| ---------- | -------- | ------------------------------------ |
| `approved` | Yes      | `true` to approve, `false` to reject |

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.sandbox.iron.xyz/api/sandbox/identification/<identification_id>" \
    -H "Content-Type: application/json" \
    -H "IDEMPOTENCY-KEY: $(uuidgen)" \
    -H "X-API-Key: $API_KEY" \
    -d '{ "approved": true }'
  ```
</CodeGroup>

### Update Fiat Address Registration Status

`PUT` `/sandbox/fiat-verification/{id}`

Set the registration status of a fiat address. The request body is a plain JSON string (one of the enum values below).

| Status                  | Description                             |
| ----------------------- | --------------------------------------- |
| `RegistrationPending`   | Registration is being processed         |
| `Registered`            | Account is active and ready for payouts |
| `RegistrationFailed`    | Registration failed                     |
| `AuthorizationRequired` | Additional authorization needed         |
| `AuthorizationFailed`   | Authorization was rejected              |

<CodeGroup>
  ```bash Bash theme={null}
  curl -X PUT "https://api.sandbox.iron.xyz/api/sandbox/fiat-verification/<fiat_address_id>" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $API_KEY" \
    -d '"Registered"'
  ```
</CodeGroup>

### Update Autoramp Status

`PUT` `/sandbox/autoramp/{id}`

Set the status of an autoramp. The request body is a plain JSON string (one of the enum values below).

| Status                | Description                                      |
| --------------------- | ------------------------------------------------ |
| `Created`             | Initial state                                    |
| `EditPending`         | Edit is being processed                          |
| `Authorized`          | Authorized by the system                         |
| `DepositAccountAdded` | Deposit account has been provisioned             |
| `Approved`            | Fully approved and ready to process transactions |
| `Rejected`            | Rejected                                         |
| `Cancelled`           | Cancelled                                        |

<CodeGroup>
  ```bash Bash theme={null}
  curl -X PUT "https://api.sandbox.iron.xyz/api/sandbox/autoramp/<autoramp_id>" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $API_KEY" \
    -d '"Approved"'
  ```
</CodeGroup>

### Reset the Sandbox

`POST` `/sandbox/reset`

Deletes all customers, wallets, fiat accounts, transactions, and autoramps. Requires an `IDEMPOTENCY-KEY` header.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.sandbox.iron.xyz/api/sandbox/reset" \
    -H "IDEMPOTENCY-KEY: $(uuidgen)" \
    -H "X-API-Key: $API_KEY"
  ```
</CodeGroup>