AgentARC - Security Layer for AI Blockchain Agents

Advanced security and policy enforcement layer for AI blockchain agents with multi-stage validation, transaction simulation, and threat detection across DeFi + smart-contract attack surfaces, with LLM-based risk analysis.

🎯 Overview

AgentARC provides a comprehensive security framework for AI agents interacting with blockchain networks. It validates all transactions through multiple security stages before execution, reducing exposure to the broader DeFi threat surface and common smart-contract attack planes, including:

💰 Unauthorized fund transfers and unexpected value movement
🔓 Hidden or unlimited token approvals and allowance abuse
🧨 Malicious smart contracts and hostile call chains (e.g., delegatecall to untrusted code)
🎣 Token traps (honeypots, sell-blocks, malicious fee mechanics)
🌊 Liquidity and price-manipulation patterns (context-dependent)
🔄 Reentrancy-style execution hazards and unexpected re-calls
🧾 Suspicious fund-flow anomalies and downstream interactions that don’t match intent

These are representative examples, not an exhaustive list. AgentARC is designed to expand with more DeFi and smart-contract threat cases over time.

Key Features

✅ Multi-Stage Validation Pipeline: Intent → Policies → Simulation → Threat Detection
✅ Comprehensive Policy Engine: 7 policy types for granular control
✅ Transaction Simulation: Tenderly integration for detailed execution traces
✅ Threat Detection (Includes Honeypots): Automated checks for token traps and other suspicious patterns
✅ Optional LLM-based Security: AI-powered malicious activity detection and risk scoring
✅ Zero Agent Modifications: Pure wrapper pattern for AgentKit
✅ Asset Change Tracking: Monitor balance changes before execution

🚀 Quick Start

Installation

# Install from PyPI (recommended)
pip install agentarc

# Or install from source
git clone https://github.com/galaar-org/AgentARC.git
cd agentarc
pip install -e .

# Verify installation
agentarc --help

Setup Policy Configuration

# Generate default policy.yaml
agentarc setup

# Edit policy.yaml to configure your security rules
vim policy.yaml

Integration (3 Lines of Code)

from agentarc import PolicyWalletProvider, PolicyEngine
from coinbase_agentkit import AgentKit, CdpEvmWalletProvider

# Create base wallet
base_wallet = CdpEvmWalletProvider(config)

# Wrap with AgentARC (add security layer)
policy_engine = PolicyEngine(
    config_path="policy.yaml",
    web3_provider=base_wallet,
    chain_id=84532  # Base Sepolia
)
policy_wallet = PolicyWalletProvider(base_wallet, policy_engine)

# Use with AgentKit - no other changes needed!
agentkit = AgentKit(wallet_provider=policy_wallet, action_providers=[...])

That's it! All transactions now go through multi-stage security validation.

📚 Examples

1. Basic Usage (`examples/basic_usage.py`)

Simple demonstration with mock wallet provider.

cd examples
python basic_usage.py

Features:

Mock wallet implementation
Policy validation examples
Error handling demonstration

2. OnChain Agent (`examples/onchain-agent/`)

Production-ready Coinbase AgentKit chatbot with AgentARC.

cd examples/onchain-agent
cp .env.example .env
# Edit .env with your API keys

pip install -r requirements.txt
python chatbot.py

Features:

✅ Real CDP wallet integration
✅ Interactive chatbot interface
✅ Complete policy configuration

See: OnChain Agent README

3. Autonomous Portfolio Agent (`examples/autonomous-portfolio-agent/`)

AI agent that autonomously manages a crypto portfolio with honeypot protection.

cd examples/autonomous-portfolio-agent
cp .env.example .env
# Edit .env

pip install -r requirements.txt
python autonomous_agent.py

Features:

✅ Autonomous portfolio rebalancing
✅ Automatic honeypot detection
✅ Multi-layer security (policies + simulation + LLM)
✅ Zero manual blacklisting
✅ Demonstrates honeypot token blocking in action

See: Autonomous Portfolio Agent README and Honeypot Demo

🛡️ Security Pipeline

AgentARC validates every transaction through 4 stages:

Stage 1: Intent Judge

Parse transaction calldata
Identify function calls and parameters
Detect token transfers and approvals

Stage 2: Policy Validation

