Configuring Policies

Steward’s policy engine enforces rules on every agent action. This guide covers all policy types, common patterns, and best practices.

Policy Basics

Policies are JSON objects with this structure:

interface PolicyRule {
  id: string;        // Unique identifier
  type: string;      // Policy type (see below)
  enabled: boolean;  // Toggle without deleting
  config: object;    // Type-specific configuration
}

Set policies via SDK or API:

await steward.setPolicies("my-agent", [
  { id: "limit-1", type: "spending-limit", enabled: true, config: { ... } },
]);

curl -X PUT http://localhost:3200/agents/my-agent/policies \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '[{ "id": "limit-1", "type": "spending-limit", "enabled": true, "config": { ... } }]'

setPolicies / PUT /agents/:id/policies replaces all policies for the agent. Always include the complete policy set.

Policy Types Reference

spending-limit

Controls the maximum value an agent can transact.

Config Field	Type	Description
`maxPerTransaction`	string (wei)	Maximum value per single transaction
`maxPerDay`	string (wei)	Maximum cumulative value per 24h rolling window
`maxPerWeek`	string (wei)	Maximum cumulative value per 7-day rolling window

{
  "id": "spending-limit",
  "type": "spending-limit",
  "enabled": true,
  "config": {
    "maxPerTransaction": "100000000000000000",
    "maxPerDay": "1000000000000000000",
    "maxPerWeek": "5000000000000000000"
  }
}

Values are in wei (1 ETH = 10^18 wei). For Solana, values are in lamports (1 SOL = 10^9 lamports). Steward tracks cumulative spend per agent.

approved-addresses

Whitelist of addresses the agent can send transactions to.

Config Field	Type	Description
`addresses`	string[]	List of allowed destination addresses

{
  "id": "dex-whitelist",
  "type": "approved-addresses",
  "enabled": true,
  "config": {
    "addresses": [
      "0x1111111254EEB25477B68fb85Ed929f73A960582",
      "0xDef1C0ded9bec7F1a1670819833240f027b25EfF"
    ]
  }
}

auto-approve-threshold

Transactions below this value are auto-approved; above enters the approval queue.

Config Field	Type	Description
`maxValue`	string (wei)	Maximum auto-approve value

{
  "id": "auto-approve",
  "type": "auto-approve-threshold",
  "enabled": true,
  "config": {
    "maxValue": "50000000000000000"
  }
}

rate-limit

Controls transaction frequency.

Config Field	Type	Description
`maxPerMinute`	number	Max transactions per minute
`maxPerHour`	number	Max transactions per hour

{
  "id": "rate-limit",
  "type": "rate-limit",
  "enabled": true,
  "config": {
    "maxPerMinute": 10,
    "maxPerHour": 100
  }
}

time-window

Restricts when the agent can transact.

Config Field	Type	Description
`allowedHours.start`	number (0-23)	Start hour
`allowedHours.end`	number (0-23)	End hour
`timezone`	string	IANA timezone (e.g., “UTC”, “America/New_York”)

{
  "id": "trading-hours",
  "type": "time-window",
  "enabled": true,
  "config": {
    "allowedHours": { "start": 8, "end": 22 },
    "timezone": "UTC"
  }
}

allowed-chains

Restricts which blockchain networks the agent can use.

Config Field	Type	Description
`chainIds`	number[]	List of allowed chain IDs

{
  "id": "chains",
  "type": "allowed-chains",
  "enabled": true,
  "config": {
    "chainIds": [8453, 1, 42161]
  }
}

Common Patterns

Conservative Trading Agent

const conservativeTrader = [
  {
    id: "spending", type: "spending-limit", enabled: true,
    config: { maxPerTransaction: "50000000000000000", maxPerDay: "200000000000000000" },
  },
  {
    id: "addresses", type: "approved-addresses", enabled: true,
    config: { addresses: ["0x_UNISWAP_ROUTER"] },
  },
  {
    id: "auto", type: "auto-approve-threshold", enabled: true,
    config: { maxValue: "10000000000000000" },  // 0.01 ETH
  },
  {
    id: "rate", type: "rate-limit", enabled: true,
    config: { maxPerMinute: 2, maxPerHour: 20 },
  },
  {
    id: "chains", type: "allowed-chains", enabled: true,
    config: { chainIds: [8453] },  // Base only
  },
];

Read-Only Agent (No Signing)

// An agent with no policies cannot sign anything (default deny).
// Just create the agent and don't set policies:
const agent = await steward.createWallet("data-agent", "Data Agent");
// This agent can check balances and read chain data but cannot sign transactions.

High-Frequency Agent

const hftAgent = [
  {
    id: "spending", type: "spending-limit", enabled: true,
    config: { maxPerTransaction: "10000000000000000", maxPerDay: "5000000000000000000" },
  },
  {
    id: "rate", type: "rate-limit", enabled: true,
    config: { maxPerMinute: 60, maxPerHour: 1000 },
  },
  {
    id: "auto", type: "auto-approve-threshold", enabled: true,
    config: { maxValue: "10000000000000000" },  // Auto-approve all (same as max per tx)
  },
];

Reading Policies

const policies = await steward.getPolicies("my-agent");
console.log(policies);
// [
//   { id: "spending-limit", type: "spending-limit", enabled: true, config: { ... } },
//   { id: "approved-addrs", type: "approved-addresses", enabled: true, config: { ... } },
// ]

Disabling a Policy

To temporarily disable a policy without removing it, set enabled: false and resubmit the full set:

const policies = await steward.getPolicies("my-agent");
const updated = policies.map(p =>
  p.id === "time-window" ? { ...p, enabled: false } : p
);
await steward.setPolicies("my-agent", updated);

Policy Engine Concepts — How the engine works
Agent Setup — Creating agents with policies
Policies API — REST API reference

Get Started

Authentication

Concepts

Guides

Configuring Policies

Configuring Policies

Policy Basics

Policy Types Reference

spending-limit

approved-addresses

auto-approve-threshold

rate-limit

time-window

allowed-chains

Common Patterns

Reading Policies

Disabling a Policy

​Configuring Policies

​Policy Basics

​Policy Types Reference

​spending-limit

​approved-addresses

​auto-approve-threshold

​rate-limit

​time-window

​allowed-chains

​Common Patterns

​Reading Policies

​Disabling a Policy

​Related

Configuring Policies

Policy Basics

Policy Types Reference

spending-limit

approved-addresses

auto-approve-threshold

rate-limit

time-window

allowed-chains

Common Patterns

Reading Policies

Disabling a Policy

Related