agent-security-gate-x402

The Sheriff of Agent Finance (agent-security-gate-x402) 🛡️🤠⚡

"The Sheriff of Agent Finance: Guarding Autonomous Wallets & Transactions in the Wild West of AI."

Before an autonomous AI agent moves a single dollar, the Sheriff inspects, attests, and secures the transaction.

Ultra-low latency (<10ms) deterministic security, prompt injection, secret key leak, dangerous AST code, and factual hallucination inspection micro-oracle, anchored to the A.GRID Universal Escrow Hub across Solana Mainnet (0.4s), Polygon, Base, and Arbitrum.

---

🖥️ Interactive Web Dashboard & Simulator (Live)

🌐 https://agent-security-gate-x402-212942243360.asia-northeast3.run.app/

Explore the full consumer and enterprise visual interface directly in your browser:

• 🛡️ Prompt Injection & Jailbreak Radar: Live testing against DAN prompts, system tag escapes, and adversarial suffixes.
• ⚡ Dangerous AST Code Analyzer: Sub-millisecond Python syntax parsing detecting os.system, subprocess, eval, exec, and malicious sockets.
• 🔍 Hallucination & NLI Fact-Checker: Contrast agent generation with ground truth context to surface fabricated numbers and unanchored claims.
• 📜 EIP-712 On-Chain Attestation & Calldata: Instant generation of v, r, s ABI calldata for EVM smart contracts.
• 📡 Real-Time Security Event Stream: Live WebSocket event feed of inspection audits.

---

🏛️ Modular 3-Tier Architecture: The "Tip of the Spear"

agent-security-gate-x402 follows a clean, decoupled 3-tier architecture. Developers start with the ultra-fast Core (Tier 1) and seamlessly scale into Institutional Governance (Tier 2) and Enterprise Domain Extensions (Tier 3):

┌─────────────────────────────────────────────────────────────────────────┐
│ 🗡️ TIER 1: THE TIP OF THE SPEAR (Developer Core & Settlement Engine)    │
│  • Sub-5ms Zero-Trust AST Gate & Prompt Injection Defense (/inspect)    │
│  • HTTP 402 Autonomous Escrow Hub & Multi-Chain Settlement (/hub)       │
│  • Solana Mainnet (0.4s) · Polygon (137) · Base (8453) · Arbitrum (42161)│
│  • 1-Line Drop-In SDK & Model Context Protocol (MCP) Server             │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ powers
┌────────────────────────────────────▼────────────────────────────────────┐
│ 🛡️ TIER 2: INSTITUTIONAL GOVERNANCE (Treasury & Trust Framework)        │
│  • Safe{Wallet} Guard & Spend Policy Firewall (daily/tx micro-ceilings) │
│  • Moody's & S&P AI Agent Credit Rating Oracle & EIP-712 Certificates   │
│  • EU AI Act Article 50 Compliance & Dynamic Risk Passport              │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ scales to
┌────────────────────────────────────▼────────────────────────────────────┐
│ 🌐 TIER 3: ENTERPRISE & DOMAIN EXTENSIONS (Real-World Assets & DePIN)   │
│  • 5 Strategic Truth Oracles (Maritime, Bio IP, BIM, DePIN, Code)       │
│  • Autonomous Receivables Factoring Bridge & Parametric Insurance Pool  │
│  • Sovereign RWA Treasury Backing & Multi-Agent Fleet Registry          │
└─────────────────────────────────────────────────────────────────────────┘

---

🔗 Live Service Links & Resources

---

🏛️ A.GRID Universal Escrow Hub: Sovereign Settlement Layer for 5 Sectors

The A.GRID Universal Escrow Hub operates as a sovereign, decentralized clearinghouse enabling autonomous agents and human enterprises to mint, claim, verify, and settle high-stakes contracts with zero counterparty risk:

                   👑 [ A.GRID Universal Escrow Hub (/hub) ]
           (Global Trade · Bio & Pharma IP · Smart Construction · DePIN · M2M)
                                   ▲
                                   │ 0.25% Protocol Toll · 0.4s Solana Finality
           ┌───────────────────────┼───────────────────────┐
           ▼                       ▼                       ▼
     [ 🚢 Global Trade ]      [ 🧬 Bio & Pharma ]     [ 🏗️ Smart Construction ]
     Cold-Chain IoT & GPS     ZK-SNARK & TEE Enclave  3D Drone LiDAR & Direct Split
           ▲                       ▲                       ▲
           └───────────────────────┴───────────────────────┘
                                   │
                    🤝 [ Autonomous AI Agents & Solvers ]

5 Strategic Domains & Deterministic Truth Invariants

