Policies

Policies are automated rules that govern what actions are allowed through the Grimoire Platform. Every action plan validated through the API is checked against your active policies.

What Policies Do

Policies let you define guardrails that are enforced automatically:

Limit trade sizes — reject swaps above a threshold
Restrict venues — only allow specific protocols
Require approval — flag large moves for manual review
Cap slippage — reject trades with excessive slippage
Control risk — enforce health factor minimums for lending positions

Policies are checked during validation (POST /v1/validate) and as part of the run flow (POST /v1/run).

Policy Rules

A policy contains one or more rules. Each rule specifies a condition that is evaluated against the action plan.

Example rules:

Rule Code	Description	Example Params
`ALLOWED_CHAINS`	Whitelist of permitted chains	`{"chains": ["ethereum", "base"]}`
`ALLOWED_VENUES`	Whitelist of permitted venue adapters	`{"venues": ["uniswap_v3", "aave_v3"]}`
`ALLOWED_ACTIONS`	Whitelist of permitted action types	`{"actions": ["swap", "deposit"]}`
`ALLOWED_TOKENS`	Whitelist of permitted tokens	`{"tokens": ["USDC", "ETH"]}`
`MAX_ACTIONS`	Maximum number of actions per plan	`{"max": 5}`
`MAX_POSITION_SIZE`	Maximum value for any single action	`{"max": 50000}`
`MAX_LEVERAGE`	Maximum leverage ratio	`{"max": 3}`
`MAX_SLIPPAGE`	Maximum allowed slippage	`{"max": 0.01}`
`MAX_GAS`	Maximum gas cost	`{"max": 0.05}`
`MAX_PRICE_IMPACT`	Maximum price impact	`{"max": 0.02}`

Managing Policies

Create a Policy

Create Policy

curl -X POST https://api.grimoire.run/v1/partners/YOUR_PARTNER_ID/policies \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Trading Limits",
    "rules": [
      {
        "code": "MAX_POSITION_SIZE",
        "phase": "preview",
        "params": { "max": 50000 }
      },
      {
        "code": "MAX_SLIPPAGE",
        "phase": "preview",
        "params": { "max": 0.01 }
      },
      {
        "code": "ALLOWED_VENUES",
        "phase": "compile",
        "params": { "venues": ["uniswap_v3", "aave_v3", "morpho_blue"] }
      }
    ]
  }'

Update a Policy

Update Policy

curl -X PUT https://api.grimoire.run/v1/partners/YOUR_PARTNER_ID/policies/POLICY_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Trading Limits",
    "rules": [
      {
        "code": "MAX_POSITION_SIZE",
        "phase": "preview",
        "params": { "max": 100000 }
      }
    ]
  }'

Get a Policy

Get Policy

curl https://api.grimoire.run/v1/partners/YOUR_PARTNER_ID/policies/POLICY_ID \
  -H "x-api-key: YOUR_API_KEY"

List All Policies

List Policies

curl https://api.grimoire.run/v1/partners/YOUR_PARTNER_ID/policies \
  -H "x-api-key: YOUR_API_KEY"

Endpoints

Method	Endpoint	Description
`POST`	`/v1/partners/{partnerId}/policies`	Create a new policy
`PUT`	`/v1/partners/{partnerId}/policies/{policyId}`	Update a policy
`GET`	`/v1/partners/{partnerId}/policies/{policyId}`	Get a specific policy
`GET`	`/v1/partners/{partnerId}/policies`	List all policies

How Policy Evaluation Works

When an action plan is validated:

All active policies for your partner account are loaded
Each rule is evaluated against the action plan
Results are returned per-rule with pass/fail and details

Policy Results

{
  "policy_result": {
    "version": "1",
    "passed_rules": ["ALLOWED_VENUES", "MAX_SLIPPAGE"],
    "failed_rules": ["MAX_POSITION_SIZE"]
  }
}