Um float que fica líquido: uma proposta sobre a carteira.
Esta página é uma proposta conceitual, não um recurso do produto. O que existe: a carteira guarda um saldo por moeda, o codespar_wallet lê o saldo e o extrato, e a carteira é abastecida por Pix (uma cobrança Pix dinâmica para BRL; um Pix que a UnblockPay converte para USDC). O que não existe: um piso que a plataforma vigia, ou mover saldo entre BRL e USDC. Aqui, isso é política do seu agente.
Abaixo do seu piso, o agente pede abastecimento.
Um exemplo com dados de demonstração: o agente lê os saldos da carteira, vê o BRL abaixo do piso que a sua política define e gera um Pix dinâmico para a diferença. Quem controla a fonte de recursos paga. Nada se move entre BRL e USDC.
- O saldo por moeda vem do codespar_wallet
- O piso é a sua política, não uma configuração da plataforma
- Abastecer BRL é um Pix dinâmico que alguém paga
- Nada se move entre BRL e USDC: isso não é oferecido
A conversa é a parte fácil.
Um float de pagamentos ou fica parado ou seca. Alguém acompanha os saldos à mão e decide quando abastecer.
Abrir o portal do banco para ver cada saldo
O agente lê o saldo por moeda com o codespar_wallet
Perceber o saldo baixo depois que um pagamento falha
O seu agente compara o saldo com o piso que você define
Pedir uma transferência ao financeiro e esperar
O agente gera um Pix dinâmico para abastecer a carteira; a fonte de recursos paga
Perder o controle do que entrou e saiu
O extrato lista os lançamentos da carteira (action=statement)
Uma proposta, sobre as partes que existem.
O agente lê o saldo por moeda e o extrato da carteira com o codespar_wallet. Quando o BRL cai abaixo do piso que a sua política define, ele gera um Pix dinâmico para abastecer a carteira, e quem controla a fonte de recursos paga. O saldo em USDC é abastecido por um Pix que a UnblockPay converte. Manter o piso e escolher entre moedas continuam no código do seu agente: a CodeSpar não vigia um piso nem move saldo entre BRL e USDC.
codespar_walletSaldo por moeda
codespar_walletSaldo contra o seu piso
codespar_walletUm Pix dinâmico para a diferença
codespar_walletA fonte de recursos paga o Pix
codespar_walletO extrato mostra o crédito
codespar_walletO codespar_wallet lê o saldo por moeda (action=balance) e os lançamentos (action=statement), e gera um Pix copia-e-cola dinâmico para abastecer a carteira (action=receive, dynamic=true). O saldo em USDC é abastecido por POST /v1/consumers/{consumerId}/fund: o pagador paga um Pix e a UnblockPay o converte em USDC para a carteira do consumidor. O piso, a decisão de abastecer e qualquer escolha entre moedas são política do seu agente; a plataforma não mantém um piso nem move saldo entre moedas.
O código, e o que ele pressupõe.
// Prerequisites: CODESPAR_API_KEY set to a test key (csk_test_…) and a consumer // (user_0000) with a wallet. The floor is your policy: CodeSpar does not watch // a floor and does not move balance between BRL and USDC. import { CodeSpar } from "@codespar/sdk"; const session = await new CodeSpar().create("user_0000", { preset: "brazilian" }); const FLOOR_BRL_MINOR = 500_000; // R$ 5,000.00, your policy const read = await session.execute("codespar_wallet", { action: "balance", consumer_id: "user_0000" }); const { balances } = read.data as { balances: { currency: string; balance_minor: number | string }[] }; const brl = Number(balances.find((b) => b.currency === "BRL")?.balance_minor ?? 0); if (brl < FLOOR_BRL_MINOR) { // a dynamic Pix for the gap; whoever holds the funding source pays it const pix = await session.execute("codespar_wallet", { action: "receive", consumer_id: "user_0000", amount: FLOOR_BRL_MINOR - brl, dynamic: true, description: "Wallet top-up", }); console.log(pix.data); // the copia-e-cola to pay }
Exemplo com o SDK publicado (@codespar/sdk 0.16.11). Os pré-requisitos estão nos comentários. Compilar não prova a integração: rode primeiro em modo de teste.
codespar_walletLê o saldo por moeda e o extrato; gera um Pix dinâmico para abastecer a carteira.
POST /v1/consumers/{consumerId}/fundAbastece o saldo em USDC a partir de um Pix que a UnblockPay converte.
Comece com uma chave de teste.
Chaves de teste são gratuitas. Abra o sandbox, conecte os provedores que o seu projeto usa e veja quais ferramentas ele pode chamar antes de construir.