1. 🚢 Global Trade & Maritime Freight (TRADE):
   • Truth Invariant: Cold-chain IoT logs (-20°C ± 2°C) + GPS geofence arrival (< 500m) + on-chain e-B/L + EUDR satellite polygon verification.
   • Settlement: Atomic split releasing freight payment to carrier lines and port stevedores.
2. 🧬 Bio & Pharma IP Transfer (BIO):
   • Truth Invariant: Zero-knowledge proof (ZK-SNARK) of binding affinity ($K_d < 10\text{nM}$) inside a Confidential TEE Enclave without leaking proprietary molecular SMILES before payment.
   • Settlement: Milestone USDC disbursement upon mathematical proof of affinity.
3. 🏗️ Smart Construction & Infrastructure (CONSTRUCTION):
   • Truth Invariant: Drone 3D LiDAR volumetric match $\ge 98.5%$ against target BIM model + concrete curing strength $\ge 24\text{ MPa}$.
   • Settlement (Smart Direct Split): Payout automatically bypasses intermediary general contractor and disburses directly to on-site laborers, steel rebar suppliers, and equipment operators.
4. ⚡ Solana DePIN Compute (COMPUTE):
   • Truth Invariant: Distributed GPU clusters (NVIDIA H100/A100) verified via loss convergence proof hash + prompt injection guard.
   • Settlement: Solana 0.4s micro-payment streaming ($0.00025 fee) with instant stake slashing upon fraud.
5. 💻 AI Agent Outsourcing & Code Verification (M2M):
   • Truth Invariant: Deterministic AST analysis blocking OS subprocess exploits (os.system, subprocess.Popen) and credential exfiltration.
   • Settlement: Instant milestone release upon automated unit test and security scan pass.

---

⚡ Multi-Chain Contract Registry

Treasury Fee Vault: 0xA185B43fDD19619f99952AAed6eabf1029bF36a1 (0.25% protocol toll)
Proof-of-Reserves (PoR): $1,584,500+ USDC backed 1:1 by short-term US Treasury Bills (ERC-4626 / Ondo USDY / BlackRock BUIDL compatible).

---

🔌 Model Context Protocol (MCP) Integration (Claude Desktop & Cursor)

Connect agent-security-gate-x402 to Claude Desktop, Cursor IDE, or any MCP client via direct command or Glama.ai:

Manual Configuration (claude_desktop_config.json)

{
  "mcpServers": {
    "security-gate-x402": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

---

🤖 ElizaOS Autonomous Agent Guard (@elizaos/plugin-security-gate)

Integrate deterministic, ultra-low latency (<1ms) prompt injection defense and AST sandboxing directly into any ElizaOS agent:

bun add @elizaos/plugin-security-gate

Add to character JSON (e.g. characters/trader.json):

{
  "name": "SecureTrader",
  "plugins": ["@elizaos/plugin-security-gate"]
}

Defense-in-Depth Pipeline

flowchart TD
    User([Inbound User / Tool Message]) --> PreHandler[securityGatePreHandler <br/> 0ms Inbound Interceptor]
    PreHandler -->|Prompt Injection / Evasion| Intercept([🚨 Intercepted & Blocked])
    PreHandler -->|Safe Message| Memory[Agent Working Memory]
    Memory --> ActionExec[Action / Tool Execution]
    ActionExec --> InspectAction[INSPECT_SAFETY Action]
    InspectAction -->|Local Deterministic AST & Regex| LocalAudit{Verdict?}
    LocalAudit -->|BLOCK| Halt([🚨 Fail-Closed Halt])
    LocalAudit -->|ALLOW / WARN| RemoteCheck{Remote Oracle <br/> Configured?}
    RemoteCheck -->|Yes| MicroOracle[Cloud Run Micro-Oracle <br/> EIP-712 Attestation]
    RemoteCheck -->|No| SafeExecute[Execute On-Chain Transaction]
    MicroOracle --> SafeExecute
    SafeExecute --> GuardContract[SafeSecurityGateGuard.sol <br/> Polygon / Base / Arbitrum]

• 📖 Comprehensive Tutorial: docs/ELIZAOS_GUARD_TUTORIAL.md
• 🔬 Threat Defense Matrix (15+ Vectors): docs/SECURITY_DEFENSE_MATRIX.md
• 🧙‍♂️ ERC Standard Proposal: Fellowship of Ethereum Magicians Topic

---

🛡️ Architectural Distinction: Advisory Tool vs. Fail-Closed Gate

A critical question in AI Agent security engineering: Where does enforcement live?

flowchart LR
    subgraph Advisory ["1. Advisory Mode (Peer MCP Tool)"]
        UserA[Inbound Request] --> ModelA[LLM Agent]
        ModelA -.->|Voluntary Check| ToolA[security-gate-x402 <br/> MCP Tool]
        ToolA -.->|JSON Verdict| ModelA
        ModelA -->|Can Ignore Verdict!| ExecA[Action Execution]
    end

    subgraph Gate ["2. Fail-Closed Gate Mode (Inline Enforcement)"]
        UserB[Inbound Request] --> GateB[securityGatePreHandler <br/> Inline Proxy / Gateway]
        GateB -->|BLOCK 🚨| DropB[Dropped at Boundary]
        GateB -->|ALLOW ✅| ModelB[LLM Agent & Tool Execution]
    end

• For Chat / Agent Runtimes (e.g. ElizaOS): Use @elizaos/plugin-security-gate with securityGatePreHandler. It intercepts incoming and outgoing messages in-path before model reasoning or tool dispatch occurs.
• For MCP Clients (e.g. Claude Desktop, Cursor): Connecting agent-security-gate-x402 via standard MCP config provides on-demand inspection tools (inspect_prompt_safety, inspect_code_ast_safety, get_onchain_security_attestation) with zero network latency.

---

⚡ 1-Click MCP Integration (Claude Desktop & Cursor)

Connect to Claude Desktop, Cursor, Windsurf, or any Model Context Protocol (MCP) client in seconds without building from source:

1. Claude Desktop Setup

Add the configuration snippet below to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "security-gate-x402": {
      "command": "uvx",
      "args": ["agent-security-gate-x402"]
    }
  }
}

