API Reference

Aegis402 Shield Protocol

Pay-per-request blockchain security API. Scan tokens, simulate transactions, and verify addresses before funds move. Payments are automatic via x402 — USDC on Base or Solana, no account required.

Base URL: https://aegis402.com/v1

Quick Start

Install an x402-enabled HTTP client, point it at any endpoint, and payment is handled automatically when the free tier is exhausted.

100 free checks/day — no payment setup required to get started.

Set X-Client-Fingerprint: <stable-agent-id> for predictable free-tier accounting. After the daily limit, the API returns 402 and an x402 client pays automatically.

Install & call your first endpoint
// Install
npm install @x402/[email protected] @x402/[email protected]

// Usage — payments on Base (EVM)
import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm/exact/client';

// yourEvmSigner: any viem/ethers/web3 wallet signer
const client = new x402Client()
  .register('eip155:*', new ExactEvmScheme(yourEvmSigner));

const fetch402 = wrapFetchWithPayment(fetch, client);

// Check a token — $0.01 USDC, paid automatically
const res = await fetch402(
  'https://aegis402.com/v1/check-token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48?chain_id=1',
  { headers: { 'X-Client-Fingerprint': 'my-agent-v1' } }
);
const data = await res.json();
console.log(data);
// Install
npm install @x402/[email protected] @x402/[email protected]

// Usage — payments on Solana
import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { ExactSvmScheme } from '@x402/svm/exact/client';

// yourSolanaSigner: any Solana wallet adapter signer
const client = new x402Client()
  .register('solana:*', new ExactSvmScheme(yourSolanaSigner));

const fetch402 = wrapFetchWithPayment(fetch, client);

// Scan a Solana token
const res = await fetch402(
  'https://aegis402.com/v1/check-token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
);
const data = await res.json();
console.log(data);
# Install
pip install x402[httpx]

# Usage
from x402 import x402Client
from x402.http.clients import x402HttpxClient

client = x402Client()  # configure signer per x402 Python docs

async with x402HttpxClient(client) as http:
    res = await http.get(
        'https://aegis402.com/v1/check-token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
        params={'chain_id': 1},
        headers={'X-Client-Fingerprint': 'my-agent-v1'}
    )
    print(res.json())
# Within the free tier (100 checks/day), no payment needed
curl "https://aegis402.com/v1/check-token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48?chain_id=1" \
  -H "X-Client-Fingerprint: my-agent-v1"

# Check usage
curl "https://aegis402.com/v1/usage"

# Health check
curl "https://aegis402.com/health"

Full x402 client guide: docs.x402.org/quickstart-for-buyers

How x402 Works

x402 is an open HTTP payment standard. No API keys, no subscriptions — pay per call in USDC.

1
Request
Your client calls the endpoint
→
2
402 Response
Server returns payment details (amount, network, address)
→
3
Pay USDC
x402 client signs & submits on-chain payment
→
4
200 Response
Server verifies payment and returns data

Payment networks: Base (EVM) for MetaMask / Coinbase Wallet — Solana for Phantom / Solflare. Currency: USDC on both networks. Learn more at x402.org.

Free Tier

Each unique client fingerprint gets 100 free checks per calendar day (UTC reset). Track usage with the /usage endpoint — it's always free.

GET /v1/usage — example response
{
  "freeTier": {
    "enabled": true,
    "dailyLimit": 100,
    "usedToday": 12,
    "remainingChecks": 88,
    "nextResetAt": "2026-02-27T00:00:00.000Z",
    "resetTimezone": "UTC"
  },
  "_meta": {
    "requestId": "a1b2c3d4-e5f6-...",
    "tier": "free",
    "eventType": "free_tier_call",
    "latencyMs": 4
  }
}
POST /v1/simulate-tx $0.05 USDC / call

Smart Transaction Guard

Simulates a transaction against current blockchain state to predict balance changes and detect threats — drainers, honeypots, malicious approvals. Run this before any eth_sendTransaction.

Request Body

