Agent wallets (test mode)
An agent wallet lets an AI agent or an automated service send payouts without your merchant key. You fund it
with part of your balance, and give the agent a wallet key (ak_test_…) that can only:
- read its own wallet and balance, and
- create payouts within a fixed policy: one provider, a maximum per payout, and an allowlist of recipient phones.
The wallet’s funded balance is the agent’s total spending limit. It can never touch the rest of your balance.
| You (merchant key) | The agent (wallet key) |
|---|---|
POST /v1/agent-wallets — create with a policy (Idempotency-Key required) |
GET /v1/agent/wallet — its policy |
POST /v1/agent-wallets/{id}/fund · …/reclaim — move money in / take unreserved money back |
GET /v1/agent/balance |
POST /v1/agent-wallets/{id}/keys — issue a key (shown once) |
POST /v1/agent/payouts — pay out within the policy |
POST /v1/agent-wallets/{id}/disable — stop new agent writes |
GET /v1/agent/payouts · …/{id} |
GET /v1/agent-wallets/{id}/payouts · …/transfers · …/keys |
Safe retries: action_id
Section titled “Safe retries: action_id”Every agent payout carries an action_id from your application (e.g. the approved task’s id), not invented by the
model. Xaalis binds one payout to each action_id in the wallet, so a retried tool call returns the original payout
instead of paying twice. Reusing an action_id with a different amount or recipient returns 409.
Limits of this version
Section titled “Limits of this version”- Test mode only: live wallet keys (
ak_live_) are refused. - Disabling a wallet blocks new agent writes; payouts already accepted still finish.
The TypeScript SDK includes agent-wallet helpers (xaalis.agentWallets for you, an agent client with
payouts.createForAction for the agent), with an example tool handler.