ETH value limits
Address allowlist/denylist
Per-asset spending limits
Gas limits
Function allowlists

Stage 3: Transaction Simulation

Tenderly simulation with full execution traces
Asset/balance change tracking
Gas estimation
Revert detection

Stage 3.5: Honeypot Detection

Simulate token BUY transaction
Automatically test SELL transaction
Block if tokens cannot be sold back
Zero manual blacklisting needed

Stage 4: LLM Security Analysis (Optional)

AI-powered malicious pattern detection
Hidden approval detection
Unusual fund flow analysis
Risk scoring and recommendations

📋 Policy Types

1. ETH Value Limit

Prevent large ETH transfers per transaction.

policies:
  - type: eth_value_limit
    max_value_wei: "1000000000000000000"  # 1 ETH
    enabled: true
    description: "Limit ETH transfers to 1 ETH per transaction"

2. Address Denylist

Block transactions to sanctioned or malicious addresses.

policies:
  - type: address_denylist
    denied_addresses:
      - "0xSanctionedAddress1..."
      - "0xMaliciousContract..."
    enabled: true
    description: "Block transactions to denied addresses"

3. Address Allowlist

Only allow transactions to pre-approved addresses (whitelist mode).

policies:
  - type: address_allowlist
    allowed_addresses:
      - "0xTrustedContract1..."
      - "0xTrustedContract2..."
    enabled: false  # Disabled by default
    description: "Only allow transactions to approved addresses"

4. Per-Asset Limits

Different spending limits for each token.

policies:
  - type: per_asset_limit
    asset_limits:
      - name: USDC
        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        max_amount: "10000000"  # 10 USDC
        decimals: 6
      - name: DAI
        address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"
        max_amount: "100000000000000000000"  # 100 DAI
        decimals: 18
    enabled: true
    description: "Per-asset spending limits"

5. Token Amount Limit

Limit token transfers across all ERC20 tokens.

policies:
  - type: token_amount_limit
    max_amount: "1000000000000000000000"  # 1000 tokens (18 decimals)
    enabled: false
    description: "Limit token transfers per transaction"

6. Gas Limit

Prevent expensive transactions.

policies:
  - type: gas_limit
    max_gas: 500000
    enabled: true
    description: "Limit gas to 500k per transaction"

7. Function Allowlist

Only allow specific function calls.

policies:
  - type: function_allowlist
    allowed_functions:
      - "eth_transfer"
      - "transfer"
      - "approve"
      - "swap"
    enabled: false
    description: "Only allow specific function calls"

🔬 Advanced Features

Tenderly Simulation

Enable advanced transaction simulation with full execution traces and asset tracking:

simulation:
  enabled: true
  fail_on_revert: true
  estimate_gas: true
  print_trace: false  # Set to true for detailed execution traces

Setup Tenderly (optional but recommended):

# Add to .env
TENDERLY_ACCESS_KEY=your_access_key
TENDERLY_ACCOUNT_SLUG=your_account
TENDERLY_PROJECT_SLUG=your_project

Capabilities:

✅ Full call trace analysis
✅ Asset/balance change tracking
✅ Event log decoding
✅ Gas prediction
✅ State modification tracking

Output Example:

Stage 3: Transaction Simulation
✅ Simulation successful (gas: 166300)
Asset changes:
  0x1234567... (erc20): +1000
  0xabcdef0... (erc20): -500

With print_trace: true:

Tenderly Simulation Details
----------------------------------------
Call Trace:
  [1] CALL: 0x1234567... → 0xabcdef0... (value: 0.5 ETH, gas: 50000)
    [1] DELEGATECALL: 0xabcdef0... → 0x9876543... (value: 0 ETH, gas: 30000)
    [2] CALL: 0xabcdef0... → 0x5555555... (value: 0 ETH, gas: 15000)

Asset/Balance Changes:
  0x1234567... (erc20): +1000
  0xabcdef0... (erc20): -500

Events Emitted:
  [1] Transfer
  [2] Approval
  [3] Swap

LLM-based Security Validation

Enable AI-powered malicious activity detection:

llm_validation:
  enabled: true
  provider: "openai"  # or "anthropic"
  model: "gpt-4o-mini"
  api_key: "${OPENAI_API_KEY}"  # or set in environment
  block_threshold: 0.70  # Block if confidence >= 70%
  warn_threshold: 0.40   # Warn if confidence >= 40%