Parameter Type Required Description
from string required Sender EVM address (0x-prefixed, 40 hex chars)
to string required Recipient or contract EVM address
value string required Amount in wei as decimal or hex string. Use "0" for token calls.
data string optional Transaction calldata as hex string. Defaults to "0x".
chain_id number optional Chain to simulate on. Default: 1 (Ethereum). See supported chains below.

Example Request

curl -X POST "https://aegis402.com/v1/simulate-tx" \
  -H "Content-Type: application/json" \
  -H "X-Client-Fingerprint: my-agent-v1" \
  -d '{
    "from":     "0xYourWalletAddress0000000000000000000000",
    "to":       "0xContractOrRecipientAddress0000000000000",
    "value":    "0",
    "data":     "0xa9059cbb000000000000000000000000...",
    "chain_id": 8453
  }'
const res = await fetch402('https://aegis402.com/v1/simulate-tx', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Fingerprint': 'my-agent-v1'
  },
  body: JSON.stringify({
    from:     '0xYourWalletAddress0000000000000000000000',
    to:       '0xContractOrRecipientAddress0000000000000',
    value:    '0',
    data:     '0xa9059cbb...',
    chain_id: 8453
  })
});
const scan = await res.json();

Response (200 OK)

{
  "isSafe": false,
  "riskLevel": "CRITICAL",
  "simulation": {
    // Raw assetsMovement from Web3Antivirus — token transfers, approvals, ETH flows
    "tokens": [
      {
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "symbol": "USDC",
        "amount": "-1000.00",
        "direction": "out"
      }
    ]
  },
  "warnings": [
    "Contract has unlimited approval drainer pattern",
    "Recipient flagged for phishing"
  ],
  "_meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tier": "paid",
    "eventType": "paid_call",
    "latencyMs": 312
  }
}

Response Fields

isSafe boolean
true when no detectors triggered. Block transaction if false.
riskLevel string
SAFE / LOW — allow. MEDIUM — show review. HIGH — confirm required. CRITICAL — block.
simulation object
Raw asset movement data from the simulation engine — token transfers, approvals, ETH flow changes.
warnings string[]
Human-readable descriptions of each detector that fired. Empty array when safe.
_meta.requestId string
Stable UUID for this request. Include in bug reports. Also set as x-request-id response header.
_meta.latencyMs number
Total server-side latency in milliseconds.
GET /v1/check-token/:address $0.01 USDC / call

Token Vetting API

Checks an ERC-20 or Solana token for honeypot logic, malicious ownership, trading restrictions, and known scam patterns. Supports both EVM addresses (0x...) and Solana addresses (base58).

Path Parameters

Parameter Type Required Description
address string required Token contract address. EVM: 0x-prefixed. Solana: base58 format.

Query Parameters

Parameter Type Required Description
chain_id number optional Chain to scan. Default: 1 (Ethereum). Auto-detected as solana for Solana addresses. See supported chains.

Example Request

# EVM token (USDC on Ethereum)
curl "https://aegis402.com/v1/check-token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48?chain_id=1"

# Solana token (address auto-detected)
curl "https://aegis402.com/v1/check-token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
const tokenAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
const res = await fetch402(
  `https://aegis402.com/v1/check-token/${tokenAddress}?chain_id=1`,
  { headers: { 'X-Client-Fingerprint': 'my-agent-v1' } }
);
const token = await res.json();

Response (200 OK)

{
  // Raw Web3Antivirus token intelligence response
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "isHoneypot": false,
  "risks": [],
  "_meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tier": "paid",
    "eventType": "paid_call",
    "latencyMs": 187
  }
}

Response Fields

address string
The token address that was scanned.
isHoneypot boolean
Whether the token contract has honeypot mechanics (buy-only, sell blocked).
risks array
Array of risk objects from the intelligence engine. Each contains a code and description of the detected issue.
_meta.requestId string
Stable UUID for this request. Also set as x-request-id response header.
GET /v1/check-address/:address $0.005 USDC / call

Address Hygiene

