Integração com o Sandbox
O Sandbox é um Environment isolado onde Deposits, Withdrawals e Ledger rodam exatamente o mesmo código de produção — a única diferença é que a confirmação de rede blockchain é simulada, nunca real. Nenhuma Blockchain Transaction real é criada a partir de um Sandbox, e nenhum dado de Sandbox chega a Production.
Todo comando de simulação exige que o Environment alvo seja do tipo Sandbox — chamar essas
rotas contra um Environment Production retorna 422 ENVIRONMENT_NOT_SANDBOX, sem nenhum
efeito colateral. Esse é o mecanismo de segurança central: não é um erro a evitar, é a proteção
que torna seguro testar sua integração sem risco de afetar dinheiro real.
Faucet — crédito instantâneo de saldo de teste
O jeito mais rápido de ter saldo de teste: observa, credita e confirma em um único passo.
POST /v1/environments/{environmentId}/sandbox/faucet
Importante: o depositAddress enviado precisa ser exatamente o endereço retornado por um
Payment Intent já criado para a Transaction que você quer
financiar — o Sandbox só simula a chegada da rede; quem credita o saldo Available da Account
é o módulo Deposits, resolvendo o Payment Intent daquele endereço. Um depositAddress
arbitrário (sem Payment Intent correspondente) faz o Sandbox responder 200 normalmente, mas
Deposits ignora silenciosamente o evento (endereço de outro contexto) — nenhum saldo é
creditado. Ver Ledger e Transaction/Settlement
para o fluxo completo (Transaction → Payment Intent → Faucet/simulate-deposit).
Simular um Deposit passo a passo
Para testar como sua integração reage a confirmações progressivas (em vez do crédito instantâneo do Faucet), simule cada etapa separadamente:
POST .../sandbox/simulate-deposit— registra a transação observada.POST .../sandbox/simulate-confirmation— registra uma confirmação de rede (chame quantas vezes quiser, controlando o número de confirmações).
Consulte o estado a qualquer momento:
GET .../sandbox/observed-addresses/{id}.
Simular o broadcast de um Withdrawal real
Uma chamada real a withdrawals.request() é Self-Custody de ponta a ponta (ver
Self-Custody): ela constrói um SigningRequest para você assinar,
exatamente como o Settlement. Assim que todas as legs estiverem assinadas e submetidas, o
all-signatures gate da plataforma dispara o broadcast automaticamente — simule a confirmação
desse broadcast da mesma forma que faria para uma leg de Settlement:
POST .../sandbox/simulate-broadcast-confirmation,
usando o broadcastAttemptId derivado do próprio broadcastReference daquela leg (faça polling
em GET /v1/signing-requests/{signingRequestId} até ele aparecer — ver self-custody-settlement.ts
no exemplo Mercatto para o código real exato, reutilizado
de forma idêntica para as legs de Withdrawal).
POST .../sandbox/simulate-withdrawal (e seu próprio
GET .../sandbox/broadcast-attempts/{id}) é um utilitário de simulação separado e independente —
ele cria seu próprio SandboxBroadcastAttempt, desconectado de qualquer Withdrawal/
ExecutionLeg real. Confirmado ao vivo: a estratégia real de execução de Withdrawal em
Self-Custody nunca o lê nem o escreve. Não construa um teste de integração real de Withdrawal em
torno dele.
Ajustar o saldo observado da Treasury (reconciliação)
Para testar cenários de reconciliação (TreasuryReconciliation), o Sandbox permite ajustar
diretamente o saldo observado da Treasury para um Asset Network:
POST .../sandbox/treasury-balance
Por que isso é seguro
Todas as simulações passam pelo mesmo Workflow, Ledger e Settlement reais — o que muda é
apenas a origem do evento de confirmação de rede (simulado, não uma blockchain real). Sua
integração testada em Sandbox se comporta exatamente como se comportaria em Production, com a
mesma API, os mesmos eventos, e o mesmo modelo de dados.