Wallet

A API Inyo Wallet é um ledger de partidas dobradas para guardar e movimentar dinheiro entre carteiras nomeadas. Ela viabiliza casos de uso B2B como dividir transferências (wires) recebidas entre sub-carteiras de fornecedores, retenções de pré-autorização no estilo cartão com captura parcial e rastreabilidade de fundos em nível de auditoria.

Conceitos Fundamentais

Carteiras

Uma carteira é uma conta nomeada que pertence a você. Cada carteira mantém saldos em um ou mais ativos (USD, USDC, EUR, MXN). Os saldos são calculados a partir do ledger — nunca gravados diretamente.

Toda carteira pertence a uma company ou a um user, identificado por um owner_ref que você fornece (seu próprio ID para aquela entidade).

Ledger de Partidas Dobradas

Toda operação grava um journal com duas ou mais entries. Cada entry é um débito ou um crédito, e a soma dos débitos é igual à soma dos créditos, por ativo, em todo journal. Isso torna impossível que dinheiro apareça ou desapareça — um bug só pode, no máximo, desviá-lo de rota.

Você não grava entries diretamente. Você chama os endpoints de operação (depósito, retenção (hold), captura, cancelamento (void), reembolso, transferência, conversão de FX) e o ledger grava as entries corretas atomicamente.

Saldos: posted, held, available

Todo saldo de carteira tem três números por ativo:

Campo	Significado
`posted`	Soma cumulativa com sinal de todas as entries — o que a carteira efetivamente recebeu menos o que enviou
`held`	Soma das pré-autorizações abertas — dinheiro reservado, mas ainda não gasto
`available`	`posted − held` — saldo disponível para gasto

Quando você pré-autoriza, held sobe (e posted cai — a pré-autorização move os fundos para uma sub-conta de retenção). Quando você captura, os fundos vão da retenção para o destino. Quando você cancela (void), held volta a cair e os fundos retornam.

Origens e Linhagem

Cada dólar no sistema remonta a uma origem (source) — um wire, débito ACH, cobrança em cartão ou depósito em stablecoin. Quando você divide um wire de $10 mil entre 10 carteiras, cada entry de crédito carrega um lineageRef apontando para a origem.

Mais tarde, quando uma carteira gasta dinheiro, as entries de débito também carregam lineageRef — apontando para a(s) origem(ns) de onde o dinheiro veio originalmente. O ledger usa consumo FIFO: o dinheiro que entrou primeiro é gasto primeiro.

Isso dá respostas em nível de auditoria para "de onde veio este dólar específico?" — exigido para AML, lotes fiscais em stablecoins e atribuição de chargebacks.

Insert-Only

Journals e entries nunca são atualizados ou excluídos — a imutabilidade é garantida no nível do banco de dados. Uma "reversão" é um journal compensatório que referencia o original via parentJournalId, de forma que as cadeias de operações permanecem rastreáveis: reembolso → captura → pré-autorização.

Autenticação e Convenções

Todo endpoint fica sob /organizations/{tenant}/ no host da API de wallet (https://{FQDN}), autenticado com a API key do seu tenant no header X-API-KEY.
Todo POST exige um header Idempotency-Key — veja Idempotência.
Todos os valores são strings no JSON, decimais com até 8 casas. Nunca faça parse de valores como números de ponto flutuante — você perderá precisão.
Os campos id de carteiras, retenções (holds) e journals são UUIDs. Campos como accountId e journalId dentro das entries são identificadores numéricos internos — use os UUIDs nas chamadas de API.

Por Onde Começar

Guia de Integração — um cenário B2B real de ponta a ponta: depósito de wire dividido entre carteiras de fornecedores, pré-autorização, captura parcial, reembolso e cancelamento (void)
Referência da API — todos os endpoints, códigos de erro e semântica de idempotência