Sandbox Trades

Overview

The sandbox environment mirrors production trade APIs but omits real liquidity providers and on- chain settlement. Use this guide to anticipate behaviors that differ from production when testing trades.

For sandbox-specific transfer behavior, see Sandbox Transfers.

Trades stop at executed

In sandbox, trades progress to the executed state and do not transition to settling or completed. Liquidity providers do not support trades on testnets, so sandbox cannot perform the final on-chain settlement.

This is the most common surprise when validating trade flows. Treat executed as the terminal sandbox state — confirm your integration handles the executed transition and treats it as the trade success signal in sandbox.

ℹ️

Funds available for downstream testing

Even though sandbox trades stop at executed and platform_available does not reflect the trade outcome, the platform makes the funds available so you can continue exercising downstream flows (transfers, withdrawals, inter-account moves). In production, the trade progresses to completed and platform_available is updated normally.

Simulate trade failures

Use the expected_error field on POST /api/trades to deterministically simulate failures and exercise your error-handling paths. The field is sandbox-only and accepts:

{
  "quote_guid": "quote_guid",
  "expected_error": "non_sufficient_funds"
}

The trade transitions to failed with the matching failure_code. Use this to validate retry logic, customer-facing error messages, and state-machine handling without waiting on real market or balance conditions.

If a sandbox trade fails with a real spread/tolerance error (rather than a simulated one), contact support to adjust the BPS for your bank temporarily.

⚠️

Production variability

Production trades fail for reasons that don't surface in sandbox — market volatility, real-time spread movement, liquidity provider routing, and rail-specific timing. Use both webhooks and polling on GET /api/trades/{trade_guid} so your integration handles every terminal state (completed, failed, cancelled) regardless of which signal arrives first. See Webhooks for subscription setup.

USDC off-ramp behavior

Direct transfers from USDC (crypto) to an external bank account via Plaid are not supported in either environment. To off-ramp USDC to a bank account:

1. Convert USDC to USD using a trade.
2. Withdraw USD using a funding transfer.

In sandbox, step 1 stops at executed as described above. The platform still makes the converted USD available so you can continue to step 2; validate end-to-end timing in production.

Related guides

• Create and execute a trade
• Trade fees
• Crypto Trade Settlement
• Sandbox Transfers