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

# Sandbox

> Build and test against SpherePay without real money or real identities. Learn how sandbox keys, test networks, and the faucet work.

Sandbox is a separate SpherePay deployment that behaves like production and moves nothing of value. You use it to build your integration, exercise the transfer lifecycle, and run your test suite without real customers, real funds, or real identity documents.

Your request bodies are identical in both places. Switch both the base URL and the key: each host accepts only its own environment's keys.

## What is different

| | Production | Sandbox |
| - | - | - |
| Base URL | `https://api.spherepay.co` | `https://api.sandbox.spherepay.co` |
| API key prefix | `secret_` | `sandbox_secret_` |
| `ethereum` resolves to | Ethereum mainnet | Sepolia |
| `sol` resolves to | Solana mainnet | Solana Devnet |
| Funds | Real | Test tokens with no value |

Everything else — endpoints, request shapes, response shapes, webhook events, error envelopes — is the same code. That is the point: what you build against sandbox is what runs in production.

## Get a sandbox key

Sandbox keys are created from the dashboard, in sandbox mode, under **Developers → API Keys**. They start with `sandbox_secret_` so you can tell at a glance that a key is not a production credential.

A sandbox key works only against `api.sandbox.spherepay.co`, and a production key works only against `api.spherepay.co`. There is no routing between them: present the wrong key and the request is rejected exactly as any unrecognized key would be.

> [!WARNING]
>
> Keep sandbox and production keys in separate configuration. Pointing a test suite at production because a key was pasted into the wrong environment variable moves real money.

## Choose a network

Pass the same network slugs you use in production. Sandbox resolves them to test networks:

```json theme={"dark"}
{
  "network": "ethereum"
}
```

In sandbox that reaches Sepolia. `sol` reaches Solana Devnet.

A sandbox request naming a network with no test configuration is rejected rather than falling through to a mainnet network. You cannot reach mainnet from a sandbox key.

## Mint test tokens

SPHEREUSDC is the sandbox test stablecoin. Mint it to any address on either test network with the faucet:

```bash theme={"dark"}
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST https://api.sandbox.spherepay.co/v2/sandbox/faucet \
  -H "Authorization: Bearer $SPHERE_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "network": "sol",
    "address": "bnZZ5unXUpgzfBjntgpivQkPhqxfjvp7TUyJfYdJ8yN",
    "amount": "1000"
  }'
```

Generate the idempotency key once per mint and reuse it if you retry, so a lost response does not mint twice.

The response is `202 Accepted` with a mint id. Minting is asynchronous, so poll for the transaction hash:

```bash theme={"dark"}
curl https://api.sandbox.spherepay.co/v2/sandbox/faucet/{id} \
  -H "Authorization: Bearer $SPHERE_SANDBOX_KEY"
```

`amount` defaults to `1000` and accepts at most `1000` per call. A mint that would take the wallet above `10000` SPHEREUSDC, counting pending mints, is refused. Send an `Idempotency-Key` header so a retry returns the same mint rather than minting twice. Reusing a key with different parameters returns `409`.

> [!NOTE]
>
> The faucet mints tokens, not gas. Fund the wallet's native balance from a public Sepolia or Solana Devnet faucet before sending a transaction from it.

## Advance a transfer

In production a transfer moves through its lifecycle as deposits arrive and rails settle. In sandbox you drive it yourself:

```bash theme={"dark"}
curl -X POST https://api.sandbox.spherepay.co/v2/sandbox/transfer/{id}/advance \
  -H "Authorization: Bearer $SPHERE_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "fundsReceived" }'
```

Each advance runs the same status machine and the same webhook pipeline as production, so your webhook handlers receive the events they will receive in production, in the same shapes.

The endpoint is idempotent by state. Advancing to the status a transfer is already in returns the original result and emits nothing, so a replayed or concurrent call is safe.

Only some transitions are legal from a given status. An illegal one returns `transfer/invalid-transition` rather than forcing the transfer into an inconsistent state.

> [!NOTE]
>
> These routes exist only on the sandbox deployment. On `api.spherepay.co` they return `404`, so there is no way to advance a real transfer by hand.

## Simulation endpoints

These endpoints exist only on `https://api.sandbox.spherepay.co`:

* [Advance a sandbox customer](https://docs.spherepay.co/api-reference/sandbox/customer-advance.md): `POST /v2/sandbox/customer/{id}/advance`
* [Advance a sandbox transfer](https://docs.spherepay.co/api-reference/sandbox/transfer-advance.md): `POST /v2/sandbox/transfer/{id}/advance`
* [Mint test tokens](https://docs.spherepay.co/api-reference/sandbox/faucet-post.md): `POST /v2/sandbox/faucet`
* [Retrieve a test token mint](https://docs.spherepay.co/api-reference/sandbox/faucet-get-id.md): `GET /v2/sandbox/faucet/{id}`

Deposit simulation for offloader wallets and virtual accounts is coming.

## Rate limits

The sandbox-only routes are limited per application, not per IP, so a shared CI runner does not throttle itself:

| Route | Limit |
| - | - |
| `POST /v2/sandbox/faucet` | 30 per minute |
| `POST /v2/sandbox/transfer/{id}/advance` | 120 per minute |

Every other endpoint follows the limits on [Rate Limits](https://docs.spherepay.co/concepts/operational/rate-limits.md).

## What sandbox does not do

* It holds no real funds, so nothing you do in sandbox can move money.
* It does not run real identity verification. Customers you create are not screened by Sumsub.
* It is not a staging environment for SpherePay. It deploys from the same branch as production, at the same time.


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