Configuration — Intercept Docs

An Intercept integration is configured by two things: a policy file, intercept.policy.json, that defines what an agent is allowed to do, and a small set of environment variables that tell the SDK how to connect. Both are illustrative. The defaults below are proposed values and may change.

JSON

{
  "version": "0.1",
  "agent": "agent_7f3c",
  "mode": "enforced",
  "risk": {
    "maxTransactionUsd": 25000,
    "dailySpendLimitUsd": 100000,
    "maxPositionPct": 0.15,
    "maxLeverage": 3,
    "maxDrawdownPct": 0.12,
    "drawdownWindow": "7d",
    "maxSlippageBps": 50,
    "minPoolLiquidityUsd": 250000
  },
  "security": {
    "allowedProtocols": ["jupiter", "drift", "kamino"],
    "blockedAddresses": [],
    "simulation": "required",
    "requireApprovalAboveUsd": 10000,
    "tokenApprovals": "deny_unlimited"
  },
  "circuitBreakers": [
    { "trigger": "drawdown_pct", "threshold": 0.08, "action": "reduce_only" },
    { "trigger": "consecutive_blocks", "threshold": 5, "action": "pause" }
  ],
  "emergency": {
    "paused": false,
    "pauseOn": ["drawdown_breach", "critical_threat"],
    "guardians": ["<guardian-pubkey>"]
  }
}

Protocol names in allowedProtocols are illustrative allowlist entries, not integrations or partners.

Policy fields

A field marked "required" has no default. An omitted optional field uses its default. A default of "none" means the check is disabled when the field is absent.

Top level

Field	Type	Default	Description
`version`	string	required	Policy schema version. Currently `"0.1"`.
`agent`	string	required	Agent ID the policy applies to.
`mode`	`"advisory"` \| `"enforced"`	`"advisory"`	Integration mode. Blocking only works if the integration is enforced. See Integration Overview.

risk

Field	Type	Default	Description
`maxTransactionUsd`	number	none	Maximum USD value of a single transaction. Reason: `RISK_MAX_TX_SIZE`.
`dailySpendLimitUsd`	number	none	Maximum outflow per rolling 24 hours. Reason: `RISK_DAILY_LIMIT`.
`maxPositionPct`	number (0–1)	none	Maximum share of portfolio value in one asset after execution. Reason: `RISK_POSITION_SIZE`.
`maxLeverage`	number (>= 1)	`1`	Maximum resulting account leverage. Reason: `RISK_MAX_LEVERAGE`.
`maxDrawdownPct`	number (0–1)	none	Maximum peak-to-trough loss within `drawdownWindow`. Reason: `RISK_DRAWDOWN`.
`drawdownWindow`	duration string	`"7d"`	Window for drawdown, e.g. `"24h"`, `"7d"`, `"30d"`.
`maxSlippageBps`	integer	`100`	Maximum slippage from expected price, in basis points. Reason: `RISK_SLIPPAGE`.
`minPoolLiquidityUsd`	number	none	Minimum liquidity of any pool the transaction routes through. Reason: `RISK_LIQUIDITY`.

USD values are designed to be derived from oracle data sources, such as Pyth or Switchboard, used here as examples.

security

Field	Type	Default	Description
`allowedProtocols`	string[]	`[]`	Protocol identifiers the agent may interact with. An empty list blocks all non-system programs. Reason: `SEC_PROTOCOL_NOT_ALLOWED`.
`blockedAddresses`	string[]	`[]`	Base58 addresses or program IDs that are always blocked. Reason: `SEC_BLOCKED_ADDRESS`.
`simulation`	`"required"` \| `"preferred"`	`"required"`	`required` blocks if simulation fails or is unavailable (`SEC_SIMULATION_FAILED`).
`requireApprovalAboveUsd`	number	none	Transactions above this value return `requires_approval`.
`tokenApprovals`	`"deny_unlimited"` \| `"allow"`	`"deny_unlimited"`	Blocks unbounded token delegate approvals. Reason: `SEC_UNLIMITED_APPROVAL`.

circuitBreakers[]

Field	Type	Default	Description
`trigger`	`"drawdown_pct"` \| `"consecutive_blocks"`	required	Condition being watched.
`threshold`	number	required	Fraction for `drawdown_pct`; count for `consecutive_blocks`.
`action`	`"reduce_only"` \| `"pause"`	required	`reduce_only` approves only exposure-reducing transactions; `pause` sets the agent to paused.

A triggered breaker emits a circuit_breaker.triggered webhook.

emergency

Field	Type	Default	Description
`paused`	boolean	`false`	When `true`, every evaluation returns `blocked` with `SYS_PAUSED`.
`pauseOn`	string[]	`[]`	Events that pause automatically: `drawdown_breach`, `critical_threat`.
`guardians`	string[]	`[]`	Public keys allowed to pause, set reduce-only and trigger recovery. Resuming is owner-only. Required to be non-empty in enforced mode.

Environment variables

Variable	Required	Description
`INTERCEPT_API_KEY`	Yes	Secret API key. Never commit it, embed it in client code or place it in a directory that is deployed as static files.
`INTERCEPT_CLUSTER`	No	`mainnet-beta` (default) or `devnet`.
`INTERCEPT_POLICY_PATH`	No	Path to the policy file when `policy` is not passed to the constructor. Defaults to `./intercept.policy.json`.

Constructor options take precedence over environment variables.

Validation rules

intercept.policies.validate(policy) and PUT /v0/policies/{agentId}?dryRun=true are designed to enforce these rules. A policy that fails returns SYS_POLICY_INVALID with a list of { path, message } errors and is never published.

version must be a supported schema version; agent must match the agent the key is scoped to.
Percentages (maxPositionPct, maxDrawdownPct, drawdown_pct thresholds) must be greater than 0 and at most 1.
maxLeverage must be at least 1. USD limits must be positive.
maxSlippageBps must be an integer between 0 and 10000.
dailySpendLimitUsd, when set, must be greater than or equal to maxTransactionUsd.
A drawdown_pct circuit breaker threshold should be lower than maxDrawdownPct; otherwise the breaker can never fire before the limit. This is a warning, not an error.
blockedAddresses and guardians must be valid base58 public keys.
allowedProtocols and blockedAddresses must not reference the same program.
In enforced mode, guardians must contain at least one key and simulation must be required.
Unknown fields are rejected, so that a typo such as maxLeverge fails loudly instead of silently disabling a check.

If the active policy becomes unreadable at evaluation time, the engine returns blocked with SYS_POLICY_INVALID.