Docs6Policies

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

examples/policy.ts
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

FieldTypeMeaning
version1Marks the format. Always 1.
assetstringSymbol of the one asset the wallet may spend. Must match the wallet's asset.
maxPerPaymentstringLargest single payment, fee included. Decimal, display units.
dailyBudgetstringMost the wallet may spend in any 24 hours, fees included.
payees"any" or arrayWho may be paid. An array is an allow-list. An empty array allows no one.
payees[].addressbase58A payee's Solana address.
payees[].labelstring?A name for your receipts. Never sent anywhere.
payees[].maxPerPaymentstring?A tighter cap for this payee. Cannot exceed the policy cap.
expiresAtISO 8601 or nullAfter 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.

OrderCodeRefused when
01KILLEDThe owner stopped the wallet.
02EXPIREDThe clock is at or past expiresAt.
03ASSET_NOT_ALLOWEDThe payment is in a different token.
04PAYEE_NOT_ALLOWEDThe payee is not on the allow-list.
05OVER_PAYMENT_CAPThe total is above maxPerPayment.
06OVER_PAYEE_CAPThe total is above that payee's own cap.
07OVER_DAILY_BUDGETThe 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.

MistakeINVALID_POLICY message
maxPerPayment above dailyBudgetmaxPerPayment: is larger than dailyBudget, so it could never apply.
A number where a string belongsdailyBudget: expected a decimal string such as "0.50".
More decimals than USDC hasmaxPerPayment: "0.0000001" has more than 6 decimal places.
A misspelled keydailyBuget: unknown field.
An address that is not base58payees[0].address: not a Solana address.
A date that is not ISO 8601expiresAt: 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.

examples/owner.ts, persist
// 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.