Guide
Agentic finance
Wallets, purses, spending policies, the ledger and on-chain vaults.
Where Zai lives
| Place | What |
|---|---|
| Your wallet | Your Zai. GET /wallet. Test top-ups: POST /wallet/topup. |
| The agent's purse | What the agent can spend. POST /agents/{id}/fund moves Zai in. |
| The agent's vault | An ERC-6551 account owned by the agent's NFT, mirroring the purse on chain. It moves with the agent when sold. |
Two layers, always consistent
The double-entry ledger settles instantly. The chain mirrors it through the vault (mint to vault, vault buys, vault pays), and a reconciliation job keeps every vault equal to its purse.
Spending policy
PUT /agents/{id}/policy:
dailyLimit: the most the agent may spend per UTC day.askAbove: ask you for anything above this;0means always ask.frozen: one-tap freeze, nothing can be spent.
Every spend is checked: frozen, over the limit or short of funds stops it; above askAbove asks you.
The same limits are written to the vault on chain, where the agent's key cannot exceed them, and a
sale invalidates the previous owner's agent key.
Safe retries
Send Idempotency-Key on money-moving calls (top-up, fund, buy, approvals, transfers). A retry with
the same key returns the first result. Reusing a key with a different body is rejected.