Sandbox Simulation

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

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.

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. Simulated withdrawals run through the real balance check, so simulate a deposit into the same wallet first or the withdrawal returns 402 INSUFFICIENT_BALANCE.

Example Stablecoin Deposit Simulation

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

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

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

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.

Field Notes

Fiat deposits accept currency: "NGN" only. Stablecoin withdrawals accept currency of USDT or USDC only. Other values return 400.
The stablecoin deposit request names the asset with symbol; the stablecoin withdrawal request uses currency.
idempotency_key is accepted on the two deposit simulations only. Withdrawal simulations generate their own key.
The fiat deposit response returns the new record as transaction_id; the stablecoin deposit response returns it as id.

Example KYB Status Simulation

curl https://api-staging.stabyl.com/v1/simulate/kyb/status \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0197f1f0-0000-7000-8000-000000000001",
    "status": "approved"
  }'

status is one of approved, rejected, or pending. The response echoes user_id and status and adds decision, one of approved, denied, or unknown, which is the value production gates check.

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, or a currency is not supported by that simulation
`402`	The simulated withdrawal exceeds the wallet’s available balance
`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.

Get Started

Wallets

Exchange

Webhooks

WebSocket

How To Use Simulation Safely

Example Stablecoin Deposit Simulation

Example Fiat Deposit Simulation

Example Fiat Withdrawal Simulation

Example Stablecoin Withdrawal Simulation

Field Notes

Example KYB Status Simulation

Required Headers

Common Failures

​How To Use Simulation Safely

​Example Stablecoin Deposit Simulation

​Example Fiat Deposit Simulation

​Example Fiat Withdrawal Simulation

​Example Stablecoin Withdrawal Simulation

​Field Notes

​Example KYB Status Simulation

​Required Headers

​Common Failures

How To Use Simulation Safely

Example Stablecoin Deposit Simulation

Example Fiat Deposit Simulation

Example Fiat Withdrawal Simulation

Example Stablecoin Withdrawal Simulation

Field Notes

Example KYB Status Simulation

Required Headers

Common Failures