What LLM Analyzes:

Hidden token approvals
Unusual fund flow patterns
Reentrancy attack patterns
Flash loan exploits
Sandwich/MEV attacks
Phishing attempts
Hidden fees and draining
Delegatecall to untrusted contracts
Honeypot token indicators

Example Output:

Stage 4: LLM-based Security Validation
⚠️  LLM warning: Detected unlimited token approval to unknown contract
Confidence: 65% | Risk: MEDIUM
Indicators: unlimited_approval, unknown_recipient

Honeypot Detection

Automatically detect scam tokens that can be bought but not sold:

How it works:

Transaction initiates a token purchase (BUY)
AgentARC simulates the BUY
Detects token receipt via Transfer events
Automatically simulates a SELL transaction
If SELL fails → HONEYPOT DETECTED → Block original BUY

Configuration:

# Honeypot detection is automatic when Tenderly simulation is enabled
simulation:
  enabled: true

Example Output:

Stage 3.5: Honeypot Detection
🔍 Token BUY detected. Checking if tokens can be sold back...
🧪 Testing sell for token 0xFe8365...
❌ Sell simulation FAILED/REVERTED
🛡️  ❌ BLOCKED: HONEYPOT DETECTED
   Token 0xFe8365... can be bought but cannot be sold

📊 Logging Levels

Control output verbosity in policy.yaml:

logging:
  level: info  # minimal, info, or debug

minimal: Only final decisions (ALLOWED/BLOCKED)
info: Full validation pipeline (recommended)
debug: Detailed debugging information including trace counts

🔧 Complete Configuration Example

policy.yaml:

version: "2.0"
apply_to: [all]

# Logging configuration
logging:
  level: info  # minimal, info, debug

# Policy rules
policies:
  - type: eth_value_limit
    max_value_wei: "1000000000000000000"  # 1 ETH
    enabled: true
    description: "Limit ETH transfers to 1 ETH per transaction"

  - type: address_denylist
    denied_addresses: []
    enabled: true
    description: "Block transactions to denied addresses"

  - type: address_allowlist
    allowed_addresses: []
    enabled: false
    description: "Only allow transactions to approved addresses"

  - type: per_asset_limit
    asset_limits:
      - name: USDC
        address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
        max_amount: "10000000"  # 10 USDC
        decimals: 6
      - name: DAI
        address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"
        max_amount: "100000000000000000000"  # 100 DAI
        decimals: 18
    enabled: true
    description: "Per-asset spending limits"

  - type: token_amount_limit
    max_amount: "1000000000000000000000"  # 1000 tokens
    enabled: false
    description: "Limit token transfers per transaction"

  - type: function_allowlist
    allowed_functions:
      - "eth_transfer"
      - "transfer"
      - "approve"
    enabled: false
    description: "Only allow specific function calls"

  - type: gas_limit
    max_gas: 500000
    enabled: true
    description: "Limit gas to 500k per transaction"

# Transaction simulation
simulation:
  enabled: true
  fail_on_revert: true
  estimate_gas: true
  print_trace: false  # Enable for detailed execution traces

# Calldata validation
calldata_validation:
  enabled: true
  strict_mode: false

# LLM-based validation (optional)
llm_validation:
  enabled: false
  provider: "openai"
  model: "gpt-4o-mini"
  api_key: "${OPENAI_API_KEY}"
  block_threshold: 0.70
  warn_threshold: 0.40

🧪 Testing

Run the test suite:

cd tests
python test_complete_system.py

Tests cover:

ETH value limits
Address denylist/allowlist
Per-asset limits
Gas limits
Calldata parsing
All logging levels

🏗️ Project Structure