2. Cursor IDE Integration

1. Open Cursor Settings (Ctrl + , or Cmd + ,) → Navigate to Features → MCP Servers.
2. Click Add New MCP Server.
3. Set Type: command
4. Set Name: security-gate-x402
5. Set Command: uvx agent-security-gate-x402

3. Registry & One-Click Installs

• 🌐 Glama.ai MCP Registry: Verified & approved server listing.
• 📦 PyPI Official Release: Official pip package distribution.

---

💎 Core Services & Capabilities

1. Ultra-Low Latency Prompt & Security Radar (<5ms)

Deterministic pattern and AST scanning neutralizing prompt injections, system tag breakouts (</system_instruction>), and API token / private key leakages before downstream agent propagation.

2. Python Code AST Hazard Auditing

In-memory Python Abstract Syntax Tree (AST) inspection isolating hazardous invocations:

• System execution (os.system, os.popen, subprocess.Popen, subprocess.run)
• Arbitrary code evaluation (eval, exec, __import__)
• Network socket reverse shells and unencrypted exfiltration vectors.

3. Factual Grounding & NLI Hallucination Verification

Compares LLM text claims against trusted source documents or ledger ground truths, outputting:

• Entity and numerical claim grounding ratios
• Flagged fabricated values and hallucinations
• Deterministic faithfulness confidence index.

4. Client-Side Bounded-Wallet Guardrails (BoundedAgentWallet)

Prevents rogue agents or infinite loops from draining autonomous wallets:

• Per-Transaction Spend Cap: Restricts maximum USDC per API call (default $0.05).
• Daily Budget Ceiling: Hard stop on cumulative 24-hour spend (default $1.00).
• Recipient Whitelisting: Guarantees funds only flow to verified gate addresses.
• Persistent Spend Ledger: Survives container restarts via local disk recording.

5. Server-Side Zero-Liability Audit Proof (X-Sheriff-Audit-Proof)

Every inspection delivers an immutable EIP-191 signed cryptographic receipt:

• Binds payload SHA-256 fingerprint, verdict, risk score, terms, and timestamp.
• Enforces ZERO_LIABILITY_AS_IS_PROVENANCE_V1 legal terms.
• Query canonical legal terms & liability limits via GET /api/v1/terms or inspect response header X-Sheriff-Terms-Url.
• Protects developers and enterprise operators against third-party liability disputes.

6. Cryptographic Proof-of-Safety & Smart Contracts

• EIP-191 Signatures: Off-chain attestation receipts for agent-to-agent validation.
• EIP-712 Typed Data & Solidity Calldata: Native integration with SecurityGateConsumer.sol on Polygon (137), Base (8453), and Arbitrum (42161).

7. A.GRID Universal Modular Escrow & Truth-Adapters (UniversalEscrowCore.sol)

A unified, Lego-like modular escrow architecture solving real-world physical and IP delivery disputes without contract fragmentation. Instead of maintaining separate contracts for every industry, a single on-chain core (UniversalEscrowCore.sol) pairs with off-chain pluggable Truth Adapters evaluated by a sub-5ms micro-oracle:

