Agentic Wallet Guardian V3

Agentic Wallet Guardian

Watch the demo

Select the preview to play the video in your browser.

📄 Read the white paper

Let AI agents transact on-chain without giving them unrestricted control of the wallet. Guardian evaluates each proposed action before signing or broadcast and returns an explainable ALLOW / WARN / BLOCK decision.

POST /decision   ->   ALLOW / WARN / BLOCK  (with a reasoned explanation)

It runs on your own infrastructure, using your own policy rules and your own reputation data - see Why self-hosted for why that matters and how this differs from calling a hosted security API directly.

Guardian is chain- and use-case-agnostic - Arc/USDC below is one live deployment, not the whole scope. See docs/hackathons.md for which track this submission targets and why.

Arc Mainnet Demo

Live demo: http://77.239.125.37:8765/arc

Demo video: https://youtu.be/srH0ZLwtwqQ

Agentic Wallet Guardian is deployed on Arc mainnet and includes a live browser demo for USDC payments. The Guardian evaluates the requested operation before execution, applies its security policies, and only an approved operation is passed to the user's wallet for signing.

Verified Arc mainnet transaction: 0xd781e8b04b5ca89c3a34fcec50a6636049f7647d2b0e1b2bb64d5b1ee54daadf

The transaction was successfully executed on Arc mainnet using USDC through the Guardian demo.

---

See it decide, live: run the API locally (GUARDIAN_ENABLE_CORS_FOR_BROWSER_DEMO=true uvicorn api.main:app --reload), then open examples/browser-demo.html in a browser - no build step, no server for the page itself. Every scenario button sends a real POST /decision to your running instance and renders the actual response (risk score, every signal that fed into it, every policy rule that fired) - nothing in the page is scripted or faked. GUARDIAN_ENABLE_CORS_FOR_BROWSER_DEMO is off by default (see guardian/config.py) since it's specifically for this local-demo case, not something to leave on for a real deployment.

---

Why self-hosted

