Integración con el Sandbox
El Sandbox es un Environment aislado donde Deposits, Withdrawals y Ledger ejecutan exactamente el mismo código que producción — la única diferencia es que la confirmación de red blockchain es simulada, nunca real. Ninguna Blockchain Transaction real se crea nunca desde un Sandbox, y ningún dato de Sandbox llega nunca a Production.
Todo comando de simulación exige que el Environment objetivo sea de tipo Sandbox — llamar
estas rutas contra un Environment Production devuelve 422 ENVIRONMENT_NOT_SANDBOX, sin ningún
efecto colateral. Este es el mecanismo de seguridad central: no es un error a evitar, es la
protección que hace seguro probar tu integración sin ningún riesgo para dinero real.
Faucet — saldo de prueba instantáneo
La forma más rápida de tener saldo de prueba: observa, acredita y confirma en un solo paso.
POST /v1/environments/{environmentId}/sandbox/faucet
Importante: el depositAddress enviado debe ser exactamente el dirección devuelto por un
Payment Intent ya creado para la Transaction que quieres
financiar — el Sandbox solo simula la llegada de la red; el módulo que efectivamente acredita el
saldo Available de la Account es Deposits, resolviendo el Payment Intent de ese dirección. Un
depositAddress arbitrario (sin Payment Intent correspondiente) hace que el Sandbox responda
200 normalmente, pero Deposits ignora silenciosamente el evento (dirección de otro contexto) —
ningún saldo se acredita. Ver Ledger y
Transaction/Settlement para el flujo completo (Transaction
→ Payment Intent → Faucet/simulate-deposit).
Simular un Deposit paso a paso
Para probar cómo reacciona tu integración a confirmaciones progresivas (en vez del crédito instantáneo del Faucet), simula cada etapa por separado:
POST .../sandbox/simulate-deposit— registra la transacción observada.POST .../sandbox/simulate-confirmation— registra una confirmación de red (llama tantas veces como quieras, controlando el número de confirmaciones).
Consulta el estado en cualquier momento:
GET .../sandbox/observed-addresses/{id}.
Simular el broadcast de un Withdrawal real
Una llamada real a withdrawals.request() es Self-Custody de extremo a extremo (vea
Self-Custody): construye un SigningRequest para que usted lo firme,
exactamente como el Settlement. En cuanto todas las legs están firmadas y enviadas, el
all-signatures gate de la plataforma dispara el broadcast automáticamente — simule la
confirmación de ese broadcast de la misma forma que lo haría para una leg de Settlement:
POST .../sandbox/simulate-broadcast-confirmation,
usando el broadcastAttemptId derivado del propio broadcastReference de esa leg (haga polling a
GET /v1/signing-requests/{signingRequestId} hasta que aparezca — vea self-custody-settlement.ts
en el ejemplo de Mercatto para el código real exacto,
reutilizado de forma idéntica para las legs de Withdrawal).
POST .../sandbox/simulate-withdrawal (y su propio
GET .../sandbox/broadcast-attempts/{id}) es una utilidad de simulación separada e
independiente — crea su propio SandboxBroadcastAttempt, desconectado de cualquier
Withdrawal/ExecutionLeg real. Confirmado en vivo: la estrategia real de ejecución de
Withdrawal en Self-Custody nunca lo lee ni lo escribe. No construya una prueba de integración
real de Withdrawal alrededor de ella.
Ajustar el saldo observado de la Treasury (reconciliación)
Para probar escenarios de reconciliación (TreasuryReconciliation), el Sandbox permite ajustar
directamente el saldo observado de la Treasury para un Asset Network:
POST .../sandbox/treasury-balance
Por qué esto es seguro
Todas las simulaciones pasan por el mismo Workflow, Ledger y Settlement reales — lo único
que cambia es el origen del evento de confirmación de red (simulado, no una blockchain real). Tu
integración, probada en Sandbox, se comporta exactamente como se comportaría en Production, con
la misma API, los mismos eventos y el mismo modelo de datos.