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

# Sandbox Reference

> Everything that behaves differently in the Etherfuse sandbox: base URLs, test data, simulated deposits, and testnet tokens.

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 lists everything that behaves **differently in sandbox**. If you have not set up your sandbox account yet, start with [Initial Setup](https://docs.etherfuse.com/v2/initial-setup.md).

## Base URLs & environments

| | Sandbox | Production |
| - | - | - |
| API base URL | `https://api.sand.etherfuse.com` | `https://api.etherfuse.com` |
| JWT access token / launch host (`aud`) | `https://api.sand.etherfuse.com/auth/token` | `https://api.etherfuse.com/auth/token` |
| Dashboard | [sandbox.etherfuse.com](https://sandbox.etherfuse.com) | [app.etherfuse.com](https://app.etherfuse.com) |

* 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 part of the key (`api_sand_...` vs `api_prod_...`).
* Sandbox connects to **testnets**: Stellar **Testnet**, Solana **Devnet**, and testnet for the other supported chains.
* **KYB is simulated in sandbox; you approve it yourself.** API keys need a business account with approved KYB, and your organization must be approved to quote. The sandbox [KYB page](https://sandbox.etherfuse.com/start) has an **Approve KYB** button that clears it without documents or admin review. Production KYB is a real review.

> [!WARNING]
>
> **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 put a production API key in client-side code. Production integrations must call the API from a server.

## KYC in sandbox

Sandbox accepts fake data for KYC; no real personal information is required.

> [!NOTE]
>
> **KYC auto-approves.** When a `personal` customer completes the [`/idv` launch](https://docs.etherfuse.com/v2/guides/kyc-websdk) (identity documents and agreement signing), we approve them automatically and send a `kycUpdated` delivery, with no manual review. The document checks do not run, so you can upload **any** document images.
>
> **Mexican customers need this test person.** Sandbox still runs Mexico's RFC check against the tax authority's (SAT) test registry, and compares the name it returns with the customer's personal data. Enter these values at the personal data step:
>
> | Field | Value |
> | - | - |
> | First name | `CARLOS` |
> | Last name | `RAMIREZ LOPEZ` |
> | RFC | `HEGL900101AB6` |
> | CURP | Any CURP in the right format, such as `HEGL900101MDFRNT00` |
>
> With any other name, `personalData` becomes `actionRequired` a few seconds after the customer submits. See [Country-specific requirements](https://docs.etherfuse.com/v2/guides/onboarding.md#country-specific-requirements).
>
> **Expect a proof of address step.** Sandbox reads every identity document as test data with no address, so every sandbox customer is asked for a proof of address. Any image passes.
>
> Production still requires review.

> [!NOTE]
>
> **The [KYC API](https://docs.etherfuse.com/v2/guides/kyc-api.md) flow behaves the same in sandbox**, with the same one difference: the document checks do not run, so we do not inspect document content. Everything else is real. We validate submissions the same way, store them on the customer's profile the same way, and advance the flow [stage by stage](https://docs.etherfuse.com/v2/guides/onboarding.md#requirements-unlock-in-stages), including the rule that personal data comes first, that we ask for a proof of address only when the identity document had none, and that the customer agreement can be sent only once it appears in the requirements list. The integration you build against sandbox is the one that works in production.
>
> A Mexican customer needs `additionalInfo.curp` and `taxId` (RFC). The RFC check runs, so send the test person above: `"firstName": "CARLOS"`, `"lastName": "RAMIREZ LOPEZ"` and `"taxId": "HEGL900101AB6"`. Sandbox reads every identity document as test data with no address, so the flow always asks for a proof of address after the identity stage. Any image passes.
>
> **[Importing a shared Sumsub session](https://docs.etherfuse.com/v2/guides/kyc-sumsub-shared-token.md) 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.

## Payment accounts in sandbox

Register bank accounts and wallets with [`POST /organization/{organizationId}/payment_account`](https://docs.etherfuse.com/v2/api-reference/payment-accounts/register-payment-account), exactly as in production. Use dummy values, for example the CLABE `012180000000000002` and the RFC `XAXX010101000`.

A new account starts `pending`, and sandbox moves it to `ready` within a few seconds. To test a rejection, register a bank account with `registrationInfo.accountHolderName` set to `Rechazo Ejemplo`: its directions become `rejected`, with `rejection.code` `holderNameMismatch`. Register it again with a different name to retry. Read the account's `rails` with [`GET /organization/{organizationId}/payment_account/{id}`](https://docs.etherfuse.com/v2/api-reference/payment-accounts/get-payment-account), or subscribe to `paymentAccountUpdated`, and quote the direction once it is `ready`.

Register wallets with testnet addresses on the chain you name in `accountDetails.chain`.

## Simulating orders in sandbox

No real money moves in sandbox; we simulate deposits and payouts.

* **Onramps:** in production we detect the customer's SPEI or PIX deposit. In sandbox, **simulate the deposit** with [`POST /organization/{organizationId}/order/{id}/fiat_received`](https://docs.etherfuse.com/v2/api-reference/sandbox/simulate-fiat-received), sending the `amount` the customer paid:

  ```bash theme={null}
  curl -X POST https://api.sand.etherfuse.com/organization/<organization_id>/order/<order_id>/fiat_received \
    -H "Authorization: <your_sandbox_api_key>" \
    -H "Content-Type: application/json" \
    -d '{ "amount": "100" }'
  ```

  The response is `200` with an empty body, and the order continues as it would after a real deposit. The endpoint works only for an order whose source is a bank account on `spei` or `pix`; other orders return `422` `unsupported`. In production it returns `403` `forbidden`.
* **Offramps:** there is no simulation step. The customer sends the tokens as `fundingInstructions` describe, and the sandbox processes the fiat payout once the transaction confirms on-chain.
* **Onramp cap:** sandbox onramps are capped at **500 MXN per quote**. A larger amount returns `400` `sandbox-limit-exceeded`. Production has no such cap.

## Testnet tokens

You need testnet tokens to test offramps and swaps; you do not need to contact Etherfuse. **There is no faucet.** Get tokens by **onramping** an Etherfuse token (for example CETES), then **swapping** it for any other supported token (USDC and others). See [Testing Onramps](https://docs.etherfuse.com/v2/guides/testing-onramps.md) and [Testing Swaps](https://docs.etherfuse.com/v2/guides/testing-swaps.md).

> [!WARNING]
>
> **Sandbox asset identifiers differ from production.** Do not hardcode token or issuer addresses. Always read the token's `asset` from [`GET /supported_assets`](https://docs.etherfuse.com/v2/api-reference/assets/list-supported-assets) for the current environment when you quote.

> [!NOTE]
>
> **Stellar: onramps to a wallet without a trustline.** When you onramp to a Stellar wallet that has no trustline for the asset (or does not exist on-chain yet), the order becomes `claimable` after delivery. Prepare the claim with [`POST /organization/{organizationId}/order/{id}/claim`](https://docs.etherfuse.com/v2/api-reference/orders/prepare-claim) and have the customer sign the transaction it returns to add the trustline and claim the tokens. For **offramps and swaps**, the wallet must already have trustlines: use `GET /supported_assets?chain=stellar` to get identifiers in `CODE:ISSUER` format and set up the trustline first. See [Stellar](https://docs.etherfuse.com/v2/guides/chains/stellar.md).

## Webhooks in sandbox

Webhooks work the same in sandbox as in production. Sandbox also accepts `http` URLs; production requires `https`. Make sure your endpoint is publicly reachable (or use a tunnel such as ngrok for local development) and subscribe with [`POST /webhook_subscription`](https://docs.etherfuse.com/v2/api-reference/webhook-subscriptions/create-webhook-subscription). See [Webhooks](https://docs.etherfuse.com/v2/webhooks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.