agentarc/
├── agentarc/                 # Main package
│   ├── __init__.py
│   ├── __main__.py             # CLI entry point
│   ├── policy_engine.py        # Multi-stage validation pipeline
│   ├── wallet_wrapper.py       # Wallet provider wrapper
│   ├── calldata_parser.py      # ABI decoding
│   ├── simulator.py            # Basic transaction simulation
│   ├── logger.py               # Logging system
│   ├── llm_judge.py            # LLM-based security analysis
│   ├── simulators/
│   │   └── tenderly.py         # Tenderly integration
│   └── rules/                  # Policy validators
│       ├── __init__.py
│       └── validators.py
├── examples/                   # Usage examples
│   ├── basic_usage.py
│   ├── onchain-agent/          # Production chatbot
│   └── autonomous-portfolio-agent/  # Autonomous agent
├── tests/                      # Test suite
├── README.md
├── CHANGELOG.md
└── pyproject.toml

🤝 Compatibility

AgentARC works with all Coinbase AgentKit wallet providers:

✅ CDP EVM Wallet Provider
✅ CDP Smart Wallet Provider
✅ Ethereum Account Wallet Provider

Same 3-line integration pattern for all wallet types!

📖 Documentation

CHANGELOG.md - Version history and updates
CONTRIBUTING.md - Contributing guidelines
Examples - Sample implementations and demos

🔒 Security Best Practices

Start with restrictive policies — Use low limits and gradually increase
Enable simulation — Catch failures before sending transactions
Use Tenderly — Get detailed execution traces and asset changes
Enable optional LLM validation — Add AI-powered risk analysis where useful
Test on testnet — Validate policies on Base Sepolia before mainnet
Monitor logs — Review transaction validations regularly
Keep denylists updated — Add known malicious addresses
Enable threat checks — Automatically catch token traps (honeypots and related patterns) and expand coverage over time

🛠️ Environment Variables

# Coinbase CDP (required for real wallet)
CDP_API_KEY_NAME=your_cdp_key_name
CDP_API_KEY_PRIVATE_KEY=your_cdp_private_key

# LLM Provider (optional - for Stage 4)
OPENAI_API_KEY=your_openai_key
# OR
ANTHROPIC_API_KEY=your_anthropic_key

# Tenderly (optional - for advanced simulation)
TENDERLY_ACCESS_KEY=your_tenderly_key
TENDERLY_ACCOUNT_SLUG=your_account
TENDERLY_PROJECT_SLUG=your_project

🎯 Use Cases

🤖 AI Trading Bots - Prevent unauthorized trades and limit exposure
💼 Portfolio Managers - Enforce spending limits across assets
🏦 Treasury Management - Multi-signature with policy enforcement
🎮 GameFi Agents - Limit in-game asset transfers
🔐 Security Testing - Validate smart contract interactions
🛡️ Honeypot Protection - Automatically detect and block scam tokens

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

🆘 Support

Issues: GitHub Issues
Examples: examples/
Documentation: README.md

Protect your AI agents with AgentARC - Multi-layer security for blockchain interactions 🛡️

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
agentarc		agentarc
examples		examples
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml

License

galaar-org/AgentARC

Folders and files

Latest commit

History

Repository files navigation

AgentARC - Security Layer for AI Blockchain Agents

🎯 Overview

Key Features

🚀 Quick Start

Installation

Setup Policy Configuration

Integration (3 Lines of Code)

📚 Examples

1. Basic Usage (examples/basic_usage.py)

2. OnChain Agent (examples/onchain-agent/)

3. Autonomous Portfolio Agent (examples/autonomous-portfolio-agent/)

🛡️ Security Pipeline

Stage 1: Intent Judge

Stage 2: Policy Validation

Stage 3: Transaction Simulation

Stage 3.5: Honeypot Detection

Stage 4: LLM Security Analysis (Optional)

📋 Policy Types

1. ETH Value Limit

2. Address Denylist

3. Address Allowlist

4. Per-Asset Limits

5. Token Amount Limit

6. Gas Limit

7. Function Allowlist

🔬 Advanced Features

Tenderly Simulation

LLM-based Security Validation

Honeypot Detection

📊 Logging Levels

🔧 Complete Configuration Example

🧪 Testing

🏗️ Project Structure

🤝 Compatibility

📖 Documentation

🔒 Security Best Practices

🛠️ Environment Variables

🎯 Use Cases

📝 License

🤝 Contributing

🆘 Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 3

Uh oh!

Languages

1. Basic Usage (`examples/basic_usage.py`)

2. OnChain Agent (`examples/onchain-agent/`)

3. Autonomous Portfolio Agent (`examples/autonomous-portfolio-agent/`)

Packages