GuidesRecipesAPI ReferenceChangelog
Guides
  1. Trades

Sandbox Trades

What sandbox-specific behavior should I expect when testing 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:

expected_errorSimulated failure
expired_quoteTrade fails because the quote expired before execution
non_sufficient_fundsTrade fails because the source account has insufficient balance
{
  "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