API Reference

Sandbox — Referência completa da Seamless Wallet

Documentação campo a campo dos 8 endpoints do sandbox, com exemplos de request e response, dicas de integração, erros esperados, headers obrigatórios e injeção de falhas. Se você consegue rodar contra este ambiente, sua integração vai passar em produção sem surpresa.

Baixar Postman collection Ver Visao Geral

Base Url

https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet

Todos os endpoints ficam sob este prefixo. É público, roda no edge global, certificado TLS válido — sem VPN, sem allowlist.

Autenticacao

Cada request Post Exige O Header X Signature = HMAC-SHA256 do body cru, usando Sandbox Wallet Hmac Secret. Sem assinatura ou com body alterado ⇒ 401 Invalid Signature.

Idempotencia

Debit, Credit e Rollback exigem X Idempotency Key. Repita o mesmo header com o mesmo body para receber a resposta original — não duplica saldo.

Headers Obrigatorios

Todo Post Passa Por Assinatura Hmac Get (Stats, Reset) não exige assinatura.

Headers Http

Campo	Tipo	Obrig	Descricao Dica
content-type ex.: `application/json`	string	sim	Sempre application/json. Body precisa ser JSON minificado. Se o servidor rejeitar com invalid_signature mesmo com secret certo, garanta que você está assinando o MESMO byte-for-byte do que enviou (sem re-serializar).
x-signature ex.: `9ef2c1...b7a4`	string (hex)	sim	Hmac Sha256 Do Body Cru Hexadecimal Assine ANTES de qualquer transformação do body. Se usar interceptors HTTP, assine no último passo.
x-idempotency-key ex.: `bet_round_2026_07_14_001`	string	Nao	Chave Unica Por Operacao Financeira Obrigatorio Use o round_id + tipo (ex.: bet_r_123, win_r_123). Se falhar timeout, reenvie o MESMO header — a resposta será a original, sem duplicar.
x-timestamp ex.: `1783996311137`	int (unix ms)	Nao	Timestamp Da Requisicao Em Milissegundos Unix Ajuda a debugar clock skew. Se seu clock estiver > 5 min do real, a integração em produção pode rejeitar.

Endpoints

POST

/authenticate

Abrir Sessao Do Jogador

Valida o launch token, cria/recupera o jogador no sandbox e devolve currency + timestamp. Chame no primeiro contato do launch iframe.

Url

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/authenticate

Request Body Query

Campo	Tipo	Obrig	Descricao Dica
user_id ex.: `player_42`	string	sim	Identificador Unico Do Jogador Na Sua Pode ser numérico ou UUID. O sandbox aceita qualquer string; guarde o mesmo user_id nas próximas chamadas.
token ex.: `launch_token_demo`	string	sim	Launch Token Emitido Pelo Seu Backend Em produção, este token é validado por HMAC e tem TTL curto (5-15 min). Gere no momento do launch, não guarde em cache.
currency ex.: `BRL`	string (ISO-4217)	Nao	Moeda Da Sessao Default Brl Suporte A moeda define a divisão em unidades menores (BRL/USD = centavos; JPY/KRW/VND = inteiro).

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
ok	boolean	sim	True Sessao Criada
user_id	string	sim	Ecoa o user_id recebido.
currency	string	sim	Moeda Que O Sandbox Associou A
ts	int (unix ms)	sim	Timestamp Do Servidor No Momento Da

Exemplo de request

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/authenticate
content-type: application/json
x-signature: <hmac-sha256(body)>

{
  "user_id": "player_42",
  "token": "launch_token_demo",
  "currency": "BRL"
}

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "ok": true,
  "user_id": "player_42",
  "currency": "BRL",
  "ts": 1783996311137
}

Erros possíveis

401 invalid_signature

{
  "ok": false,
  "error": "invalid_signature"
}

Dicas De Integracao

Chame /authenticate uma vez por sessão. Depois use /balance pra ler saldo.
user_id novo? O sandbox cria com saldo inicial de 10 000 (unidades menores).
token no sandbox aceita qualquer string; em produção precisa ser HS256 válido.

POST

/balance

Consultar Saldo

Retorna o saldo atual do jogador na moeda pedida. Não altera estado.

Url

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/balance

Request Body Query

Campo	Tipo	Obrig	Descricao Dica
user_id ex.: `player_42`	string	sim	Jogador Cujo Saldo Sera Consultado
currency ex.: `BRL`	string	Nao	Moeda Do Saldo Default Brl Se o jogador não existe ainda, o sandbox cria com saldo inicial de 10 000 (unidades menores da moeda).

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
user_id	string	sim	Jogador Consultado
balance	int	sim	Saldo Em Unidades Menores Centavos P SEMPRE trate como inteiro. Dividir por 100 só na UI. Guardar como float é bug garantido.
currency	string	sim	Moeda Do Saldo

