Skip to main content
The sandbox is a full copy of the API for development: same endpoints and auth as production, connected to blockchain testnets, with no real money or personal data. This page is the single reference for everything that behaves differently in sandbox. If you haven’t set up your sandbox account yet, start with Initial Setup.

​
Base URLs & environments

  • The endpoints and auth scheme are identical across environments; only the base URL and API key differ. Build against sandbox, then swap the base URL to go live.
  • API keys are environment-specific and not interchangeable. The environment is baked into the key (api_sand_… vs api_prod_…).
  • Sandbox connects to testnets: Stellar Testnet, Solana Devnet, and testnet for the other supported chains.
  • KYB is required in sandbox too, but you approve it yourself: API keys need a business account with approved KYB. The sandbox KYB page has an Approve KYB button that clears it without documents or admin review. Production KYB is a real review.
Interactive testers use sandbox keys only. The in-docs playgrounds and any browser-side testing send authenticated requests from the browser. Use a sandbox key only; never embed a production API key in client-side code. Production integrations must call the API server-side.

​
KYC in sandbox

Sandbox accepts fake data for KYC; no real personal information is required.
KYC auto-approves. When a personal customer completes the /idv launch (identity documents + agreement signing) they auto-approve and a kyc_updated webhook fires, with no manual review. The identity checks don’t actually run, so you can upload any document images.The one exception is Mexico: if the customer selects Mexico they must upload a Constancia de Situación Fiscal at the tax-document step, or the flow won’t pass. Any constancia works; it just needs to look like a valid one. Use this example, or see Country-specific requirements.Production still requires review.
The KYC API flow behaves identically in sandbox, with the same one difference: the checks don’t actually run, so document content isn’t scrutinised and government registry checks are skipped. Everything else is real. Submissions are validated the same way, land on the customer’s profile the same way, and the flow advances stage by stage, including the rule that personal data comes first and that a proof of address is only requested when the identity document carried none. The integration you build against sandbox is the one that works in production.A Mexican customer’s constancia is still read: its RFC comes from the document itself, so a sample belonging to somebody else records the wrong identity.Importing a shared Sumsub session needs a second sandbox account to act as the donor, configured for sharing exactly as in production. Without one, build the rest of the integration against the KYC API flow and add the import when sharing is in place.

​
Bank accounts in sandbox

Use a placeholder RFC to auto-approve a bank account. When registering a bank account via API in sandbox, use one of these placeholder RFCs so Etherfuse provisions it without involving the real SPEI provider:These skip SPEI provider registration and mark the account active immediately, so you can go straight to creating orders. Any other RFC in sandbox is sent to the SPEI provider’s sandbox and treated as a real registration; it will not auto-approve. Both placeholders are rejected in production.
Optional: test with a real bank account. To verify a real Mexican bank account wires up correctly with our SPEI provider, link it in sandbox using its real RFC. No real funds are moved; all sandbox transactions are simulated even with a real bank account. This is optional; the placeholder RFCs above cover standard testing.

​
Simulating orders in sandbox

No real money moves in sandbox; deposits and payouts are simulated.
  • Onramps: production detects the customer’s MXN deposit automatically via SPEI. In sandbox, simulate the deposit with the sandbox-only Simulate Fiat Received endpoint (POST /ramp/order/fiat_received) using the order’s orderId.
  • Offramps: no simulation step; the sandbox processes the fiat payout automatically once the burn transaction confirms on-chain.
  • Onramp cap: sandbox onramps are capped at 500 MXN per quote (larger amounts are rejected). Production has no such cap.
  • Every order response includes a statusPage URL (https://sandbox.etherfuse.com/ramp/order/<order_uuid>) you can open in a browser to track progress, sign transactions, and debug without polling.

​
Testnet tokens

You’ll need testnet tokens to test offramps and swaps; no need to contact Etherfuse. There is no faucet. Get tokens by onramping an Etherfuse token (e.g. CETES), then swapping it for any other supported token (USDC, etc.). See Testing Onramps and Testing Swaps.
Sandbox asset identifiers differ from production. Don’t hardcode mint/issuer addresses; always resolve the identifier from GET /ramp/assets for the current environment when quoting or building orders.
Stellar: trust lines for onramps are handled automatically. When onramping to a Stellar wallet without a trustline (or that doesn’t exist on-chain yet), pass walletAddress in the quote; the quote fee includes a one-time onboarding cost, and after the order completes you sign the stellarClaimTransaction from the order response to add the trustline and claim your tokens. For offramps and swaps, the wallet must already have trust lines: use GET /ramp/assets?blockchain=stellar to get identifiers in CODE:ISSUER format and establish the trustline first.

​
Webhooks in sandbox

Webhooks work the same in sandbox as in production. Make sure your endpoint is publicly reachable (or use a tunnel like ngrok for local development) and register it via POST /ramp/webhook.