graph TD
    subgraph Client Layer ["1. Client & Enterprise Interface"]
        SDK["Unified agent_gate_sdk (Python / TypeScript)"]
        UI["B2B Unified Mission Control Dashboard"]
    end

    subgraph Off-Chain Truth Engine ["2. Off-Chain Truth Adapters (<5ms)"]
        Gate["Security Gate Micro-Oracle (EIP-712 Signer)"]
        Ad1["🚢 TradeIoTAdapter (GPS Geofence & Cold-Chain)"]
        Ad2["🧬 BioZkAdapter (Genomics & ZK-SNARK Kd Affinity)"]
        Ad3["🏗️ BuildDroneAdapter (3D LiDAR & BIM CAD Match)"]
    end

    subgraph On-Chain Settlement Core ["3. On-Chain Universal Escrow Core"]
        Core["UniversalEscrowCore.sol (Polygon, Base, Arbitrum)"]
        Split["Direct Split Disbursal Engine (<1s Settlement)"]
    end

    SDK --> Gate
    UI --> Gate
    Ad1 --> Gate
    Ad2 --> Gate
    Ad3 --> Gate
    Gate -->|EIP-712 Proof Attestation| Core
    Core --> Split

🌐 3 Real-World Industrial Truth Domains

⚡ 3-Line Python SDK Usage

from sdk import UniversalEscrowClient, IndustryDomain

# 1. Initialize client
escrow = UniversalEscrowClient(chain_id=137)

# 2. Lock capital into Universal Escrow Core
job = escrow.create_job(
    domain=IndustryDomain.CONSTRUCTION_BUILD,
    amount_usdc=1_000_000.0,
    truth_requirement_hash="0x3fbc8a9b..." # BIM Model Hash
)

# 3. Direct split payout instantly upon autonomous drone verification
escrow.settle_with_truth(
    job_id=job.id,
    proof_data="DRONE_LIDAR_BIM_MATCH_PASS",
    recipients=[
        {"address": "0xWorkersPool...", "amount": 350_000.0},
        {"address": "0xConcreteSupply...", "amount": 400_000.0},
        {"address": "0xSteelSupply...", "amount": 247_500.0}
    ] # 0.25% ($2,500 USDC) fee automatically routed to A.GRID Treasury
)

🧪 Interactive Simulation Runner

Simulate all 3 industrial escrows end-to-end with cryptographic EIP-712 proofs and zero-deficit balance audit:

python scripts/demo_universal_escrow_lifecycle.py

---

📦 Quick Start & Installation

📖 Read the 3-Minute Quickstart Guide • 🧪 Run 3-Line Agent Demo • 🌐 ElizaOS Plugin

Option 1. Run Instantly with uvx (No Installation Required)

# Run stdio MCP server directly for LLM clients
uvx agent-security-gate-x402

Option 2. Install from PyPI

pip install agent-security-gate-x402

# Run MCP server (stdio mode)
agent-security-gate

# Or launch interactive terminal tester
python test_interactive.py

Option 3. Local Development Server

git clone https://github.com/nohosa001-pixel/security-gate-x402.git
cd security-gate-x402
pip install -e .
uvicorn app.main:app --port 8000 --reload

---

📜 Smart Contract Integration & Verified Deployments

Autonomous on-chain agents can verify security attestations directly in Solidity before executing financial transactions.

⛓️ Verified Polygon Mainnet Deployments (Chain ID: 137)

The core micro-oracle signers and security consumer contracts are live on Polygon Mainnet:

🛠️ Solidity Integration Example (SecurityGateConsumer.sol)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "./contracts/SecurityGateConsumer.sol";

contract AutonomousAgentExecutor {
    SecurityGateConsumer public immutable securityGate;

    constructor(address _securityGateAddress) {
        securityGate = SecurityGateConsumer(_securityGateAddress);
    }

    function executeGuardedAction(
        bytes32 payloadHash,
        uint8 riskScore,
        string calldata verdict,
        uint256 expiresAt,
        uint8 v,
        bytes32 r,
        bytes32 s,
        address target,
        bytes calldata callData
    ) external {
        // Enforces max 10% risk score threshold and valid oracle signature
        securityGate.verifyAndExecute(
            payloadHash,
            riskScore,
            verdict,
            expiresAt,
            v,
            r,
            s,
            target,
            callData,
            10 // maxRiskScore
        );
    }
}

---

🧪 Testing

Run the full pytest suite:

pytest -v tests/

Launch the interactive terminal tester:

python test_interactive.py

---

📢 X (Twitter) Automated Promotion & Security Alert Bot

Launch the automated promotion and status broadcast bot:

# Windows 1-Click launcher
.\x_promo_bot.bat

# Or run via Python directly
python x_promo_bot.py

• 🇰🇷 Korean Thread: Comprehensive showcase of security radars, AST parser, and Web UI.
• 🌐 Global Launch Thread: High-impact English launch announcement with 1-click test links.
• 🛡️ Real-Time Security Bulletins: Automated micro-oracle status and guardrail alerts.
• 🤖 Dual Mode: Direct X API v2 thread chaining (requests_oauthlib) or instant 1-click Web Intent browser launcher.

---

📄 License

MIT License © 2026 Security Gate Team