From 45f2b29a4266af89b5cd6107c6598028d3382e42 Mon Sep 17 00:00:00 2001 From: Roman Date: Wed, 4 Feb 2026 19:53:05 +0700 Subject: [PATCH 1/3] feat: Add aegis402 blockchain security skill Blockchain security API for AI agents with pay-per-request pricing. Features: - Token honeypot detection ($0.01/check) - Transaction simulation ($0.05/tx) - Address poisoning detection ($0.005/check) - Multi-chain support (ETH, Base, Polygon, Arbitrum, etc.) - x402 payment protocol integration Use cases: - Trading bots needing pre-swap safety checks - DeFi automation with approval verification - AI hedge funds with portfolio protection - Wallet agents with transfer verification Website: https://aegis402.xyz Co-Authored-By: Claude Opus 4.5 --- aegis402/README.md | 38 +++++ aegis402/SKILL.md | 244 +++++++++++++++++++++++++++++++ aegis402/references/use-cases.md | 238 ++++++++++++++++++++++++++++++ 3 files changed, 520 insertions(+) create mode 100644 aegis402/README.md create mode 100644 aegis402/SKILL.md create mode 100644 aegis402/references/use-cases.md diff --git a/aegis402/README.md b/aegis402/README.md new file mode 100644 index 00000000..45b511ca --- /dev/null +++ b/aegis402/README.md @@ -0,0 +1,38 @@ +# Aegis402 Shield Protocol + +Blockchain security API for AI agents. Pay-per-request via x402 protocol. + +## What It Does + +- **Token Scanning** — Honeypot detection, rug pull warnings, trust scores +- **Transaction Simulation** — Preview balance changes before signing +- **Address Verification** — Detect poisoning attacks, known scam addresses + +## Quick Integration + +```typescript +import { x402Client, wrapFetchWithPayment } from '@x402/fetch'; +import { ExactEvmScheme } from '@x402/evm/exact/client'; + +const client = new x402Client().register('eip155:*', new ExactEvmScheme(wallet)); +const fetch402 = wrapFetchWithPayment(fetch, client); + +// Check token before buying +const { isHoneypot, trustScore } = await fetch402( + 'https://aegis402.xyz/v1/check-token/0x...?chain_id=8453' +).then(r => r.json()); +``` + +## Pricing + +| Endpoint | Price | +|----------|-------| +| `/v1/simulate-tx` | $0.05 | +| `/v1/check-token/:address` | $0.01 | +| `/v1/check-address/:address` | $0.005 | + +## Links + +- [Website](https://aegis402.xyz) +- [Full Documentation](./SKILL.md) +- [Use Cases](./references/use-cases.md) diff --git a/aegis402/SKILL.md b/aegis402/SKILL.md new file mode 100644 index 00000000..7575362c --- /dev/null +++ b/aegis402/SKILL.md @@ -0,0 +1,244 @@ +--- +name: aegis402 +description: Blockchain security API for AI agents. Use when the agent needs to verify token safety before buying, simulate transactions before signing, or check addresses for poisoning attacks. Provides automated on-chain threat detection with pay-per-request pricing via x402 protocol. +--- + +# Aegis402 Shield Protocol + +Blockchain security API for AI agents. Automated on-chain threat detection with pay-per-request pricing. + +**Website:** https://aegis402.xyz +**API Base:** `https://aegis402.xyz/v1` + +## When to Use This Skill + +Use Aegis402 when your agent needs to: +- **Check a token before buying** — Detect honeypots, rug pulls, high-risk tokens +- **Simulate a transaction before signing** — Preview balance changes, catch approval traps +- **Verify a recipient address** — Detect address poisoning, known scam addresses + +## Quick Start + +```typescript +import { x402Client, wrapFetchWithPayment } from '@x402/fetch'; +import { ExactEvmScheme } from '@x402/evm/exact/client'; + +const client = new x402Client() + .register('eip155:*', new ExactEvmScheme(yourEvmWallet)); + +const fetch402 = wrapFetchWithPayment(fetch, client); + +// Check if token is a honeypot before buying +const check = await fetch402('https://aegis402.xyz/v1/check-token/0x...?chain_id=8453'); +const { isHoneypot, trustScore } = await check.json(); + +if (isHoneypot || trustScore < 50) { + // ABORT — risky token detected +} +``` + +**Requirements:** USDC on Base Mainnet or Solana Mainnet for payments. + +--- + +## Pricing + +| Endpoint | Price | Use Case | +|----------|-------|----------| +| `POST /v1/simulate-tx` | $0.05 | Transaction simulation | +| `GET /v1/check-token/:address` | $0.01 | Token honeypot detection | +| `GET /v1/check-address/:address` | $0.005 | Address reputation check | + +--- + +## Endpoints + +### Check Token ($0.01) + +Scan any token for honeypots, scams, and risks before buying. + +```bash +curl "https://aegis402.xyz/v1/check-token/0xTokenAddress?chain_id=8453" +``` + +**Response:** +```json +{ + "address": "0x...", + "isHoneypot": false, + "trustScore": 95, + "risks": [] +} +``` + +### Check Address ($0.005) + +Verify if address is flagged for phishing or poisoning attacks. + +```bash +curl "https://aegis402.xyz/v1/check-address/0xRecipientAddress" +``` + +**Response:** +```json +{ + "address": "0x...", + "isPoisoned": false, + "reputation": "NEUTRAL", + "tags": ["wallet", "established"] +} +``` + +### Simulate Transaction ($0.05) + +Predict balance changes and detect threats before signing. + +```bash +curl -X POST "https://aegis402.xyz/v1/simulate-tx" \ + -H "Content-Type: application/json" \ + -d '{ + "from": "0xYourWallet", + "to": "0xContract", + "value": "1000000000000000000", + "data": "0x...", + "chain_id": 8453 + }' +``` + +**Response:** +```json +{ + "isSafe": true, + "riskLevel": "LOW", + "simulation": { + "balanceChanges": [ + { "asset": "USDC", "amount": "-100.00" } + ] + }, + "warnings": [] +} +``` + +--- + +## Integration Patterns + +### Pattern 1: Pre-Swap Safety Check + +Before executing any token swap: + +```typescript +async function safeSwap(tokenAddress: string, chain_id: number) { + // 1. Check token safety first + const tokenCheck = await fetch402( + `https://aegis402.xyz/v1/check-token/${tokenAddress}?chain_id=${chain_id}` + ); + const { isHoneypot, trustScore, risks } = await tokenCheck.json(); + + if (isHoneypot) { + throw new Error('HONEYPOT DETECTED — aborting swap'); + } + + if (trustScore < 50) { + throw new Error(`LOW TRUST SCORE (${trustScore}) — aborting swap`); + } + + // 2. Proceed with swap only if safe + return executeSwap(tokenAddress); +} +``` + +### Pattern 2: Transaction Simulation Before Signing + +Never sign without simulation: + +```typescript +async function safeSend(tx: Transaction) { + // 1. Simulate first + const simulation = await fetch402('https://aegis402.xyz/v1/simulate-tx', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(tx) + }); + + const { isSafe, riskLevel, warnings } = await simulation.json(); + + if (!isSafe || riskLevel === 'CRITICAL') { + throw new Error(`DANGEROUS TX: ${warnings.join(', ')}`); + } + + // 2. Only sign if simulation passes + return signAndSend(tx); +} +``` + +### Pattern 3: Address Verification Before Transfer + +Always verify recipient addresses: + +```typescript +async function safeTransfer(to: string, amount: bigint) { + // 1. Check for address poisoning + const addrCheck = await fetch402( + `https://aegis402.xyz/v1/check-address/${to}` + ); + const { isPoisoned, reputation } = await addrCheck.json(); + + if (isPoisoned) { + throw new Error('ADDRESS POISONING DETECTED — possible scam'); + } + + // 2. Transfer only to verified addresses + return transfer(to, amount); +} +``` + +--- + +## Risk Levels + +| Level | Meaning | Action | +|-------|---------|--------| +| `SAFE` | No issues detected | Proceed | +| `LOW` | Minor concerns | Proceed with caution | +| `MEDIUM` | Some risks | Review before proceeding | +| `HIGH` | Significant risks | Avoid unless necessary | +| `CRITICAL` | Do not proceed | ABORT | + +--- + +## Supported Chains + +| Chain | ID | check-token | check-address | simulate-tx | +|-------|-----|-------------|---------------|-------------| +| Ethereum | 1 | ✅ | ✅ | ✅ | +| Base | 8453 | ✅ | ✅ | ✅ | +| Polygon | 137 | ✅ | ✅ | ✅ | +| Arbitrum | 42161 | ✅ | ✅ | ✅ | +| Optimism | 10 | ✅ | ✅ | ✅ | +| BSC | 56 | ✅ | ✅ | ✅ | +| Avalanche | 43114 | ✅ | ✅ | ✅ | + +--- + +## Complementary with Local Guardrails + +Aegis402 provides **external verification** that complements client-side security rules: + +| Local Guardrails | Aegis402 API | +|-----------------|--------------| +| "Never approve unknown contracts" | → Verify contract risk before approval | +| "Simulate before signing" | → Provides the simulation | +| "Check destination addresses" | → Detects poisoning attacks | +| "Validate token before buying" | → Honeypot detection | + +Use both for defense in depth. + +--- + +## Links + +- **Website**: https://aegis402.xyz +- **API Docs**: https://aegis402.xyz/api.html +- **Demo**: https://aegis402.xyz/demo.html +- **x402 Protocol**: https://docs.x402.org diff --git a/aegis402/references/use-cases.md b/aegis402/references/use-cases.md new file mode 100644 index 00000000..0f47301c --- /dev/null +++ b/aegis402/references/use-cases.md @@ -0,0 +1,238 @@ +# Aegis402 Use Cases for AI Agents + +## The Problem + +Meme coin lifecycle: 15 minutes. Agent decision time: 100ms. Human reaction time: too slow. + +Without security verification: +1. Agent sees hype around $SCAM69 +2. Agent analyzes sentiment, sees liquidity, buys +3. Agent doesn't see: honeypot code, hidden `renounceOwnership`, team allocation +4. Result: -$50,000 in one transaction + +## Solution: Pre-Execution Security Layer + +Aegis402 adds a security check between "decide to trade" and "sign transaction". + +``` +Agent Decision → Aegis402 Check → Safe? → Execute + ↓ + Risky? → Abort +``` + +--- + +## Use Case 1: Trading Bots + +### Before Buying Any Token + +```typescript +async function buyToken(address: string, chain_id: number) { + // Security gate: check before buying + const { isHoneypot, trustScore, risks } = await fetch402( + `https://aegis402.xyz/v1/check-token/${address}?chain_id=${chain_id}` + ).then(r => r.json()); + + if (isHoneypot) { + log('BLOCKED: Honeypot detected'); + return null; + } + + if (trustScore < 60) { + log(`BLOCKED: Low trust score (${trustScore})`); + return null; + } + + // Safe to proceed + return executeBuy(address); +} +``` + +### Spending Tier Integration + +Combine with spending limits for layered security: + +```typescript +const TIERS = { + auto: 50, // < $50 — auto-execute after Aegis check + notify: 500, // $50-500 — notify human after Aegis check + approval: Infinity // > $500 — require human approval +}; + +async function tieredTrade(amount: number, tx: Transaction) { + // Always run Aegis check first + const { isSafe, riskLevel } = await fetch402('https://aegis402.xyz/v1/simulate-tx', { + method: 'POST', + body: JSON.stringify(tx) + }).then(r => r.json()); + + if (!isSafe) { + return { status: 'blocked', reason: 'Aegis security check failed' }; + } + + // Apply spending tier rules + if (amount > TIERS.approval) { + return { status: 'pending_approval', tx }; + } + + if (amount > TIERS.auto) { + notifyHuman(`Trade $${amount}: ${tx.to}`); + } + + return executeTrade(tx); +} +``` + +--- + +## Use Case 2: DeFi Automation + +### Safe Approval Flow + +```typescript +async function safeApprove(token: string, spender: string, amount: bigint) { + // 1. Check the spender contract + const { isPoisoned, reputation } = await fetch402( + `https://aegis402.xyz/v1/check-address/${spender}` + ).then(r => r.json()); + + if (isPoisoned || reputation === 'MALICIOUS') { + throw new Error('Refusing to approve malicious spender'); + } + + // 2. Simulate the approval + const { isSafe, warnings } = await fetch402('https://aegis402.xyz/v1/simulate-tx', { + method: 'POST', + body: JSON.stringify({ + from: wallet, + to: token, + data: encodeApproval(spender, amount), + chain_id: 8453 + }) + }).then(r => r.json()); + + if (!isSafe) { + throw new Error(`Unsafe approval: ${warnings.join(', ')}`); + } + + // 3. Execute with exact amount (never unlimited) + return approve(token, spender, amount); +} +``` + +--- + +## Use Case 3: Wallet Agents + +### Transfer Verification + +```typescript +async function sendTokens(to: string, amount: bigint, token: string) { + // Check recipient for address poisoning + const { isPoisoned } = await fetch402( + `https://aegis402.xyz/v1/check-address/${to}` + ).then(r => r.json()); + + if (isPoisoned) { + // Could be address poisoning attack + throw new Error('Recipient flagged as poisoned address'); + } + + return transfer(to, amount, token); +} +``` + +--- + +## Use Case 4: AI Hedge Funds + +### Portfolio Protection + +```typescript +class SecurePortfolioManager { + async rebalance(trades: Trade[]) { + const safeResults = await Promise.all( + trades.map(async (trade) => { + // Run security check on each trade + const simulation = await fetch402('https://aegis402.xyz/v1/simulate-tx', { + method: 'POST', + body: JSON.stringify(trade.tx) + }).then(r => r.json()); + + return { + trade, + safe: simulation.isSafe, + risk: simulation.riskLevel, + warnings: simulation.warnings + }; + }) + ); + + // Only execute safe trades + const safeTrades = safeResults.filter(r => r.safe); + const blockedTrades = safeResults.filter(r => !r.safe); + + if (blockedTrades.length > 0) { + alertRiskTeam(blockedTrades); + } + + return executeTrades(safeTrades.map(r => r.trade)); + } +} +``` + +--- + +## Integration with Agent Frameworks + +### ElizaOS Plugin + +```typescript +// plugins/aegis402.ts +import { Plugin } from '@elizaos/core'; + +export const aegis402Plugin: Plugin = { + name: 'aegis402', + actions: [ + { + name: 'CHECK_TOKEN_SAFETY', + handler: async (runtime, message) => { + const { address, chain_id } = message.content; + const result = await runtime.fetch402( + `https://aegis402.xyz/v1/check-token/${address}?chain_id=${chain_id}` + ); + return result.json(); + } + } + ] +}; +``` + +--- + +## Cost Analysis + +For a trading bot making 100 trades/day: + +| Check Type | Per Trade | Daily Cost | +|------------|-----------|------------| +| Token check only | $0.01 | $1.00 | +| Token + Simulation | $0.06 | $6.00 | +| Full (token + sim + address) | $0.065 | $6.50 | + +**ROI**: One prevented rug pull ($5,000+) = 770+ days of protection costs. + +--- + +## Health Check (Free) + +```bash +curl https://aegis402.xyz/health +``` + +```json +{ + "status": "healthy", + "circuitBreaker": { "state": "CLOSED" } +} +``` From 99c9e6e22e5ad852b99092f7f8569fa6a33f0f74 Mon Sep 17 00:00:00 2001 From: Roman Date: Wed, 4 Feb 2026 20:06:17 +0700 Subject: [PATCH 2/3] chore: Remove use-cases reference file --- aegis402/references/use-cases.md | 238 ------------------------------- 1 file changed, 238 deletions(-) delete mode 100644 aegis402/references/use-cases.md diff --git a/aegis402/references/use-cases.md b/aegis402/references/use-cases.md deleted file mode 100644 index 0f47301c..00000000 --- a/aegis402/references/use-cases.md +++ /dev/null @@ -1,238 +0,0 @@ -# Aegis402 Use Cases for AI Agents - -## The Problem - -Meme coin lifecycle: 15 minutes. Agent decision time: 100ms. Human reaction time: too slow. - -Without security verification: -1. Agent sees hype around $SCAM69 -2. Agent analyzes sentiment, sees liquidity, buys -3. Agent doesn't see: honeypot code, hidden `renounceOwnership`, team allocation -4. Result: -$50,000 in one transaction - -## Solution: Pre-Execution Security Layer - -Aegis402 adds a security check between "decide to trade" and "sign transaction". - -``` -Agent Decision → Aegis402 Check → Safe? → Execute - ↓ - Risky? → Abort -``` - ---- - -## Use Case 1: Trading Bots - -### Before Buying Any Token - -```typescript -async function buyToken(address: string, chain_id: number) { - // Security gate: check before buying - const { isHoneypot, trustScore, risks } = await fetch402( - `https://aegis402.xyz/v1/check-token/${address}?chain_id=${chain_id}` - ).then(r => r.json()); - - if (isHoneypot) { - log('BLOCKED: Honeypot detected'); - return null; - } - - if (trustScore < 60) { - log(`BLOCKED: Low trust score (${trustScore})`); - return null; - } - - // Safe to proceed - return executeBuy(address); -} -``` - -### Spending Tier Integration - -Combine with spending limits for layered security: - -```typescript -const TIERS = { - auto: 50, // < $50 — auto-execute after Aegis check - notify: 500, // $50-500 — notify human after Aegis check - approval: Infinity // > $500 — require human approval -}; - -async function tieredTrade(amount: number, tx: Transaction) { - // Always run Aegis check first - const { isSafe, riskLevel } = await fetch402('https://aegis402.xyz/v1/simulate-tx', { - method: 'POST', - body: JSON.stringify(tx) - }).then(r => r.json()); - - if (!isSafe) { - return { status: 'blocked', reason: 'Aegis security check failed' }; - } - - // Apply spending tier rules - if (amount > TIERS.approval) { - return { status: 'pending_approval', tx }; - } - - if (amount > TIERS.auto) { - notifyHuman(`Trade $${amount}: ${tx.to}`); - } - - return executeTrade(tx); -} -``` - ---- - -## Use Case 2: DeFi Automation - -### Safe Approval Flow - -```typescript -async function safeApprove(token: string, spender: string, amount: bigint) { - // 1. Check the spender contract - const { isPoisoned, reputation } = await fetch402( - `https://aegis402.xyz/v1/check-address/${spender}` - ).then(r => r.json()); - - if (isPoisoned || reputation === 'MALICIOUS') { - throw new Error('Refusing to approve malicious spender'); - } - - // 2. Simulate the approval - const { isSafe, warnings } = await fetch402('https://aegis402.xyz/v1/simulate-tx', { - method: 'POST', - body: JSON.stringify({ - from: wallet, - to: token, - data: encodeApproval(spender, amount), - chain_id: 8453 - }) - }).then(r => r.json()); - - if (!isSafe) { - throw new Error(`Unsafe approval: ${warnings.join(', ')}`); - } - - // 3. Execute with exact amount (never unlimited) - return approve(token, spender, amount); -} -``` - ---- - -## Use Case 3: Wallet Agents - -### Transfer Verification - -```typescript -async function sendTokens(to: string, amount: bigint, token: string) { - // Check recipient for address poisoning - const { isPoisoned } = await fetch402( - `https://aegis402.xyz/v1/check-address/${to}` - ).then(r => r.json()); - - if (isPoisoned) { - // Could be address poisoning attack - throw new Error('Recipient flagged as poisoned address'); - } - - return transfer(to, amount, token); -} -``` - ---- - -## Use Case 4: AI Hedge Funds - -### Portfolio Protection - -```typescript -class SecurePortfolioManager { - async rebalance(trades: Trade[]) { - const safeResults = await Promise.all( - trades.map(async (trade) => { - // Run security check on each trade - const simulation = await fetch402('https://aegis402.xyz/v1/simulate-tx', { - method: 'POST', - body: JSON.stringify(trade.tx) - }).then(r => r.json()); - - return { - trade, - safe: simulation.isSafe, - risk: simulation.riskLevel, - warnings: simulation.warnings - }; - }) - ); - - // Only execute safe trades - const safeTrades = safeResults.filter(r => r.safe); - const blockedTrades = safeResults.filter(r => !r.safe); - - if (blockedTrades.length > 0) { - alertRiskTeam(blockedTrades); - } - - return executeTrades(safeTrades.map(r => r.trade)); - } -} -``` - ---- - -## Integration with Agent Frameworks - -### ElizaOS Plugin - -```typescript -// plugins/aegis402.ts -import { Plugin } from '@elizaos/core'; - -export const aegis402Plugin: Plugin = { - name: 'aegis402', - actions: [ - { - name: 'CHECK_TOKEN_SAFETY', - handler: async (runtime, message) => { - const { address, chain_id } = message.content; - const result = await runtime.fetch402( - `https://aegis402.xyz/v1/check-token/${address}?chain_id=${chain_id}` - ); - return result.json(); - } - } - ] -}; -``` - ---- - -## Cost Analysis - -For a trading bot making 100 trades/day: - -| Check Type | Per Trade | Daily Cost | -|------------|-----------|------------| -| Token check only | $0.01 | $1.00 | -| Token + Simulation | $0.06 | $6.00 | -| Full (token + sim + address) | $0.065 | $6.50 | - -**ROI**: One prevented rug pull ($5,000+) = 770+ days of protection costs. - ---- - -## Health Check (Free) - -```bash -curl https://aegis402.xyz/health -``` - -```json -{ - "status": "healthy", - "circuitBreaker": { "state": "CLOSED" } -} -``` From 56f5194cc23993dd9b76caed34176500792197b5 Mon Sep 17 00:00:00 2001 From: Roman Date: Wed, 4 Feb 2026 20:06:31 +0700 Subject: [PATCH 3/3] chore: Update README to remove use-cases link --- aegis402/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/aegis402/README.md b/aegis402/README.md index 45b511ca..3123abf0 100644 --- a/aegis402/README.md +++ b/aegis402/README.md @@ -35,4 +35,3 @@ const { isHoneypot, trustScore } = await fetch402( - [Website](https://aegis402.xyz) - [Full Documentation](./SKILL.md) -- [Use Cases](./references/use-cases.md)