There are good hosted alternatives for agent-transaction security (GoPlus's AgentGuard, Blockaid, Chainalysis/TRM for compliance). If you just want a risk score and don't care who sees the query, calling one of those directly is less work than running this. Guardian exists for the cases where that tradeoff doesn't work for you:

• Nothing about which wallets, contracts, or amounts your agents touch leaves your infrastructure. Threat-intel and contract allow/deny checks are local JSON files you populate yourself (see data/threat_lists/README.md), not a lookup call to a third party. A hosted API inherently sees every address and amount you ask it about.
• Your policy rules live in your code, not a vendor's dashboard. Spending caps, reputation gates, and which action types require confirmation are plain Python in guardian/policy/, reviewable and changeable without waiting on anyone else's product roadmap.
• No per-call fees or rate limits imposed by someone else - only the ones you configure for your own users (GUARDIAN_RATE_LIMIT_PER_MINUTE).
• No vendor lock-in. Every external data source (RPC endpoint, Blockscout instance, DexScreener) is swappable behind a small provider interface - see Architecture.

The honest tradeoff going the other way: you also take on running it, keeping your local threat lists current, and you don't get a hosted vendor's chain coverage or dedicated threat-research team for free. This is the right choice for teams that specifically need data sovereignty or deep policy customization - not a strict upgrade over every hosted option.

---

Architecture

                AI Agent

| v Action Intent { agent_id, wallet, chain, action_type, target, amount, metadata } | v ┌───────────────────────────────┐ │ Guardian Decision Engine │ ├───────────────────────────────┤ │ 1. Hard Rules │ <- chain support, sanity checks │ 2. Wallet Intelligence │ <- mock | real RPC (web3.py) │ 3. Token Intelligence │ <- mock | real DexScreener | real GoPlus │ 4. Contract Intelligence │ <- local lists, then mock | real Blockscout | real GoPlus │ 5. Simulation │ <- mock | real eth_call dry-run (see below) │ 6. Threat Intelligence │ <- local JSON allow/deny lists │ 7. Anomaly Detection │ <- vs. this agent's own history (see below) │ 8. Policy Engine │ <- spending caps, reputation gates │ 9. Risk Fusion │ <- signals -> single 0-100 score │ 10. Reputation Adjustment │ │ 11. Explanation │ <- evidence -> human-readable reasons └───────────────────────────────┘ | v ALLOW / WARN / BLOCK | v Blockchain Execution

Every data source in steps 2-4 is a small provider interface with a mock implementation (zero config, zero network calls) and a real one, selected per-source by environment variable - see .env.example. Switching from demo mode to a real deployment is a config change, not a code change.

Repository layout

guardian/

config.py GuardianConfig - the one place that reads os.environ core/ ActionIntent, Signal, Decision, EvaluationContext (zero external dependencies - no pydantic/FastAPI) decision/ DecisionEngine (orchestrator), RiskFusionEngine, hard rules reasoning/ explanation + confidence builders intelligence/ wallet/ analyzer.py + providers.py (mock | RpcWalletDataProvider) token/ analyzer.py + providers.py (mock | DexScreenerTokenDataProvider | GoPlusTokenDataProvider) contract/ analyzer.py + providers.py (mock | BlockscoutContractDataProvider | GoPlusContractDataProvider) simulation/ pre-execution dry-run (mock | real eth_call) + tx_builder.py (real calldata for transfer/approve) goplus_client.py shared GoPlus Token Security API client (used by both contract + token) threat/ blocklist.py (local AddressList) + intelligence.py policy/ PolicyEngine + policy templates (spending caps, reputation gates) reputation/ AgentReputation (score derived from decision history) memory/ storage.py (protocol) + InMemoryStorage + sqlite_storage.py api/ main.py FastAPI app: /decision, /health, /capabilities, /agents/{id}/history, /demo/{scenario} security.py API-key auth dependency + rate-limit middleware schemas.py pydantic request/response models (API boundary only) mcp_server.py MCP stdio server - same DecisionEngine, no HTTP required data/threat_lists/ local, operator-maintained allow/deny lists (empty by default - see its README) scripts/ refresh_ofac_list.py fetch OFAC's public SDN list into the local threat list tests/ 101 tests covering the engine, policy, reputation, and every provider

guardian/* is intentionally dependency-free (standard library only, except where a real provider needs httpx or web3), so the decision core can be unit-tested, embedded in another service, or ported to a different web framework without dragging FastAPI along. Only api/ touches pydantic/FastAPI.

---

Honesty about the current state

This is real, runnable, tested decision infrastructure with real (not mock) data sources available for every signal source - but "available" isn't the same as "flip a switch and trust it blindly." Specifics:

• Wallet (RPC provider): is_contract and tx_count (nonce-based) are reliable with any JSON-RPC endpoint. Wallet *age* requires an archive-capable node and is off by default (GUARDIAN_RPC_ESTIMATE_AGE=false) - most free public RPC endpoints don't serve historical state, so this fails closed to "unknown" rather than guessing.
• Contract (Blockscout provider): real verification-status lookups against a public Blockscout instance. Their exact response schema and rate limits can change - this is written to degrade to "unknown" on any unexpected response, never to fabricate an answer, but hasn't been load- tested against production traffic.
• Token (DexScreener provider): real liquidity data, but matching a bare ticker symbol to an on-chain pair is inherently ambiguous (many unrelated tokens share a symbol, and scammers deliberately mint look-alikes). The provider picks the highest-liquidity pair on the requested chain and reports its own match confidence rather than presenting a guess as certain - for anything where that ambiguity matters, match by contract address instead of symbol.
• Contract + Token (GoPlus provider): real contract-security (owner-can-drain, mintable, self-destruct, hidden owner) and trading-security (honeypot, buy/sell tax, blacklist, pausable transfers, holder concentration) from GoPlus's Token Security API - meaningfully more signal types than Blockscout/DexScreener give individually, since GoPlus's own static analysis covers both in one call. Two real limits: it only has data for contracts it's actually analyzed (mostly token contracts, not generic dApp/router contracts), and GoPlusTokenDataProvider needs a contract *address* - a bare symbol like "PEPE" can't be resolved and is honestly reported as unverifiable rather than guessed at.
• Sanctioned-address list is real, populated data: 103 addresses (100 EVM + 3 Solana) from OFAC's SDN list, via 0xB10C/ofac-sanctioned-digital-currency-addresses - verified end-to-end (a known-sanctioned address correctly triggers BLOCK through the full pipeline) and verified to correctly reflect delistings, not just additions (Tornado Cash's addresses, removed from the SDN list in March 2025, are correctly absent). Re-run scripts/refresh_ofac_list.py periodically - sanctions change in both directions.
• `malicious_contracts.json` / `verified_contracts.json` still ship empty on purpose (see data/threat_lists/README.md) - there's no single authoritative source for "malicious contract" the way OFAC's list is authoritative for sanctions, so populating these is a judgment call for whoever operates this instance, not something to seed by default with unverified entries.
• Simulation is real, but conditional. RpcSimulationProvider (GUARDIAN_SIMULATION_PROVIDER=rpc) genuinely dry-runs a transaction via eth_call/eth_estimateGas against current chain state - a revert comes back with its actual reason, not a guess, and ERC-20 approve() amounts are decoded from real calldata instead of inferred. This activates when the caller supplies raw calldata via intent.metadata["data"], OR - new - when GUARDIAN_TX_BUILDER=rpc is also set and the intent is a plain transfer or approve (see next bullet). A swap intent with no transaction built yet still has nothing to dry-run - Guardian reports that honestly (simulation_not_attempted) rather than guessing.
• **Transaction building