Exemplo de request

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/balance
content-type: application/json
x-signature: <hmac-sha256(body)>

{
  "user_id": "player_42",
  "currency": "BRL"
}

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "user_id": "player_42",
  "balance": 10000,
  "currency": "BRL"
}

Dicas De Integracao

10000 = R$ 100,00 (BRL usa 2 casas decimais).
Não use /balance pra decidir se pode debitar. O /debit já valida atomicamente — usar /balance antes cria race condition.

POST

/debit

Debitar Aposta

Retira amount do saldo do jogador de forma atômica. Idempotente por x-idempotency-key. Retorna insufficient_funds sem alterar saldo se não há fundos.

Url

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/debit

Request Body Query

Campo	Tipo	Obrig	Descricao Dica
user_id ex.: `player_42`	string	sim	Jogador Que Vai Apostar
amount ex.: `100`	int (>=0)	sim	Valor Da Aposta Em Unidades Menores Amount = 0 é aceito (rodada bônus). Amount negativo é rejeitado.
currency ex.: `BRL`	string	sim	Moeda Da Aposta Precisa Bater Com
round_id ex.: `round_2026_07_14_001`	string	sim	Id Da Rodada De Jogo Uma Use o mesmo round_id no /credit e /rollback correspondentes — é como o sandbox relaciona bet ↔ win.

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
status	"ok" \| "insufficient_funds" \| "duplicate"	sim	Resultado Da Operacao
balance_after	int	sim	Saldo Do Jogador Apos O Debito
operator_tx_id	string	sim	Id Interno Gerado Pelo Sandbox Pra Guarde este ID nos seus logs. Útil pra debugar reconciliação.
idempotency_key	string	sim	Ecoa O X Idempotency Key Da

Exemplo de request

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/debit
content-type: application/json
x-signature: <hmac-sha256(body)>
x-idempotency-key: bet_round_2026_07_14_001

{
  "user_id": "player_42",
  "amount": 100,
  "currency": "BRL",
  "round_id": "round_2026_07_14_001"
}

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "status": "ok",
  "balance_after": 9900,
  "operator_tx_id": "op_a7f3c9b1",
  "idempotency_key": "bet_round_2026_07_14_001"
}

Erros possíveis

Insufficient balance

{
  "status": "insufficient_funds",
  "balance_after": 50,
  "operator_tx_id": "op_...",
  "idempotency_key": "bet_..."
}

Duplicata (mesma idem-key)

{
  "status": "duplicate",
  "balance_after": 9900,
  "operator_tx_id": "op_a7f3c9b1",
  "idempotency_key": "bet_round_2026_07_14_001"
}

Dicas De Integracao

Ao receber timeout/5xx, reenvie o MESMO x-idempotency-key. Nunca gere uma nova.
duplicate NÃO é erro — significa que a operação original foi aplicada e você está seguro.
Se seu jogador clica 3x em spin, o mesmo idempotency-key protege de débito duplicado.

POST

/credit

Creditar Premio

Adiciona amount ao saldo do jogador (win, cashout, bônus). Idempotente. bet_id liga ao /debit original.

Url

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/credit

Request Body Query

Campo	Tipo	Obrig	Descricao Dica
user_id ex.: `player_42`	string	sim	Jogador Que Vai Receber O Premio
amount ex.: `250`	int (>=0)	sim	Valor Do Premio Em Unidades Menores
currency ex.: `BRL`	string	sim	Moeda Do Premio
bet_id ex.: `bet_round_2026_07_14_001`	string	sim	X Idempotency Key Do Debit Que Sem bet_id o sandbox aceita (retorna ok), mas em produção você quer sempre ligar win ↔ bet pra reconciliação.

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
status	"ok" \| "duplicate"	sim	Resultado.
balance_after	int	sim	Saldo Do Jogador Apos O Credito
operator_tx_id	string	sim	Id Interno Do Sandbox
idempotency_key	string	sim	Ecoa o x-idempotency-key.

Exemplo de request

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/credit
content-type: application/json
x-signature: <hmac-sha256(body)>
x-idempotency-key: win_round_2026_07_14_001

{
  "user_id": "player_42",
  "amount": 250,
  "currency": "BRL",
  "bet_id": "bet_round_2026_07_14_001"
}

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "status": "ok",
  "balance_after": 10150,
  "operator_tx_id": "op_e2d4a8f0",
  "idempotency_key": "win_round_2026_07_14_001"
}

