AEP Cookbook

Single reference for AEP deployment, policies, integration, and operations. For detailed guidance, see the skills in skills/.

Quick Start

npm-first (recommended): see Getting started — Quick start — npx @economicagents/cli@0.2.0 deploy against the published factory; no Foundry clone.

From source (custom factory):

1. Deploy factory: cd contracts && forge script script/Deploy.s.sol --rpc-url base_sepolia --broadcast (requires .env with PRIVATE_KEY, BASE_SEPOLIA_RPC) → note factory address
2. Deploy account: npx @economicagents/cli@0.2.0 deploy --factory 0xFactoryAddress (owner derived from PRIVATE_KEY) or --owner 0x...
3. Set policies: npx @economicagents/cli@0.2.0 policy-set -m <module> --max-per-tx 1000000 --max-daily 5000000 --max-weekly 20000000 (get module via aep modules)
4. Optional — relationships: cd contracts && forge script script/DeployRelationships.s.sol --rpc-url base_sepolia --broadcast → add factory addresses to ~/.aep/config.json
5. Optional — intent resolution (self-host): cd packages/indexer && pnpm run build && npx aep-index sync (index at ~/.aep/index/); cd packages/api && pnpm run build && node dist/index.js (POST /resolve on port 3847). Hosted reference at https://api.economicagents.org is offline (HTTP 521) as of August 2026.

Full config (~/.aep/config.json): factoryAddress, rpcUrl, account (from deploy); for counterparty: identityRegistryAddress, reputationRegistryAddress; for execute: bundlerRpcUrl; for resolve: indexPath; optional indexDatabaseUrl — PostgreSQL URL for hybrid provider search (overridden by env AEP_INDEX_DATABASE_URL when set); for relationships: creditFacilityFactoryAddress, escrowFactoryAddress, revenueSplitterFactoryAddress, slaFactoryAddress; for monitor: monitor.accounts, monitor.facilities, monitor.slas, monitor.webhookUrl, monitor.pollIntervalMs; for fleet: fleets.

Provider index (Postgres optional): With AEP_INDEX_DATABASE_URL or indexDatabaseUrl, run aep-index migrate once, then sync and embed. Vector hybrid search uses OpenAI (OPENAI_API_KEY, optional AEP_EMBEDDING_MODEL). Without a DB URL, the index stays in ~/.aep/index/ (providers.json + optional SQLite search.db). Optional namespace: AEP_INDEX_DATASET_ID.

Quick Reference

Policy Modules

BudgetPolicy

Skills: aep-budget, aep-rate-limit

CounterpartyPolicy

• Default: All allowed except block list
• Address allow list: Only allowlisted addresses
• Agent allow list: Only wallets of allowed ERC-8004 agent IDs
• Global min-reputation: Only verified agents with reputation >= min

Skill: aep-counterparty

RateLimitPolicy

aep rate-limit set -m <module> --max-tx <n> --window-seconds <s> — set max transactions per window (owner only). Example: aep rate-limit set -m 0x... --max-tx 10 --window-seconds 3600 (10 tx/hour).

Skill: aep-rate-limit

Deployment

Full testnet deployment: See Deployment guide for deploy-base-sepolia.sh, deployed addresses, mainnet preflight, and post-deploy services.

Base Sepolia Addresses

Skill: aep-deploy

Integration

MCP Config

{
  "mcpServers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@economicagents/mcp@0.2.0"]
    }
  }
}

See MCP reference for global install and monorepo paths.

Tools: get_balance, get_policy_state, set_budget_caps, resolve_intent, get_analytics, get_credit_score, get_recommendations, fleet_summary, fleet_accounts, fleet_alerts, credit_state, escrow_state, splitter_state, sla_state.

OpenClaw Skills

cp -r skills/aep-budget skills/aep-counterparty skills/aep-x402 skills/aep-mpp skills/aep-rate-limit skills/aep-relationships ~/.openclaw/skills/

Or symlink: ln -s /path/to/AEP/skills/aep-budget ~/.openclaw/skills/aep-budget (and similarly for aep-counterparty, aep-x402, aep-mpp, aep-rate-limit, aep-relationships)

Skill: aep-integration

Economic Relationships

MCP tools: credit_state, escrow_state, splitter_state, sla_state.

Skill: aep-relationships

Monetization

• Treasury: treasuryAddress in ~/.aep/config.json or AEP_TREASURY_ADDRESS env
• API paywall: Set AEP_TREASURY_ADDRESS (or treasuryAddress in config) and AEP_RESOLVE_PRICE to gate POST /resolve via x402
• Relationship fees: --origination-fee (credit), --setup-fee (escrow, SLA). Use 0 for no fee.
• Fee-free mode: Deploy relationship factories with AEP_TREASURY_ADDRESS unset

Resolution paths and paywall

Skill: aep-monetization

Fleet Management

Manage multiple AEP accounts as a fleet. Config in ~/.aep/config.json:

{
  "fleets": {
    "fleet-1": {
      "accounts": ["0x...", "0x..."],
      "name": "Production Agents"
    }
  }
}

API: GET /fleet/:id/summary, /fleet/:id/accounts, /fleet/:id/alerts. When AEP_FLEET_API_KEY is set, these require Authorization: Bearer <key> or X-Fleet-API-Key.

On-Chain Event Monitor

Run aep monitor to watch for security-relevant events (Frozen, DefaultDeclared, BreachDeclared, PolicyRecordSpendFailed, UserOperationRevertReason). Alerts emitted as JSON lines to stdout; optional webhook POST.

Config (~/.aep/config.json):

{
  "monitor": {
    "accounts": ["0x..."],
    "facilities": ["0x..."],
    "slas": ["0x..."],
    "webhookUrl": "https://...",
    "pollIntervalMs": 12000
  }
}

If monitor is omitted, uses account for accounts. See INCIDENT-RESPONSE-PLAYBOOK.

Key Management

• Kill switch: aep freeze blocks all execution on suspected compromise.
• Operator/session keys: Deferred; owner-only implemented.

Skill: aep-key-management

Links

• Architecture — Contract hierarchy, validateUserOp flow
• Threat Model — Attack surfaces and mitigations
• Deployment — Sepolia, mainnet, validation, local services