Skip to main content
Policy gates are declarative rules enforced by the OWS signing layer before any transaction is signed. They control what a signed transaction is allowed to do — which chains, what expiry window, and (when available) spending limits. Policies work alongside band filtering:
  • Bands control which tools the agent can see (MCP layer)
  • Policies control what the visible tools can do (OWS layer)
An agent with MCP_BANDS=full but a restrictive policy can see all tools but will be denied by the policy when trying to sign for an unauthorized chain.

​
How Policies Work

  1. You create a policy with constraints (allowed chains, expiry)
  2. You create an agent API key bound to that policy
  3. When the agent requests a signature, OWS evaluates the policy before touching any key material
  4. If the policy denies the request, signing fails with a flow error containing the specific rule that triggered and a requiredAction to fix it
All policies bound to an agent key are evaluated with AND semantics — the first denial short-circuits. Policies are stored locally in the OWS vault and cannot be overridden by the MCP server or LLM.

​
Available Constraints

ConstraintWhat It ControlsStatus
allowedChainsList of CAIP-2 chain IDs the agent can sign for (e.g., ["eip155:1"] for Ethereum only)Available
expiresAtISO 8601 timestamp after which the agent key stops workingAvailable
maxPerTxNativeMaximum native token value per transactionPlanned
dailyNativeBudgetDaily cumulative spend cap in native tokenPlanned

​
Not yet in MCP

Upstream OWS supports additional declarative policy rules that WalletSuite MCP does not currently surface through the create_custom_policy tool schema. Notably, allowed_typed_data_contracts — which scopes EIP-712 signing to a contract allowlist — is implementable at the OWS layer but is not wired through MCP tool arguments today. Use a direct OWS configuration if you need it before MCP exposes it.

​
Creating a Policy

Use the create_custom_policy tool in owner mode (requires MCP_BANDS including sign): 
Create a policy called "eth-only-30d" that allows signing on Ethereum only, expiring in 30 days.
The agent calls: 
{
  "name": "create_custom_policy",
  "arguments": {
    "policyName": "eth-only-30d",
    "allowedChains": ["eip155:1"],
    "expiresAt": "2026-05-16T00:00:00Z"
  }
}
Returns a policyId — a server-generated UUID — alongside the policyName you supplied. Capture the policyId from the response; you bind agent keys to the UUID, not to the name. 
// Example create_custom_policy response
{
  "policyId": "2f6d3a1e-94c7-4c8e-9c5a-7b0e1f2a3b4c",
  "policyName": "eth-only-30d",
  "summary": { "allowedChains": ["eip155:1"], "expiresAt": "2026-05-16T00:00:00Z" }
}

​
Binding a Policy to an Agent Key

Use create_agent_api_key with the policyId UUID returned above: 
Create an agent API key for wallet "treasury" bound to policy 2f6d3a1e-94c7-4c8e-9c5a-7b0e1f2a3b4c.
The agent calls: 
{
  "name": "create_agent_api_key",
  "arguments": {
    "walletName": "treasury",
    "policyId": "2f6d3a1e-94c7-4c8e-9c5a-7b0e1f2a3b4c"
  }
}
policyId is the UUID from create_custom_policy’s response — not the human-readable policyName. Passing the name raises OWS_POLICY_NOT_FOUND.
The token is written to a local file (mode 0600) — never returned in chat. Restart the MCP server in agent mode with OWS_AGENT_TOKEN sourced from that file.

​
What Happens When a Policy Denies

The agent receives a structured error: 
{
  "category": "flow",
  "code": "OWS_POLICY_DENIED",
  "message": "Policy 'eth-only-30d' denied signing for chain tron:mainnet",
  "requiredAction": "This agent key is restricted to chains: eip155:1. Use a different wallet or modify the policy."
}
The requiredAction tells the agent exactly what to do. See Structured Errors for the full error taxonomy.

​
Owner Override

The owner key (OWS owner mode) can always override agent policies. This ensures you always retain full control — WalletSuite cannot unilaterally freeze funds or block signing. If an agent is denied by a policy, the owner can:
  • Modify the policy to allow the operation
  • Delete the policy
  • Sign directly in owner mode (bypasses all policies)

​
Two Layers of Control

LayerWhat It ControlsWhere It Runs
Band FilteringWhich tools exist in the MCP schemaMCP Server (startup)
Policy GatesWhat signed transactions can doOWS Vault (per-request)
A complete security setup uses both:
  1. Set MCP_BANDS to the minimum required level
  2. Create a policy with chain restrictions and expiry
  3. Create an agent key bound to that policy
  4. The agent can only see the tools it needs AND can only sign what the policy allows

​
Practical Example

Scenario: You want an agent that can prepare and sign Ethereum transfers only, with a 7-day authorization window. Setup:
  1. Create a policy:
    • allowedChains: ["eip155:1"]
    • expiresAt: 7 days from now
  2. Create an agent key bound to that policy
  3. Configure the MCP server:
    • MCP_BANDS=full
    • OWS_ENABLED=true
    • OWS_AUTH_MODE=agent
    • OWS_AGENT_TOKEN from the token file
Result: The agent can prepare and sign Ethereum transactions. If it tries to sign for Tron, the policy denies it. After 7 days, the agent key expires and all signing stops until a new key is created. See OWS Local Signing for the full setup guide.