Dicas De Integracao

amount = 0 é aceito (rodada sem prêmio ainda gera evento pra fechar contabilidade).
Vários /credit no mesmo bet_id são permitidos (freespins, respins). Use idempotency-key distinta em cada.

POST

/rollback

Desfazer Operacao

Reverte um /debit (devolve valor ao jogador) ou um /credit (retira valor do jogador). Só funciona uma vez por original_key.

Url

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/rollback

Request Body Query

Campo	Tipo	Obrig	Descricao Dica
original_key ex.: `bet_round_2026_07_14_001`	string	sim	X Idempotency Key Da Operacao Original Rollback só funciona uma vez por original_key. A segunda tentativa retorna status=already_rolled_back.

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
status	"ok" \| "not_found" \| "already_rolled_back"	sim	Resultado Do Rollback
balance_after	int	sim	Saldo Apos O Rollback Credito Revertido
reverted_amount	int	sim	Valor devolvido/removido.

Exemplo de request

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/rollback
content-type: application/json
x-signature: <hmac-sha256(body)>
x-idempotency-key: rb_bet_round_2026_07_14_001

{
  "original_key": "bet_round_2026_07_14_001"
}

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "status": "ok",
  "balance_after": 10000,
  "reverted_amount": 100
}

Erros possíveis

Chave Nao Existe

{
  "status": "not_found",
  "balance_after": 10000,
  "reverted_amount": 0
}

Ja Revertido

{
  "status": "already_rolled_back",
  "balance_after": 10000,
  "reverted_amount": 0
}

Dicas De Integracao

Use rollback quando o motor de jogo confirmar que a rodada não completou (crash da RNG, timeout no client, disputa).
Não use rollback pra reajustar prêmio — use um novo /credit ou /debit compensatório com bet_id/round_id auditáveis.

POST

/query

Consultar Operacao

Busca o status de qualquer operação pela sua idempotency_key. Use pra reconciliação, auditoria e recuperação de timeouts.

Url

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/query

Request Body Query

Campo	Tipo	Obrig	Descricao Dica
idempotency_key ex.: `bet_round_2026_07_14_001`	string	sim	Chave Da Operacao Que Voce Quer Use este endpoint como reconciliação diária: liste seus rounds locais, consulte cada um, compare status/amount.

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
found	boolean	sim	False Nao Existe Operacao Com Essa
kind	"debit" \| "credit" \| "rollback"	Nao	Tipo Da Operacao
status	"ok" \| "rolled_back"	Nao	Estado atual.
amount	int	Nao	Valor Da Operacao
user_id	string	Nao	Jogador Afetado
round_id	string	Nao	Rodada relacionada.
balance_after	int	Nao	Saldo Do Jogador Logo Depois Da
processed_at	ISO-8601	Nao	Quando A Operacao Foi Processada No

Exemplo de request

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/query
content-type: application/json
x-signature: <hmac-sha256(body)>

{
  "idempotency_key": "bet_round_2026_07_14_001"
}

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "found": true,
  "kind": "debit",
  "status": "ok",
  "amount": 100,
  "user_id": "player_42",
  "round_id": "round_2026_07_14_001",
  "balance_after": 9900,
  "processed_at": "2026-07-14T02:31:52.812Z"
}

Dicas De Integracao

Timeout no /debit? Chame /query com a mesma key: se found=true e status=ok, a aposta foi aplicada — não retente.
Passe ?div_rate=1 pra forçar o sandbox devolver dados divergentes e treinar seu código de reconciliação.

GET

/stats

Estatisticas Agregadas

Retorna métricas agregadas do estado atual do sandbox (útil pra dashboards de load test).

Url

GET https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/stats

Request Body Query

Sem parâmetros — envie apenas os headers (HMAC não é exigido em GET).

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
ok	boolean	sim	True Stats Disponiveis
stats.users	int	sim	Total De Jogadores Criados No Sandbox
stats.ops	int	sim	Total De Operacoes Debit Credit Rollback
stats.balance	int	sim	Soma Dos Saldos De Todos Os
stats.totalDebit	int	sim	Total apostado.
stats.totalCredit	int	sim	Total Pago Em Premios
stats.rtp	float	sim	RTP observado (totalCredit / totalDebit). Use pra sanity check. Rodou 1000 apostas de R$10 e o RTP saiu 0.35? Volume baixo — não é bug do jogo, é variância.
now	int (unix ms)	sim	Timestamp Do Servidor

Exemplo de request

