╔══════════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ ██╗ ██╗ █████╗ ██████╗ ██████╗ ██╗ █████╗ ███╗ ██╗ ║
║ ██╔════╝ ██║ ██║██╔══██╗██╔══██╗██╔══██╗██║██╔══██╗████╗ ██║ ║
║ ██║ ███╗██║ ██║███████║██████╔╝██║ ██║██║███████║██╔██╗██║ ║
║ ██║ ██║██║ ██║██╔══██║██╔══██╗██║ ██║██║██╔══██║██║╚████║ ║
║ ╚██████╔╝╚██████╔╝██║ ██║██║ ██║██████╔╝██║██║ ██║██║ ╚███║ ║
║ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚══╝ ║
║ ║
║ P R O T O C O L ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
Fail-Closed. Paranoid by Design. Built for Autonomous Agents on X Layer.
An autonomous AI agent can't smell a honeypot. It can't sense a sandwich attack forming in the mempool. It can't read a manipulated liquidity pool. Guardian Protocol can — and it answers in under 2 seconds.
Autonomous AI agents are executing real trades on real chains with real money. They're doing it faster than any human ever could. But they're doing it blind.
Every other DeFi security tool is built for humans: visual dashboards, browser extensions, manual lookups. When an agent needs to know right now whether a trade is safe, those tools are useless.
Worse: most security tools fail open. If the scan returns nothing — no result, timeout, unknown token — they say "probably fine, proceed." For an autonomous agent running thousands of trade evaluations, that's not a safety policy. That's Russian roulette.
Guardian Protocol is different. We fail closed.
If we cannot confirm it's safe with high confidence — the trade is blocked. Full stop.
Guardian Protocol is a reusable Agent Skill — a drop-in security middleware that any autonomous agent can call before executing an on-chain swap on X Layer.
One function call. One JSON verdict. No ambiguity.
const verdict = await evaluateTrade({ tokenIn, tokenOut, amount, chainId: 196 });
if (verdict.isSafeToExecute) {
executeSwap(); // ✅ Guardian cleared this trade
} else {
abort(); // ⛔ Guardian blocked it — reasons in verdict.flags
}That's the entire integration. Behind those two lines: a four-engine security pipeline running in parallel, powered by OKX's infrastructure, designed to withstand adversarial mainnet conditions.
Sample CLI Evaluation Output:
{
"isSafeToExecute": false,
"safetyScore": { "overall": 0, "tier": "CRITICAL" },
"flags": [
{ "code": "HONEYPOT_DETECTED", "severity": "CRITICAL", "message": "Contract code matches known honeypot pattern: sell function disabled post-buy." }
]
} +--------------------------------------------------------------+
| |
| Agent --> evaluateTrade(request) --> GUARDIAN ORCHESTRATOR |
| |
| +--------------+ +--------------+ +-------------+ +--------+|
| | TOKEN RISK | | TX | | MEV | | AMM ||
| | (30%) | | SIMULATION | | DETECTION | | POOL ||
| | | | (30%) | | (15%) | | (25%) ||
| | Honeypot | | eth_call | | Trade-size | | Thin ||
| | Tax scan | | dry-run | | heuristic | | liq. ||
| | Blacklist | | OKX cross- | | Dynamic | | Tick ||
| | Mint fn | | validation | | slippage | | gap ||
| | Holders | | | | cap | | Price ||
| | GoPlus API | | | | | | dev. ||
| | OKX API | | | | | | 1-side ||
| +------+-------+ +------+-------+ +------+------+ +---+----+|
| | | | | |
| +----------------+----------------+-------------+ |
| | |
| +-----------v-----------------+ |
| | RISK ENGINE | |
| | Weights: 30 / 30 / 15 / 25 | |
| | Penalty cascades | |
| | Cross-analyzer correlation | |
| | Sub-score floor enforcement | |
| | Confidence degradation | |
| +-----------+-----------------+ |
| | |
| +----------------v---------------------+ |
| | { isSafeToExecute, safetyScore, flags } |
| +------------------------------------------+ |
| |
+--------------------------------------------------------------+
Powered by OKX Security API + GoPlus Security (dual-oracle)
Calls two independent security oracles for every token. Not one — two. The OKX Security API is the primary source; GoPlus Security provides a cross-validated second opinion on every honeypot classification. If they disagree, the score takes a penalty. If either times out, the trade is blocked.
What it detects: honeypots, hidden sell taxes, blacklist wallet functions, unlimited mint capabilities, unverified contracts, low holder counts (rug-pull indicators), ownership not renounced.
eth_call dry-run → OKX Security API cross-validation
Simulates the transaction via eth_call on X Layer's RPC, pinned to a specific block number for deterministic results. The simulation detects reverts before the transaction hits the mempool — saving the agent from wasting gas on a doomed transaction — and computes exact slippage by decoding the return data against the agent's expected output. In parallel, the OKX Security API's transaction-scan endpoint provides an independent second opinion on the transaction's safety, flagging known drainer contracts, suspicious approval patterns, and phishing attempts that pure eth_call cannot detect. If the OKX API is unavailable, the pipeline degrades gracefully to RPC-only results rather than blocking outright — the OKX cross-check is additive confidence, not a hard dependency.
What it detects: transaction reverts (with gas waste calculation), excessive slippage, OKX-flagged drainer contracts, suspicious state changes, elevated gas costs.
Deterministic trade-impact heuristic with dynamic slippage caps
This analyzer operates deterministically on available quote data and does not perform live mempool WebSocket scanning. Instead of attempting unreliable mempool observation, it focuses on what it can control: hardening the transaction's execution parameters to make MEV extraction mathematically unprofitable. The engine computes a dynamic slippage cap based strictly on the USD size of the trade — larger trades receive tighter caps because they present more profitable sandwich targets. Trades over $1,000 get a 25% tighter slippage cap; trades over $10,000 get a 50% tighter cap. The result is a recommended maximum slippage tolerance that the agent should enforce, along with a trade-impact assessment (negligible, moderate, significant, extreme) that quantifies the trade's vulnerability to extraction.
What it detects: sandwich attack profitability (via slippage exposure), frontrunning risk at trade size, trade-size impact assessment, recommended MEV protection.
On-chain concentrated liquidity state reads
This is the analyzer that no other tool has. It reads the raw on-chain state of the concentrated liquidity pool directly — slot0(), liquidity(), ticks(), tickSpacing() — using a Uniswap V3-compatible ABI. It detects liquidity manipulation that is completely invisible to traditional constant-product analysis:
- Tick gap manipulation — Liquidity withdrawn near the current price creates a price cliff. The trade executes; the price dumps.
- sqrtPriceX96 deviation — The reported pool price doesn't match the theoretical price implied by the current tick. Someone is lying.
- One-sided liquidity — 90% of liquidity concentrated above or below the current price is the fingerprint of a coordinated extraction setup.
- Thin liquidity at tick — Zero active liquidity at the execution tick means your trade walks off a cliff.
┌─── CAN WE CONFIRM SAFETY WITH HIGH CONFIDENCE? ───┐
│ │
│ YES, all analyzers succeeded │
│ AND score ≥ 70 │
│ AND no sub-score < 20 │
│ AND no CRITICAL flags │
│ ↓ │
│ ✅ APPROVE │
│ │
│ ANYTHING ELSE → ⛔ BLOCK │
│ │
│ Examples: │
│ • API timeout → Score 0 → BLOCK │
│ • RPC unreachable → Failover → BLOCK if all │
│ • Unknown token → Score 0 → BLOCK │
│ • OKX ≠ eth_call → Penalty → Likely BLOCK │
│ • Zero tick liquidity → CRITICAL → BLOCK │
│ • High slippage cap → Slippage ↓→ May BLOCK │
└────────────────────────────────────────────────────┘
This is not a "show the user a warning" design. This is a gate. Agents don't get warnings — they get true or false. A value of false means the swap function never gets called. Period.
Guardian Protocol is not bolted onto OKX infrastructure — it is built from it. Every security judgment passes through OKX's APIs.
| OKX Component | Guardian's Usage |
|---|---|
| OKX Security API — Token Scan | Primary oracle: honeypot classification, buy/sell tax, blacklist detection, holder analysis |
| OKX Security API — TX Pre-execution | Independent cross-validator: our eth_call result is verified against OKX's external simulation. Disagreements trigger a penalty. |
| OKX DEX API | Supported architecture for Phase 3 optimized execution routing post-verdict |
| HMAC-SHA256 Auth | Full OKX API v5 authentication: OK-ACCESS-KEY, OK-ACCESS-SIGN, OK-ACCESS-TIMESTAMP, OK-ACCESS-PASSPHRASE |
X Layer RPC (xlayerrpc.okx.com) |
Native viem-based client with 3-endpoint round-robin and 500ms per-endpoint timeout |
| Chain ID 196 / 195 | Native mainnet + testnet support |
When the OKX API returns a honeypot flag, the specific reason is surfaced in the flags array: "Contract code matches known honeypot pattern: sell function disabled post-buy." Not a generic warning. A specific, actionable diagnosis.
Guardian Protocol integrates Uniswap's official AI Skills (npx skills add Uniswap/uniswap-ai) into its AMM pool analyzer for protocol-specific security capabilities that generic tools miss.
Uniswap AI Skills Referenced:
| Uniswap AI Skill | Guardian's Usage |
|---|---|
| swap-integration | TWAP verification patterns — Guardian reads Uniswap V3 observations to detect spot/TWAP price deviations that indicate flash loan manipulation |
| uniswap-v4-security-foundations | V4 hook permission risk model — Guardian assesses beforeSwapReturnDelta, afterSwapReturnDelta, and other dangerous hook permissions that can modify swap pricing |
| uniswap-driver | Swap planning and price validation reference — Guardian uses the same observation window methodology for TWAP-based oracle integrity verification |
| uniswap-viem | EVM integration patterns — Guardian's pool state reads use the same viem + Uniswap V3 ABI patterns for slot0(), liquidity(), ticks(), observe() |
What Guardian adds on top of Uniswap AI Skills:
-
TWAP Oracle Deviation Analysis — Reads Uniswap V3's
observe()function to compute 5-minute and 30-minute TWAPs, then compares against spot price. A >2% deviation triggers a warning; >5% flags manipulation (likely flash loan attack in progress). -
V4 Hook Security Assessment — For Uniswap V4 pools, Guardian reads hook permissions and flags dangerous combinations:
beforeSwapReturnDelta= HIGH risk (hook can modify swap pricing arbitrarily)afterSwapReturnDelta= MEDIUM risk (hook can modify output amounts)- Standard
beforeSwap/afterSwap= LOW risk (common for oracles, fees)
-
Concentrated Liquidity Manipulation Detection — What Uniswap AI tools don't cover: reading raw tick-level liquidity distribution to detect strategic removal of liquidity near the current price (tick gap manipulation), one-sided liquidity (rug-pull signal), and zero-liquidity execution ticks.
Install Uniswap AI Skills:
npx skills add Uniswap/uniswap-ai
Source: Uniswap/uniswap-ai
Every evaluation returns a composite score 0–100 computed via weighted aggregation with penalty cascading.
| Tier | Score | Machine Verdict | Meaning |
|---|---|---|---|
| ✅ SAFE | 90–100 | isSafeToExecute: true |
All analyzers clear. Execute. |
| 70–89 | isSafeToExecute: true |
Minor signals. Present but manageable. Review flags. | |
| 🔶 CAUTION | 50–69 | isSafeToExecute: false |
Significant risk. Blocked. |
| 🟠 DANGEROUS | 30–49 | isSafeToExecute: false |
Multiple serious vectors. Blocked. |
| 🔴 CRITICAL | 0–29 | isSafeToExecute: false |
Fatal signal or analyzer failure. Blocked. |
The risk engine is not a calculator — it's an adversarial model:
- Sub-score floor — Any single analyzer scoring below 20 blocks the trade regardless of the overall score. A token that scores 95 but has a simulation revert is still blocked.
- Cross-analyzer penalty cascades — Correlated risk signals amplify each other:
AMM_THIN_LIQUIDITY+ high simulation slippage → −60% penalty (confirmed pool manipulation)AMM_PRICE_DEVIATION+SANDWICH_ATTACK_LIKELY→ −40% penalty (coordinated attack pattern)AMM_ONESIDED_LIQUIDITY+MINT_FUNCTION_PRESENT→ −30% penalty (rug-pull signature)
- Confidence degradation — Each failed analyzer reduces the confidence factor applied to the final score. Three failed analyzers = score effectively halved before verdict.
- Node.js ≥ 20.0.0
- OKX API credentials — OKX Developer Portal
- An X Layer RPC endpoint (public:
https://rpc.xlayer.tech)
# Clone
git clone https://github.com/bitnormie01/guardian-protocol
cd guardian-protocol
# Install
npm install
# Configure
cp .env.example .env
# Add your OKX API credentials to .env
# Verify — all 72 tests should pass
npm test
# Live fire against X Layer Mainnet
npm run live-fire# Full trade evaluation: Is this WOKB → USDC swap safe?
npx tsx src/cli.ts evaluate \
0xe538905cf8410324e03A5A23C1c177a474D59b2b \
0x1E4a5963aBFD975d8c9021ce480b42188849D41d \
1000000000000000000 \
--chain 196
# Quick token screen: Is this token a honeypot?
npx tsx src/cli.ts scan-token \
0xe538905cf8410324e03A5A23C1c177a474D59b2b \
--chain 196
# Pre-flight check: Will this transaction revert?
npx tsx src/cli.ts simulate-tx \
0xYourRawTxHex \
--user 0xYourWallet \
--chain 196All CLI output is pure JSON on stdout. Agents parse it directly. Structured logs on stderr. No mixing.
import { evaluateTrade, scanToken, simulateTx } from "@guardian-protocol/skill";
// ── Pattern 1: Full pipeline (recommended for every swap) ──
const verdict = await evaluateTrade({
tokenIn: "0xe538905cf8410324e03A5A23C1c177a474D59b2b",
tokenOut: "0x1E4a5963aBFD975d8c9021ce480b42188849D41d",
amount: "1000000000000000000",
userAddress: "0xYourWallet",
chainId: 196, // X Layer Mainnet
});
if (verdict.isSafeToExecute) {
// Execute your swap — Guardian doesn't execute trades, only evaluates them
await executeSwap({ tokenIn, tokenOut, amount });
// Note: verdict.optimizedRouting is a Phase 3 field (currently null)
} else {
// Structured flags tell the agent exactly why
for (const flag of verdict.flags) {
console.log(`[${flag.severity.toUpperCase()}] ${flag.code}: ${flag.message}`);
}
}
// ── Pattern 2: Token pre-screen before even building a tx ──
const scan = await scanToken({ tokenAddress: "0x...", chainId: 196 });
if (!scan.isSafe) return; // don't waste gas building a tx for a honeypot
// ── Pattern 3: Validate a pre-built transaction ──
const sim = await simulateTx({ proposedTxHex: "0x...", userAddress: "0x...", chainId: 196 });
if (!sim.simulationSuccess) return; // tx would revertnpm test # Full suite: 72/72 ✅
npm run test:watch # Watch mode for development
npm run live-fire # End-to-end test against X Layer Mainnet (Chain ID 196)| Suite | Tests | What's Covered |
|---|---|---|
token-risk.test.ts |
9 | Honeypot, blacklist, mint, tax, API failure → fail-closed |
tx-simulation.test.ts |
13 | Revert detection, slippage via eth_call return data, OKX cross-validation (action:block/warn), graceful degradation, RPC failure → fail-closed, quick revert check, slippage edge cases |
mev-detection.test.ts |
10 | Trade-size impact assessment, dynamic slippage cap computation, custom thresholds, score boundaries, report structure, error handling |
amm-pool-analyzer.test.ts |
13 | Thin liquidity, tick gaps, price deviation, one-sided, score bounds |
risk-engine.test.ts |
27 | Weighted scoring, all 3 AMM correlations, confidence, penalties, sub-score floors |
| Total | 72 | 100% passing ✅ |
The test suite is adversarial. It doesn't just test the happy path — it tests everything that can go wrong and verifies the system fails closed every time.
| Metric | Value | Notes |
|---|---|---|
| Full 4-analyzer pipeline | < 2 seconds | All 4 analyzers run concurrently via Promise.all |
| RPC failover budget | ~1.5s | 3 endpoints × 500ms timeout each |
| Cache hit response | < 1ms | LRU cache serves repeat evaluations instantly |
| Cache TTL | 60 seconds | Fresh enough for DeFi conditions |
| Cache capacity | 500 entries | Handles high-frequency agent loops |
Agents running in evaluation loops never hit rate limits. The OKX API client wraps all requests in a 60-second LRU cache. The same token evaluated 50 times in a minute hits the API once.
| Category | Flag Code | Severity | What It Means |
|---|---|---|---|
| Token | HONEYPOT_DETECTED |
🔴 CRITICAL | Cannot sell after buying — funds permanently trapped |
| Token | BLACKLIST_FUNCTION |
🔴 CRITICAL | Contract can freeze your wallet address |
| Token | HIGH_TAX_TOKEN |
🟠 HIGH | Buy/sell tax exceeds threshold — guaranteed extraction |
| Token | MINT_FUNCTION_PRESENT |
🟠 HIGH | Deployer can print unlimited tokens, diluting holdings |
| Token | UNVERIFIED_CONTRACT |
🟠 HIGH | No verified source code — unauditable |
| Token | OWNERSHIP_NOT_RENOUNCED |
🟡 MEDIUM | Admin controls remain with deployer |
| Token | LOW_HOLDER_COUNT |
🟡 MEDIUM | Centralized distribution — rug-pull precursor |
| TX Sim | TX_SIMULATION_REVERTED |
🔴 CRITICAL | Transaction will fail on-chain — 100% wasted gas |
| TX Sim | HIGH_PRICE_IMPACT |
🟠 HIGH | Slippage beyond your tolerance |
| TX Sim | UNEXPECTED_STATE_CHANGE |
🟠 HIGH | OKX cross-validation flagged suspicious transaction behavior |
| TX Sim | GAS_ESTIMATION_FAILED |
🟡 MEDIUM | Elevated gas cost or estimation failure |
| MEV | FRONTRUN_RISK_HIGH |
🟠 HIGH | Slippage tolerance makes this trade profitable for sandwich bots |
| AMM | AMM_THIN_LIQUIDITY |
🔴 CRITICAL | Zero or near-zero liquidity at execution price |
| AMM | AMM_TICK_GAP_MANIPULATION |
🟠 HIGH | Price cliff created by strategic liquidity removal |
| AMM | AMM_PRICE_DEVIATION |
🟡 MEDIUM | Pool price deviates from its theoretical fair value |
| AMM | AMM_ONESIDED_LIQUIDITY |
🟡 MEDIUM | Asymmetric liquidity — coordinated extraction signal |
guardian-protocol/
├── src/
│ ├── index.ts # Orchestrator — evaluateTrade(), scanToken(), simulateTx()
│ ├── cli.ts # Agent CLI — JSON-only output, 3 commands
│ ├── analyzers/
│ │ ├── token-risk.ts # OKX + GoPlus dual-oracle honeypot/tax/blacklist detection
│ │ ├── tx-simulation.ts # eth_call dry-run + OKX cross-validation
│ │ ├── mev-detection.ts # Deterministic trade-impact heuristic + dynamic slippage caps
│ │ └── amm-pool-analyzer.ts # On-chain concentrated liquidity pool state analysis
│ ├── scoring/
│ │ ├── risk-engine.ts # Weighted aggregation + penalty cascades + correlation detection
│ │ └── thresholds.ts # Configurable weights (30/30/15/25) + all policy thresholds
│ ├── services/
│ │ ├── okx-security-client.ts # HMAC-SHA256 signed OKX API v5 client + LRU cache
│ │ └── xlayer-rpc-client.ts # Round-robin RPC manager (3 endpoints, 500ms failover)
│ ├── types/
│ │ ├── input.ts # GuardianEvaluationRequest schema
│ │ ├── output.ts # GuardianEvaluationResponse + SafetyScore + RiskFlagCodes
│ │ ├── internal.ts # AnalyzerResult inter-module contract
│ │ └── okx-api.ts # OKX API response type definitions
│ └── utils/
│ ├── errors.ts # GuardianError + structured error codes
│ ├── logger.ts # Structured JSON logger (stdout/stderr separation)
│ └── hex.ts # Hex validation + utilities
├── tests/unit/
│ ├── analyzers/ # 45 analyzer unit tests
│ └── scoring/ # 27 risk engine / scoring tests
├── scripts/
│ └── live-fire.ts # End-to-end mainnet demo (X Layer 196)
├── CHANGELOG.md # Version history
├── LIVE_FIRE_LOG.txt # Actual live fire output from X Layer Mainnet (Chain ID 196)
├── SKILL.md # OnchainOS skill metadata
├── USAGE.md # Integration guide
└── MOLTBOOK_PITCH.md # Hackathon submission
| Variable | Required | Description |
|---|---|---|
OKX_API_KEY |
✅ | OKX OnchainOS API key |
OKX_SECRET_KEY |
✅ | HMAC-SHA256 signing secret |
OKX_PASSPHRASE |
✅ | Account passphrase |
OKX_PROJECT_ID |
✅ | OKX project identifier |
XLAYER_RPC_URL |
➖ | Primary RPC (default: https://rpc.xlayer.tech) |
XLAYER_RPC_URL_2 |
➖ | Secondary RPC for failover |
XLAYER_RPC_URL_3 |
➖ | Tertiary RPC for failover |
GUARDIAN_SAFETY_THRESHOLD |
➖ | Override block threshold (default: 70) |
GUARDIAN_MAX_SLIPPAGE_BPS |
➖ | Max allowed slippage in bps (default: 500) |
GUARDIAN_TX_SIMULATION_TIMEOUT_MS |
➖ | Simulation timeout (default: 10000) |
GUARDIAN_RPC_ENDPOINT_TIMEOUT_MS |
➖ | Per-endpoint failover budget (default: 500) |
See CHANGELOG.md for full history.
- 🆕 Dual-oracle token scanning — OKX Security API + GoPlus Security cross-validation
- 🆕 AMM Pool Analyzer — On-chain concentrated liquidity manipulation detection (4th engine)
- 🆕 RPC Redundancy — 3-endpoint round-robin with health-based failover
- 🆕 TX Simulation Cross-Validation — eth_call + OKX transaction-scan dual verification
- 🆕 Dynamic Slippage Caps — Computed deterministically based on trade size in USD
- 🆕 Risk Engine Rebalancing — 4-analyzer weights (30/30/15/25)
- 🆕 Cross-Analyzer Correlations — 3 compound penalty detectors
- 🆕 72 tests — Up from 50, all passing
- Token risk, TX simulation, MEV detection, risk engine, CLI, live fire demo
This is our Skill Arena submission. Guardian Protocol demonstrates what a real, reusable, production-hardened agent skill looks like:
- Modular — Three exposed functions (
evaluateTrade,scanToken,simulateTx) composable as any agent needs - Machine-readable — All output is structured JSON. No human in the loop required.
- Fail-safe — The default state is blocked. Safety requires active confirmation.
- OKX-native — Built on OKX Security APIs, targeting X Layer, using OKX infrastructure as the trust anchor
- Tested — 72 tests. Not demo tests. Adversarial tests.
- Real on-chain activity — Verified against X Layer Mainnet (Chain ID 196). See
LIVE_FIRE_LOG.txt.
0x6e9fb08755b837388a36ced22f26ed64240fb29c
X Layer Mainnet (Chain ID 196) — View on OKLink
0x93A3DB5645Cb21DBDfEAB3047Fe01D1A65a8F52F
X Layer Mainnet (Chain ID 196) — View on OKLink
- Telegram: @bitnormie01
See MOLTBOOK_PITCH.md for the full submission document.