Checks a wallet or contract address for toxic score, poisoning attacks, phishing association, and known exploit involvement. Supports EVM (0x...) and Solana (base58) addresses.

Path Parameters

Parameter Type Required Description
address string required Wallet or contract address. EVM: 0x-prefixed. Solana: base58. Chain is auto-detected from address format.

Example Request

# EVM address
curl "https://aegis402.com/v1/check-address/0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

# Solana address
curl "https://aegis402.com/v1/check-address/9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
const recipientAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
const res = await fetch402(
  `https://aegis402.com/v1/check-address/${recipientAddress}`
);
const scan = await res.json();

// Block if address looks suspicious
if (scan.toxicScore > 50) {
  console.warn('High-risk address detected!');
}

Response (200 OK)

{
  // Raw Web3Antivirus toxic-score response
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "toxicScore": 0,
  "isPoisoned": false,
  "risks": [],
  "_meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tier": "paid",
    "eventType": "paid_call",
    "latencyMs": 95
  }
}

Response Fields

address string
The address that was checked.
toxicScore number
0–100 toxicity score from the Web3Antivirus engine. Higher is more dangerous. Scores above 50 should trigger confirmation.
isPoisoned boolean
Whether the address matches known address-poisoning attack patterns (visually similar to a real address).
risks array
Array of risk classification objects from the intelligence engine.
_meta.requestId string
Stable UUID. Also in x-request-id response header.
GET /v1/usage Free

Free Tier Usage

Returns the current free-tier usage snapshot for the calling fingerprint. Always free — call before paid endpoints to decide whether to use an x402 client.

Example Request

curl "https://aegis402.com/v1/usage" \
  -H "X-Client-Fingerprint: my-agent-v1"

Response Fields

freeTier.dailyLimit number
Maximum free checks per day (currently 100).
freeTier.usedToday number
Checks consumed today for this fingerprint.
freeTier.remainingChecks number
Checks remaining until x402 kicks in.
freeTier.nextResetAt string (ISO 8601)
Timestamp of next UTC midnight reset.

Supported Chains

chain_id refers to the chain being scanned, not the payment rail. Payment is always USDC on Base or Solana regardless of what chain you are scanning.

Chain chain_id check-token check-address simulate-tx
Ethereum 1 Yes Yes Yes
Base 8453 Yes Yes Yes
Polygon 137 Yes Yes Yes
Arbitrum 42161 Yes Yes Yes
Optimism 10 Yes Yes Yes
BSC 56 Yes Yes Yes
Avalanche 43114 Yes Yes Yes
Solana solana (auto) Yes Yes No

Errors

All error responses follow the same shape: { error, details?, _meta }. The _meta.requestId field is always present — include it in bug reports.

Status Meaning What to do
400 Invalid or missing parameters Check required fields. from/to must be valid hex addresses. value is required.
402 Payment Required — free tier exhausted Use an x402 client with a funded wallet. Or wait for UTC midnight reset.
500 / 502 Upstream service error Retry once with exponential backoff. If persistent, report with requestId.
503 Circuit breaker open — upstream unavailable Wait 30 seconds and retry.
504 Upstream timeout Retry. If consistent, check health endpoint.
Example error response
{
  "error": "Missing required parameters: from, to, value",
  "_meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "latencyMs": 2
  }
}

Feedback Endpoint

Report issues or false positives. Always free. Do not include private keys or seed phrases.

POST /v1/feedback
curl -X POST "https://aegis402.com/v1/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "kind":      "issue",
    "summary":   "False positive on safe token",
    "expected":  "Token should scan as safe",
    "happened":  "Got isHoneypot: true",
    "repro":     "GET /v1/check-token/0x... chain_id=1",
    "endpoint":  "/v1/check-token/0x...",
    "status_code": 200,
    "chain_id":  "1",
    "agent":     { "name": "my-agent", "version": "1.0.0" },
    "extra":     { "failed_request_id": "a1b2c3d4-..." }
  }'

kind must be one of: issue, feedback, expectation. Community: t.me/aegis402_chat