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

# Sandbox Simulation

> Non-production endpoints for testing wallet, KYB, and notification flows.

Simulation endpoints are available only outside production. Use them to test integration behavior without moving real funds.

| Endpoint                                       | Purpose                                         |
| ---------------------------------------------- | ----------------------------------------------- |
| `POST /simulate/fiat/deposits`                 | Credit a test NGN fiat deposit                  |
| `POST /simulate/fiat/withdrawals`              | Create a test fiat withdrawal transaction       |
| `POST /simulate/crypto/deposits`               | Credit a test USD stablecoin deposit            |
| `POST /simulate/crypto/withdrawals`            | Create a test stablecoin withdrawal transaction |
| `POST /simulate/kyb/status`                    | Set a test user's KYB status                    |
| `POST /simulate/notifications/product-updates` | Insert a test product update notification       |

<Warning>
  Simulated withdrawals are sandbox records for integration testing and never move funds. Production Partner API withdrawal quote and submit calls use the signed request flow described in [Withdrawals](/docs/withdrawals).
</Warning>

## How To Use Simulation Safely

Simulation is for exercising your client behavior:

* deposit credit handling
* transaction timeline reconciliation
* failed or pending record handling
* KYB-gated flows in staging
* notification rendering and delivery tests

Do not reuse simulation payloads as production assumptions. Production money movement can have additional timing and review states.

The wallet simulation requests identify the target staging account by
`user_id`. Replace the example UUID below with your staging account user ID.

## Example Stablecoin Deposit Simulation

```bash theme={null}
curl https://api-staging.stabyl.com/v1/simulate/crypto/deposits \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0197f1f0-0000-7000-8000-000000000001",
    "chain": "tron",
    "symbol": "USDT",
    "amount": "25.00",
    "idempotency_key": "sim_crypto_dep_001"
  }'
```

After creating a simulated deposit, verify that your reconciliation process
upserts the resulting wallet transaction by transaction ID. Simulation records
do not replace testing a staging workflow that produces the webhook events your
integration subscribes to.

## Example Fiat Deposit Simulation

```bash theme={null}
curl https://api-staging.stabyl.com/v1/simulate/fiat/deposits \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0197f1f0-0000-7000-8000-000000000001",
    "amount": "50000.00",
    "currency": "NGN",
    "idempotency_key": "sim_fiat_dep_001"
  }'
```

## Example Fiat Withdrawal Simulation

```bash theme={null}
curl https://api-staging.stabyl.com/v1/simulate/fiat/withdrawals \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0197f1f0-0000-7000-8000-000000000001",
    "amount": "500.00",
    "currency": "NGN"
  }'
```

## Example Stablecoin Withdrawal Simulation

```bash theme={null}
curl https://api-staging.stabyl.com/v1/simulate/crypto/withdrawals \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0197f1f0-0000-7000-8000-000000000001",
    "chain": "tron",
    "currency": "USDT",
    "amount": "2.5"
  }'
```

Withdrawal simulations create non-production transaction records. They do not
perform a payout and must not be used to infer production timing or finality.

## Required Headers

Simulation endpoints are public in non-production environments. Send `Content-Type: application/json` for JSON request bodies.

## Common Failures

| Status | Meaning                                                |
| ------ | ------------------------------------------------------ |
| `400`  | Request body is invalid                                |
| `403`  | Simulation is not available in the current environment |
| `404`  | Referenced test account or resource was not found      |

Use simulation responses to verify your reconciliation and notification handling before production access.