A float that stays liquid: a proposal on top of the wallet.
This page is a conceptual proposal, not a product feature. What exists: the wallet keeps a balance per currency, codespar_wallet reads the balance and the statement, and the wallet is funded by Pix (a dynamic Pix charge for BRL; a Pix that UnblockPay converts for USDC). What does not exist: a floor the platform watches, or a move of balance between BRL and USDC. Here those are your agent's policy.
Below your floor, the agent asks for funding.
An example with demo data: the agent reads the wallet's balances, sees BRL below the floor your policy sets and mints a dynamic Pix for the gap. Whoever holds the funding source pays it. Nothing moves between BRL and USDC.
- The balance per currency comes from codespar_wallet
- The floor is your policy, not a platform setting
- Funding BRL is a dynamic Pix that someone pays
- No move between BRL and USDC: that is not offered
The conversation is the easy part.
A payout float either sits idle or runs dry. Someone watches the balances by hand and decides when to fund them.
Open the bank portal to check each balance
The agent reads the balance per currency with codespar_wallet
Notice a low balance after a payout fails
Your agent compares the balance with the floor you set
Ask finance for a transfer and wait
The agent mints a dynamic Pix to fund the wallet; the funding source pays it
Lose track of what came in and went out
The statement lists the wallet's ledger entries (action=statement)
A proposal, on the parts that exist.
The agent reads the wallet's balance per currency and its statement with codespar_wallet. When BRL drops below the floor your policy sets, it mints a dynamic Pix to fund the wallet, and whoever holds the funding source pays it. The USDC balance is funded from a Pix that UnblockPay converts. Keeping the floor and choosing between currencies stay in your agent's code: CodeSpar does not watch a floor or move balance between BRL and USDC.
codespar_walletBalance per currency
codespar_walletBalance against your floor
codespar_walletA dynamic Pix for the gap
codespar_walletThe funding source pays the Pix
codespar_walletThe statement shows the credit
codespar_walletcodespar_wallet reads the balance per currency (action=balance) and the ledger entries (action=statement), and mints a dynamic Pix copia-e-cola to fund the wallet (action=receive, dynamic=true). The USDC balance is funded through POST /v1/consumers/{consumerId}/fund: the payer pays a Pix and UnblockPay converts it into USDC for the consumer's wallet. The floor, the decision to fund and any choice between currencies are your agent's policy; the platform does not hold a floor or move balance between currencies.
The code, and what it assumes.
// 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 }
Example with the published SDK (@codespar/sdk 0.16.11). Its prerequisites are in the comments. Compiling does not prove the integration: run it in test mode first.
codespar_walletReads the balance per currency and the statement; mints a dynamic Pix to fund the wallet.
POST /v1/consumers/{consumerId}/fundFunds the USDC balance from a Pix that UnblockPay converts.
Start with a test key.
Test keys are free. Open the sandbox, connect the providers your project uses and see which tools it can call before you build.