AegisNet Documentation

Build and run guardrailed AI trading agents on Ethereum: ENS identities with onchain limits, Claude strategy planning, World ID approval for large trades, and 1inch SwapVM routing with an agent-gated Uniswap v4 hook.

Overview

Each agent gets a name under the root ENS name (for example agent1.aegisnet.eth) in AegisSubnameRegistry, with an owner, a whitelist of contracts it may call, a daily spending limit and an approval threshold. AegisExecutionManager enforces all of these onchain. Trades at or above the threshold pause until the owner proves they are a real human with World ID.

Users sign every onchain action with their own wallet. The backend never holds user keys: it plans strategies with Claude, verifies World ID proofs and signs the relayer attestation the contract trusts, and indexes contract events.

Quickstart

1. Install

cd contracts && npm install
cd ../backend && npm install
cp .env.example .env   # fill in RPC, relayer key, World ID app, optional Claude key
      

2. Test

cd contracts && npm test                # contract unit tests
cd ../backend && npm run test:e2e      # full user flow on a local chain (see README)
      

3. Run

cd backend
npm run build && npm start
# App, console and API on http://localhost:4000
      

4. Deploy

docker build -t aegisnet .
docker run -p 4000:4000 --env-file backend/.env -e NODE_ENV=production -v aegis-data:/app/data aegisnet
      

How a trade flows

1. Plan      POST /api/agent/propose            → Claude plan + encoded SwapVM calldata
2. Submit    agent wallet → requestExecution(adapter, calldata, valueUSD)
             · under the threshold: executes in the same transaction
             · at or above: ExecutionRequested(requiresBiometrics = true)
3. Verify    owner scans with World App (IDKit, signal = requestId)
             POST /api/worldid/attest           → relayer signature + per-request nullifier
4. Approve   owner wallet → verifyBiometricsWithRelayer(requestId, nullifier, signature)
5. Execute   owner wallet → executeVerifiedTransaction(requestId)
   or Cancel owner/agent wallet → cancelExecution(requestId)
      

Architecture

Browser (landing + console)
  ├─ wallet (EIP-6963) ──── signs ───► AegisSubnameRegistry · AegisExecutionManager · AegisUniswapV4Hook
  └─ World ID widget (IDKit)
        │
        ▼
Backend (Node/Express, one container)
  ├─ Claude planner  ─ plan only; calldata built by deterministic code
  ├─ World ID gate   ─ proof check · one human per owner · relayer signature
  └─ Chain indexer   ─ contract events → activity & agents
      

REST API

GET /api/health

Chain, relayer check, contracts, World ID settings, AI planner and indexer status.

{
  "status": "online",
  "network": "Sepolia",
  "relayer": { "address": "0x…", "matchesContract": true },
  "worldId": { "appId": "app_…", "action": "agent-high-value-auth", "verifyMode": "cloud" },
  "ai": { "enabled": true, "model": "claude-opus-5" },
  "indexer": { "cursor": 7234567, "synced": true },
  "contracts": { "AegisSubnameRegistry": "0x09Ff…4625", "AegisExecutionManager": "0xC65d…594c" }
}
        

POST /api/agent/propose

Plans a strategy for an agent and returns the calldata its wallet submits. Nothing is sent onchain. Rate limited.

// Request
{ "agentAddress": "0x…", "goalPrompt": "Swap USDC to ETH at the best price", "amountUSD": 2500 }

// Response (abridged)
{
  "proposal": {
    "planner": "claude", "summary": "Swap $2,500 of USDC into ETH via 1inch…",
    "strategyType": "split_swap", "requiresBiometric2FA": true,
    "authorization": { "isAllowed": true, "requiresBiometrics": true },
    "dailyLimit": { "limitUSD": 50000, "remainingUSD": 47250, "exceeds": false }
  },
  "targetContract": "0xc2CA…19f1",
  "encodedCallData": "0x…"
}
        

POST /api/worldid/attest

Takes the IDKit success result for a paused request. Checks the request onchain, verifies the proof with World's API, enforces one human per owner and the daily limit, and returns the attestation for verifyBiometricsWithRelayer. Rate limited.

// Request
{ "requestId": "0x…", "proof": "0x…", "merkle_root": "0x…", "nullifier_hash": "0x…", "verification_level": "device" }

// Response
{ "nullifierHash": "4417…", "signature": "0x…", "owner": "0x…", "newlyBound": false }
        

GET /api/execution/requests?agent=&owner=

Every request on the manager, built from chain events, with status PENDING_BIOMETRICS, BIOMETRICS_VERIFIED, EXECUTED or CANCELLED and all transaction hashes. POST /api/execution/refresh indexes the latest block right away.

GET /api/ens/permissions/:agent · /api/ens/agents?owner= · /api/ens/text-record/:node/:key

Live agent limits read from the registry, agents an address owns (from events), and ENSIP-26 text records. GET /api/uniswap/pools/:poolId reads hook gating.

POST Admin routes

For bots and scripts whose agent key is the backend wallet: /api/agent/execute, /api/ens/* writes, /api/execution/:id/execute|cancel and /api/uniswap/pools/gate. In production they need the x-api-key header (ADMIN_API_KEY) and are disabled without it.

Smart Contracts

AegisSubnameRegistry.sol

Agent identities, owners, whitelists, limits and ENSIP-26 text records. The caller of registerSubname becomes the owner.

function registerSubname(string subnameLabel, address agentAddress, uint256 biometricThresholdUSD, uint256 dailySpendingLimit) returns (bytes32);
function setTargetContractWhitelist(bytes32 node, address target, bool allowed);   // owner
function updateBiometricThreshold(bytes32 node, uint256 thresholdUSD);            // owner
function revokeSubname(bytes32 node);                                             // owner
function isAgentAuthorized(address agent, address target, uint256 valueUSD) view returns (bool, bool, bytes32);
      

AegisExecutionManager.sol

Checks the caller is an authorized agent, holds trades at or above the threshold, and executes after a relayer-attested World ID approval.

function requestExecution(address target, bytes callData, uint256 valueUSD) returns (bytes32 requestId, bool requiresBiometrics);
function verifyBiometricsWithRelayer(bytes32 requestId, uint256 nullifierHash, bytes signature);
function executeVerifiedTransaction(bytes32 requestId);
function cancelExecution(bytes32 requestId);   // owner, agent or protocol owner
      

AegisSwapVMAdapter.sol

Executes SwapVM instruction lists (only callable by the manager): 0x01 swap, 0x02 split route, 0x03 minimum-output check, 0x04 Uniswap v4 hop, 0x05/0x06 Aqua deposit and rebalance. Output amounts are computed by the adapter; routing into real DEX liquidity is on the roadmap.