Pular para o conteúdo principal

Wallet Balance

Wallet Balance responde a uma pergunta diferente da do Ledger. O Ledger é a contabilidade econômica da própria Ishtaran — Available, Pending, Reserved, Payable, Delivered — populada exclusivamente por fluxos reais de Payment/Settlement/Payout. Wallet Balance é uma observação do estado da chain: quantos tokens realmente estão, agora, no endereço self-custody registrado de uma Account. Simulado no Sandbox, real on-chain em Production.

Nunca some os dois, nunca substitua um pelo outro. Uma Account pode ter um Payable grande no Ledger e um Wallet Balance de 0 ao mesmo tempo — nada foi pago on-chain ainda. Ou uma wallet pode ter fundos sobre os quais o Ledger não tem nenhuma opinião — seu dono moveu dinheiro para lá vindo de fora de qualquer fluxo mediado pela Ishtaran.

Um exemplo concreto​

Suponha que a wallet de uma Account tenha 100 USDT on-chain agora mesmo (Wallet Balance), enquanto seu Ledger mostra Payable: 30, Reserved: 10, Delivered: 25 de atividade de Settlement não relacionada. São cinco números separados respondendo cinco perguntas separadas — nunca some, e nunca reporte um como se fosse o outro:

CampoFontePergunta que responde
Wallet Balance: 100 USDTEstado de chain observado"Quantos tokens estão neste endereço agora mesmo?"
Ledger Payable: 30Settlement (ainda não pago)"Quanto a Ishtaran liquidou para esta Account mas ainda não moveu on-chain?"
Ledger Reserved: 10Reserva de Transaction (em andamento)"Quanto está bloqueado contra uma Transaction ainda em progresso?"
Ledger Delivered: 25Payout (já movido on-chain)"Quanto a Ishtaran já pagou historicamente a esta Account?"

Um Wallet Balance de 100 não significa que 30 disso seja "o Payable"; a wallet pode ter esses 100 de um depósito completamente não relacionado, um Payout anterior, ou fundos movidos de fora da Ishtaran por completo. Ao contrário, um Payable de 30 não garante que a wallet mostrará +30 uma vez pago — o timing on-chain, as taxas de rede, e payouts parciais fazem os dois números se moverem de forma independente. Mostre ambos, rotulados separadamente, nunca combinados num único saldo exibido.

Por que isso existe​

Toda Account com uma ExecutionDestination registrada já tem uma wallet real, endereçável — o Self-Custody exige uma antes que qualquer leg de Settlement possa executar. Wallet Balance responde à pergunta que esse próprio endereço sempre implicitamente levanta: "quanto realmente há ali?" — sem exigir que um Settlement, um Withdrawal, ou qualquer outro evento que afete o Ledger tenha acontecido antes.

Consultando um saldo​

  • Leitura em snapshot — GET /v1/accounts/{accountId}/wallet-balances retorna a última observação conhecida da plataforma: o endereço, o saldo, quando foi observado pela última vez, e se essa observação está desatualizada. Essa chamada nunca consulta a blockchain diretamente — segura de chamar a cada carregamento de página.
  • Atualização autoritativa — POST /v1/accounts/{accountId}/wallet-balances/refresh pede à plataforma para verificar o estado real da chain agora. A plataforma aplica sua própria guarda curta (~30 segundos) de frescor/single-flight no lado do servidor — chamar isso com mais frequência do que o necessário é sempre seguro, nunca um erro, nunca custo extra de provider. Verifique os campos stale/refreshSuppressed da resposta para saber se uma verificação real de fato aconteceu.
  • Agregado multi-asset — GET /v1/accounts/{accountId}/wallet-balances/aggregate soma o saldo entre vários AssetNetworks que o chamador já conhece (por exemplo, USDT em múltiplas networks), agrupado por Asset, com um detalhamento por network no resultado. Nunca soma entre Assets diferentes.

Mantido atualizado automaticamente​

A plataforma mantém o saldo de uma wallet atualizado por conta própria — um Settlement, Payout, ou Withdrawal confirmando sob Self-Custody dispara uma atualização orientada a evento para o endereço afetado, além de uma varredura periódica de reconciliação em background. Um cliente não precisa fazer polling agressivo para ter correção.

Um cliente PODE observar de forma independente uma chain real por conta própria (só em Production — não há chain independente para consultar no Sandbox) como um sinal barato e opcional para decidir quando chamar o endpoint de refresh mais cedo. Essa observação é sempre apenas uma dica: a plataforma sempre reverifica por conta própria e nunca aceita um saldo relatado pelo cliente como autoritativo.

Send vs Pay​

Ambos movem fundos para fora de uma wallet, mas significam coisas estruturalmente diferentes para a plataforma:

  • Send é uma transferência direta wallet-a-wallet, iniciada pelo remetente. Nunca cria uma Transaction, PaymentIntent, ou Settlement — é um peer pagando outro peer, ponto final.
  • Pay é o cumprimento de um Payment Request existente (uma PaymentIntent vinculada a uma Transaction específica). Ele conduz o pipeline real Transaction → PaymentIntent → Settlement descrito em Transaction, Settlement, Split e Refund — Split, Fee, e a contabilidade do Ledger se aplicam do mesmo jeito que em qualquer outro Settlement.

Um pedido para pré-visualizar quanto um pagamento vai custar (taxas, valor recebido) nunca deve, por si só, criar nada real — nenhuma Transaction, nenhuma PaymentIntent. Só uma confirmação explícita deve avançar para o pipeline real do Pay.

Receive​

Receber não é tanto uma capacidade distinta quanto duas coisas diferentes que uma Account pode fazer:

  • Aceitar um Send direto — nada para configurar com antecedência; qualquer endereço self-custody registrado pode receber uma transferência.
  • Emitir um Payment Request — criar uma PaymentIntent com antecedência (um valor, uma descrição opcional, uma expiração) para que um pagador possa cumpri-la via Pay. O pagador nunca precisa de um relacionamento de conta com quem solicitou, além da própria Transaction compartilhada que o pedido representa.

Rotas​