Section 6
Policies
A small JSON file written by the owner. The wallet checks it before every payment, and a refusal names the rule.
6.1The file
export const policy: Policy = {
version: 1,
asset: "USDC",
maxPerPayment: "0.05",
dailyBudget: "2.00",
payees: [
{
address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
label: "search api",
},
{
address: "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T",
label: "price feed",
maxPerPayment: "0.002",
},
],
expiresAt: "2027-01-31T00:00:00Z",
};The object is plain JSON. Keep it in a file next to the agent or in your configuration store. The figure on the front page runs one task against a policy like this.
6.2Fields
| Field | Type | Meaning |
|---|---|---|
version | 1 | Marks the format. Always 1. |
asset | string | Symbol of the one asset the wallet may spend. Must match the wallet's asset. |
maxPerPayment | string | Largest single payment, fee included. Decimal, display units. |
dailyBudget | string | Most the wallet may spend in any 24 hours, fees included. |
payees | "any" or array | Who may be paid. An array is an allow-list. An empty array allows no one. |
payees[].address | base58 | A payee's Solana address. |
payees[].label | string? | A name for your receipts. Never sent anywhere. |
payees[].maxPerPayment | string? | A tighter cap for this payee. Cannot exceed the policy cap. |
expiresAt | ISO 8601 or null | After this instant every payment is refused. |
6.3Evaluation order
Rules are checked in this order and the first that fails decides. The order is part of the interface: a payment that breaks two rules always reports the same one.
| Order | Code | Refused when |
|---|---|---|
| 01 | KILLED | The owner stopped the wallet. |
| 02 | EXPIRED | The clock is at or past expiresAt. |
| 03 | ASSET_NOT_ALLOWED | The payment is in a different token. |
| 04 | PAYEE_NOT_ALLOWED | The payee is not on the allow-list. |
| 05 | OVER_PAYMENT_CAP | The total is above maxPerPayment. |
| 06 | OVER_PAYEE_CAP | The total is above that payee's own cap. |
| 07 | OVER_DAILY_BUDGET | The total does not fit in what is left of the budget. |
The total is the payment plus the protocol fee. A policy that allows 0.05 per payment allows a price of 0.05 only when the fee is zero.
6.4The 24-hour budget
The budget is a rolling window, not a calendar day. At any moment the wallet adds up what it sent in the previous 86,400 seconds, and a payment must fit in the remainder. Spending falls out of the window exactly 24 hours after it happened, so there is no midnight at which an agent gets a fresh allowance all at once.
A payment in flight holds its total against the budget from the moment the policy allows it. Two payments started at the same instant cannot both pass on the last of the budget. If the transfer fails, the hold is released. If it settles, the hold becomes a debit.
6.5Validation
compilePolicy rejects a file it does not fully understand. Unknown keys are errors, because a misspelled limit that is silently ignored is a missing limit. These messages were produced by running each mistake through the validator while this page was built.
| Mistake | INVALID_POLICY message |
|---|---|
| maxPerPayment above dailyBudget | maxPerPayment: is larger than dailyBudget, so it could never apply. |
| A number where a string belongs | dailyBudget: expected a decimal string such as "0.50". |
| More decimals than USDC has | maxPerPayment: "0.0000001" has more than 6 decimal places. |
| A misspelled key | dailyBuget: unknown field. |
| An address that is not base58 | payees[0].address: not a Solana address. |
| A date that is not ISO 8601 | expiresAt: not an ISO 8601 instant. |
6.6Kill switch
wallet.kill() sets a flag that is checked before every other rule. From that call on, every payment is refused with KILLED, including payments by the MCP tools. A transfer that was already submitted to the network is not recalled. wallet.revive() clears the flag.
Killing the wallet does not move the balance. To take the money away from an agent, withdraw it. A withdrawal is public and shows its amount.
6.7Persistence
The spend ledger and the kill flag live in the wallet process. Save wallet.snapshot() and pass it back as state, or a restart forgets what was spent and what was stopped. The MCP server does this for you when DOEI_STATE is set.
// The spend ledger lives in the wallet process.
// Save it, or a restart resets the budget.
const state = wallet.snapshot();
// later: createAgentWallet({ ...options, state })6.8Where it is enforced
So the policy protects you from the agent, and only if the agent cannot reach the key. Run the wallet in its own process, give the model the MCP tools and nothing else, and keep the keyfile out of any directory the agent can read. As a second line, keep the private balance small: the balance is a limit the chain does enforce.