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

Service / Endpoint	Description	URL Link
🏛️ Universal Escrow Hub	Multi-chain sovereign settlement & clearinghouse across 5 sectors	Launch Escrow Hub
🤖 Autonomous Agent Directive	Standard machine-readable directive & API handshake for agents	/AGENTS.md
📜 Proof-of-Reserves (PoR)	Real-time cryptographic solvency & US T-Bills treasury audit	/api/v1/escrow/por
🖥️ Web Dashboard	Interactive visual UI, security simulator & audit tester	Launch Dashboard
⚡ API Playground	Browser-based interactive query sandbox	Open Playground
🛡️ Live Inspection	Core deterministic security & NLI hallucination check	/inspect
📜 On-Chain Calldata	EIP-712 smart contract attestation calldata endpoint	/api/v1/gate/attestation/onchain
📊 Prometheus Metrics	Real-time APM telemetry & security counters	/metrics
🛡️ Glama MCP Directory	Verified MCP Server with JSON Tool Schemas	Open on Glama
📖 Swagger API Docs	Full interactive OpenAPI documentation	View Swagger Docs
🤖 LLM Agent Manifest	Machine-readable tool specifications	/llms.txt

---

🏛️ 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

Network	Chain ID	Contract Type	Address	Finality
Solana Mainnet	501	Universal Anchor Program	AGR3W3R9pKxnuZGYrpaggfkbMKVrjoniLaGvi1voBFSC	0.4s
Polygon Mainnet	137	UniversalEscrowCore.sol	0x8ACafCEce0B1BFE140e75614b90FD1307b6f389d	2.1s
Base Mainnet	8453	UniversalEscrowCore.sol	0x99FEd65Cf2D5378182c3481B300124BB1a8Ad278	2.0s
Arbitrum One	42161	UniversalEscrowCore.sol	0x99FEd65Cf2D5378182c3481B300124BB1a8Ad278	0.25s

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?

Integration Mode	Position in Stack	Enforcement Mechanism	Security Guarantee
Advisory Mode (MCP Peer Server)	Lateral to Agent Model	Host LLM decides whether to invoke tool and whether to honor verdict	Best-effort / Advisory. Compromised or jailbroken models can ignore the tool.
Fail-Closed Gate Mode (Pre-Handler / Inline Gateway)	Directly in Request Path	Deterministic code execution intercepting traffic before tool/action runs	Deterministic Enforcement. Bypasses model volition; invalid payloads are dropped at network/runtime boundary.

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

Domain (enum)	Industry & Physical Invariant	Off-Chain Verification	Direct Split Beneficiaries
0: TRADE_MARITIME	🚢 Maritime Freight & Cold-Chain	Haversine GPS (<500m port radius), -20°C ± 2°C temp timeseries, RFID dock scan	Vessel Captain, Cold-Storage Harbor, Customs Brokerage
1: BIO_KNOWLEDGE_IP	🧬 Bio / Pharma Research IP	Genomic Merkle Root matching, sub-10nM binding affinity (Kd) ZK-proof, TEE SGX attestation	Research Lab, GPU/TEE Compute Cluster, Patient Registry
2: CONSTRUCTION_BUILD	🏗️ Infrastructure & Construction	Autonomous Drone 3D LiDAR point cloud vs BIM architectural model (≥98.5%), Concrete compressive strength (≥24 MPa)	Direct to 50+ Field Laborers & Concrete/Steel Material Suppliers (Bypasses contractor embezzlement)

⚡ 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:

Contract / Role	Address	Explorer
🛡️ SecurityGateConsumer	0x9E3dEE18D8139E1d20f9f7D1F6673c75727F1DDA	PolygonScan
🏰 SafeSecurityGateGuard	0x5cC5Afa2a97599d492A3E408Fdd95fD0b520f173	PolygonScan
🤝 AgentEscrow	0x8ACafCEce0B1BFE140e75614b90FD1307b6f389d	PolygonScan
📊 AgentCreditOracle	0x6418f408cFf03F862D7691f01fAb00a895E6aB93	PolygonScan
📋 AgentComplianceRegistry	0x28292D76E07E5539F15F3b97935dE8E0432E76DD	PolygonScan
🏦 AgentLendingPool	0xe43a9C368808B2dfF139D27789C40A3C8F2282cF	PolygonScan
☂️ AgentInsurancePool	0x4f115665a2BdE534bb7fC426e89ca0BfE2De3B50	PolygonScan
🔄 AgentFactoringPool	0xd0Aa4Aed2AeDE14611B53C3e93CF784F3Fe05BB0	PolygonScan
🏛️ AgentTreasuryVault	0xfCf3BF5fB5858db9aE81bE458B39b0032fc0C638	PolygonScan
🌐 UniversalEscrowCore	0x5555555555555555555555555555555555555555	Contracts
🔑 Oracle Signer / Treasury	0xA185B43fDD19619f99952AAed6eabf1029bF36a1	PolygonScan

🛠️ 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