GET https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/stats

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "ok": true,
  "stats": {
    "users": 3,
    "ops": 28,
    "balance": 30550,
    "totalDebit": 2400,
    "totalCredit": 550,
    "rtp": 0.229
  },
  "now": 1783996311137
}

Dicas De Integracao

Não exige HMAC. Endpoint público de leitura.
Rode /stats antes e depois de um teste de carga pra medir throughput e RTP.

GET

/reset

Limpar Estado Do Sandbox

Apaga todos os jogadores, saldos e operações. Use quando quiser começar um teste do zero.

Url

GET https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/reset

Request Body Query

Sem parâmetros — envie apenas os headers (HMAC não é exigido em GET).

Response 200 Ok

Campo	Tipo	Obrig	Descricao Dica
ok	boolean	sim	true = estado limpo.
reset	boolean	sim	True Confirmacao Do Reset

Exemplo de request

GET https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/reset

Exemplo de response

HTTP/1.1 200 OK
content-type: application/json

{
  "ok": true,
  "reset": true
}

Dicas De Integracao

Reset é global no sandbox — todo mundo compartilha. Combine com sua equipe antes de rodar.
Em produção não existe /reset. Não escreva código que dependa de resetar estado.

Injecao De Falhas Query String

Adicione estes parâmetros na URL de qualquer endpoint Post para simular condições reais de produção — latência alta, 5xx, timeouts, divergências. Ideal pra testar sua camada de retry, idempotência e reconciliação.

Query Parameters

Campo	Tipo	Obrig	Descricao Dica
lat_min ex.: `50`	int (ms)	Nao	Latencia Minima Artificial Adicionada Antes De Combine com lat_max pra simular jitter real de rede.
lat_max ex.: `800`	int (ms)	Nao	Latencia Maxima Artificial O Sandbox Sorteia lat_max=800 aproxima de latência de emergência real. lat_max=3000 estressa timeouts.
err_rate ex.: `0.1`	float 0..1	Nao	Probabilidade De Retornar Http 500 Injected 0.1 = 10% das chamadas. Ideal pra validar sua camada de retry.
timeout_rate ex.: `0.05`	float 0..1	Nao	Probabilidade Da Resposta Demorar 10s Forca Use pra validar que seu client cancela a request e depois faz /query pra recuperar o estado real.
insuff_rate ex.: `0.02`	float 0..1	Nao	Probabilidade De Debit Retornar Insufficient Funds Simula usuário que ficou zerado entre o /balance e o /debit. Teste sua UX de erro.
div_rate ex.: `0.1`	float 0..1	Nao	Probabilidade De Query Devolver Dados Divergentes Serve pra estressar sua rotina de reconciliação — o valor real está no /stats.
rtp ex.: `0.97`	float 0..2	Nao	Rtp Alvo Informativo Nao Altera Resultado

Exemplo — 10% de erro + latência até 800ms

POST https://sandbox.i-gaming.co/api/public/v1/sandbox/wallet/debit?lat_max=800&err_rate=0.1&timeout_rate=0.05
content-type: application/json
x-signature: <hmac-sha256(body)>
x-idempotency-key: bet_stress_001

{"user_id":"player_42","amount":100,"currency":"BRL","round_id":"r_stress_001"}

Codigos De Status

Todo erro estruturado vem no body como { "ok": false, "error": "..." } ou como Status dentro de uma resposta 200.

Codigo	Quando Acontece	O Que Fazer
200 OK	Operação processada com sucesso.	Leia o campo status do body — pode ser ok, duplicate, insufficient_funds, etc.
401 invalid_signature	x-signature ausente ou HMAC não bate com o body cru.	Verifique: (a) secret correto, (b) você está assinando o body byte-a-byte do que envia, (c) hex minúsculo.
404 unknown_kind	Path final não é um dos endpoints suportados.	Confira o path — case-sensitive, sem barra final.
405 use POST	Endpoint que exige POST recebeu GET.	Só /stats e /reset aceitam GET. Todos os outros são POST.
500 injected_5xx	Falha injetada via err_rate.	Retente com backoff exponencial. Mesmo x-idempotency-key.
500 error (real)	Erro inesperado (DB, RPC). Raro.	Guarde o response body. Rode /query com a mesma idem-key pra ver se aplicou. Contate suporte.

Pronto pra integrar?

Baixe a Postman collection com todos os endpoints já configurados e pre-request script que assina HMAC automaticamente. Rode contra o sandbox, valide sua integração, depois fale com a gente pra ir pra produção.

Postman collection Voltar Para Sandbox Falar Com Suporte