Policy Engine API

The client.policies namespace provides tools for building, validating, updating, and querying policies that govern agent behavior.

Building a Policy

import { PolicyBuilder } from '@brain-protocol/sdk';

const policy = new PolicyBuilder()
  .setSpendLimit('1000 USDC/day')
  .setAllowedAssets(['USDC', 'ETH'])
  .setAllowedContracts(['0xUniswapV3', '0xAaveV3'])
  .setTimeWindow('09:00', '21:00', 'UTC')
  .setApprovalThreshold('1-of-1')
  .build();

const policyHash = await client.policies.deploy(policy, account.address);

Updating a Policy

// Updates take effect after on-chain confirmation
await client.policies.update(agent.agentId, {
  spendLimit: '2000 USDC/day',
});

Simulate an Action Against a Policy

const simulation = await client.policies.simulate(agent.agentId, {
  target: '0xUniswapV3',
  asset: 'USDC',
  amount: '300',
});

console.log(simulation.allowed); // true or false
console.log(simulation.reason);  // reason if blocked

Get Current Policy

const policy = await client.policies.get(agent.agentId);
console.log(policy);
// {
//   spendLimit: '1000 USDC/day',
//   allowedAssets: ['USDC', 'ETH'],
//   allowedContracts: ['0xUniswapV3'],
//   timeWindow: '09:00-21:00 UTC',
//   approvalThreshold: '1-of-1',
//   policyHash: '0x...'
// }

Check Remaining Budget

const budget = await client.policies.getBudgetStatus(agent.agentId);
console.log(budget);
// {
//   dailyLimit: '1000 USDC',
//   spent: '213.50 USDC',
//   remaining: '786.50 USDC',
//   resetsAt: '2025-09-02T00:00:00Z'
// }

Policy Fields Reference

Field	Type	Description
spendLimit	string	e.g. "500 USDC/day", "10 ETH/week"
allowedAssets	string[]	Token symbols permitted for use
allowedContracts	string[]	Contract addresses the agent may call
blockedMerchants	string[]	Merchant addresses to reject in x402 flows
timeWindow	string	"HH:MM-HH:MM TZ" — active hours
approvalThreshold	string	e.g. "1-of-1", "2-of-3"

Policy updates require an on-chain transaction (setPolicy on the BrainAccount). Changes are not effective until the transaction is confirmed.