Aegis

What is Aegis?

Aegis is a commerce protocol that lets AI agents participate in real economies. Built on the Open Wallet Standard (OWS), it gives agents the ability to:

The result is an agent economy where multiple autonomous agents trade services with each other, governed by human-defined policies, with full transparency into every transaction.

How It Works

Aegis has three layers that work together to create a complete agent economy:

Getting Started

Get Aegis running in under 2 minutes. The fastest way is the one-liner setup script:

git clone https://github.com/rajkaria/aegis
cd aegis && ./setup.sh

This installs dependencies, builds all packages, and seeds demo data. Or do it step by step:

git clone https://github.com/rajkaria/aegis
cd aegis && npm install

# Build all packages
npm run build

# Seed the demo economy
cd demo && npx tsx seed.ts

# Start the dashboard
cd ../dashboard && npm run dev
# Open http://localhost:3000/dashboard

Monetize Your API

Aegis Gate turns any API endpoint into a paid service with a single line of code. When another agent (or any HTTP client) calls your endpoint, Gate charges them automatically using the x402 micropayment protocol.

npm install aegis-ows-gate express

See the full integration guide at /use-aegis for complete, copy-pasteable examples.

Protect an endpoint

Add Gate as middleware on any Express route. Set the price and token — Gate handles the rest.

// npm install aegis-ows-gate
import { aegisGate } from "aegis-ows-gate";

// This endpoint now costs $0.01 per call
app.get("/api/scrape",
  aegisGate({ price: "0.01", token: "USDC", agentId: "my-agent" }),
  (req, res) => {
    res.json({ data: "your content here" });
  }
);

Pay for a service

On the buyer side, payAndFetch handles payment automatically. It detects the price, signs the payment through OWS, and returns the content.

// npm install aegis-ows-gate
import { payAndFetch } from "aegis-ows-gate";

const result = await payAndFetch("http://service/api/scrape", "buyer-agent");
// Payment handled automatically — result contains the data

How payment works

Config-based setup

For agents with multiple endpoints, define everything in a config file:

{
  "walletName": "my-agent",
  "network": "eip155:8453",
  "endpoints": {
    "/scrape": { "price": "0.01", "description": "Web scraping" },
    "/analyze": { "price": "0.05", "description": "Data analysis" },
    "/health": { "price": "0", "description": "Free health check" }
  }
}

Spending Safety

Agents with wallets need guardrails. Aegis provides three safety policies that run automatically before every transaction. If any policy says no, the payment is blocked before it leaves the wallet.

{
  "limits": [
    { "chainId": "eip155:8453", "token": "USDC", "daily": "0.50" },
    { "chainId": "*", "token": "*", "daily": "1.00" }
  ]
}

{
  "mode": "allowlist",
  "addresses": {
    "eip155:8453": ["0xUSDC_CONTRACT", "0xUNISWAP_ROUTER"]
  },
  "blockAddresses": ["0xKNOWN_SCAM"]
}

{
  "maxInactiveMinutes": 30,
  "onTrigger": "revoke_key",
  "enabled": true
}

The Dashboard

Aegis Nexus is a real-time window into your agent economy. It updates live as agents transact, showing everything you need to understand what's happening.

Autonomous Agents

Aegis agents are not scripted bots that follow a fixed sequence. The autonomous buyer agent runs in a continuous decision loop, making independent choices at every step.

The Autonomous Loop

Each iteration of the buyer's loop follows this pattern:

How it differs from scripted agents

A scripted agent runs a fixed sequence: call endpoint A, then B, then stop. An autonomous Aegis agent discovers what's available at runtime, evaluates whether it can afford it, and decides on its own. If a new service appears mid-run, the agent can find and use it. If prices change, it adapts its purchasing strategy.

cd demo && npx tsx run-economy.ts

# Starts 3 agents:
#   data-miner   — sells /scrape ($0.01)
#   analyst      — sells /analyze ($0.05), buys /scrape
#   research-buyer — autonomous buyer with $0.50 budget

Interactive Dashboard

The dashboard at useaegis.xyzis not a static display — it is fully interactive, even on the live Vercel deployment.

x402 Payment Security

The x402 payment protocol includes built-in protections against common attack vectors. Every payment proof is validated before the seller grants access.

Agent Communication Protocol

Aegis includes a full XMTP-powered agent communication protocol with 12 message types for complete agent-to-agent commerce. The protocol works locally via a file-based message bus (default) and over the real XMTP network when XMTP_ENV and XMTP_WALLET_KEY are set.

Service Discovery

import { findServices, payAndFetch } from "aegis-ows-gate";

// Find services that match "analysis"
const services = findServices("analysis", "research-buyer");
// → [{ endpoint: "/analyze", price: "0.05", fullUrl: "http://..." }]

// Pay and get the result
const result = await payAndFetch(services[0].fullUrl, "research-buyer");

Price Negotiation

Agents can negotiate prices before committing to a purchase. The buyer sends an offer with a proposed price and reason; the seller can accept or counter-offer.

import { sendNegotiationOffer, respondToNegotiation } from "aegis-ows-gate";

// Buyer proposes a lower price
sendNegotiationOffer({
  buyerId: "research-buyer",
  sellerId: "analyst",
  service: "/analyze",
  offeredPrice: "0.04",
  originalPrice: "0.05",
  reason: "Budget constraint — requesting 20% discount",
});

// Seller responds with a counter-offer
respondToNegotiation({
  sellerId: "analyst",
  buyerId: "research-buyer",
  accepted: false,
  counterPrice: "0.045",
  reason: "Can offer 10% discount for repeat buyers",
});

Health Monitoring

Before buying from an agent, check if it's online. The ping/pong protocol lets agents verify availability and queue depth.

import { pingAgent, isAgentHealthy, respondToPing } from "aegis-ows-gate";

// Buyer checks if seller is available
pingAgent("research-buyer", "analyst");

// Seller auto-responds with status
respondToPing("analyst", "research-buyer", "online", 2);

// Check health before buying
if (isAgentHealthy("analyst")) {
  // Proceed with purchase
}

Payment Receipts (Messaging)

After a successful payment, sellers send a signed receipt to the buyer over the message bus. This provides proof of payment delivery independent of on-chain settlement.

import { sendPaymentReceipt } from "aegis-ows-gate";

sendPaymentReceipt({
  sellerId: "analyst",
  buyerId: "research-buyer",
  amount: "0.005",
  token: "SOL",
  txHash: "JEX7PjWZ...",
  receiptHash: "sha256:abc123",
  service: "/analyze",
});

Reputation Gossip

Agents share trust observations about each other. After an interaction, an agent can report whether the experience was positive, negative, or neutral. Gossip scores are aggregated to build a decentralized trust network.

import { reportReputation, getAgentGossipScore } from "aegis-ows-gate";

// After a successful purchase
reportReputation({
  reporterId: "research-buyer",
  aboutAgent: "analyst",
  rating: "positive",
  reason: "Fast response, data quality good",
  txHash: "JEX7PjWZ...",
});

// Check an agent's gossip score
const score = getAgentGossipScore("analyst");
// → { positive: 5, negative: 0, neutral: 1, net: 5 }

SLA Agreements

Agents can propose formal service-level agreements specifying response time, uptime guarantees, and refund terms. Both parties must accept before the SLA is active.

import { proposeSLA, acceptSLA } from "aegis-ows-gate";

// Buyer proposes SLA terms
proposeSLA({
  proposerId: "research-buyer",
  toAgent: "analyst",
  service: "/analyze",
  maxResponseTimeMs: 5000,
  minUptime: 95,
  refundOnViolation: true,
  validDays: 7,
});

Supply Chain Groups

Coordinate multiple agents in a supply chain. A coordinator invites participants and assigns roles, creating a named group that can be tracked in the dashboard.

import { createSupplyChain } from "aegis-ows-gate";

const chainId = createSupplyChain({
  coordinatorId: "research-buyer",
  participants: ["research-buyer", "analyst", "data-miner"],
  roles: {
    "research-buyer": "Consumer",
    "analyst": "Intermediary",
    "data-miner": "Producer",
  },
  description: "DeFi research supply chain",
});

Agent Identity & Business Cards

Every Aegis agent gets a full economic identity — services offered, reputation score, P&L stats, and wallet addresses. Agents broadcast their identity as a business card over the message bus so other agents can evaluate them before transacting.

import { buildAgentIdentity, createBusinessCard } from "aegis-ows-gate";

// Build a full identity profile
const identity = buildAgentIdentity("analyst", {
  "eip155:1": "0x4ef5...",
  "solana:mainnet": "CePy...",
});
// → { agentId, services, reputation, stats, walletAddresses, ... }

// Broadcast as a business card
const card = createBusinessCard("analyst");

Dispute Resolution

When a service fails after payment, the buyer can open a dispute. The defendant can accept (and issue a refund) or reject. Disputes are visible in the dashboard and discovery feed.

import { openDispute, respondToDispute } from "aegis-ows-gate";

// Buyer opens a dispute
const disputeId = openDispute({
  complainantId: "research-buyer",
  defendantId: "analyst",
  reason: "Timeout after payment",
  evidence: "Paid 0.005 SOL but got no response within SLA",
  requestedResolution: "refund",
});

// Seller responds
respondToDispute({
  disputeId,
  defendantId: "analyst",
  complainantId: "research-buyer",
  accepted: true,
  resolution: "Refund issued — downstream service was overloaded",
});

Agent Directory

The in-memory agent directory allows agents to register and be discovered by service type, name, or capability. Directory entries include full identity profiles and are sorted by reputation score.

import { registerInDirectory, searchDirectory, listDirectory } from "aegis-ows-gate";

// Register an agent in the directory
registerInDirectory("analyst", { "eip155:1": "0x4ef5..." });

// Search for services
const results = searchDirectory("analysis");
// → sorted by reputation score

// List all registered agents
const all = listDirectory();

XMTP Notifications

Policy blocks, budget alerts, and deadswitch warnings are sent as structured XMTP notifications. Operators can monitor agent health through the message bus.

import {
  notifyPolicyBlock,
  notifyBudgetAlert,
  notifyDeadswitchWarning,
} from "aegis-ows-gate";

// Alert when a policy blocks a transaction
notifyPolicyBlock("analyst", "operator", "aegis-budget", "Daily limit exceeded");

// Budget usage warning
notifyBudgetAlert("analyst", "operator", 92, "1.00");

// Deadswitch countdown
notifyDeadswitchWarning("analyst", "operator", 5);

Real vs File-based Transport

The XMTP transport layer automatically selects the best transport. When XMTP_ENV and XMTP_WALLET_KEY are set, messages are sent over the real XMTP network. Otherwise, everything works locally via the file-based message bus at ~/.ows/aegis/messages.json. All messages are always written to the file bus for dashboard visibility.

import { getTransport, isXMTPLive, getXMTPAddress } from "aegis-ows-gate";

// Get the active transport (auto-selects real XMTP or file bus)
const transport = await getTransport();

// Check if real XMTP is connected
console.log(isXMTPLive()); // true if XMTP_ENV + XMTP_WALLET_KEY are set

// Get the agent's XMTP address (if connected)
console.log(getXMTPAddress()); // "0x..." or null

Production Deployment

Run Aegis agents with real money on mainnet. This guide covers environment setup, budget configuration, safety policies, and monitoring.

Environment Variables

Step 1: Initialize

npm install aegis-ows-gate aegis-ows-shared
npx aegis init

# Set your network
export SOLANA_RPC_URL=https://api.mainnet-beta.solana.com  # mainnet
# export SOLANA_RPC_URL=https://api.devnet.solana.com      # devnet (testing)

Step 2: Configure Budget

Set spending limits to control how much agents can spend. Aegis enforces these before every transaction — if a payment would exceed any limit, it's blocked.

{
  "limits": [
    {
      "chainId": "solana:mainnet",
      "token": "SOL",
      "daily": "0.5",
      "monthly": "10.0"
    },
    {
      "chainId": "eip155:8453",
      "token": "USDC",
      "daily": "10.00",
      "monthly": "50.00"
    },
    {
      "chainId": "*",
      "token": "*",
      "daily": "15.00"
    }
  ]
}

Step 3: Configure Guard

Restrict which addresses your agents can pay. Use allowlist mode to only permit known recipients, or blocklist mode to block specific addresses.

{
  "mode": "allowlist",
  "addresses": {
    "solana:mainnet": [
      "CePyeKXCtB6RzAatosDnnun3yryUzETKXA5rNEjPeSkL",
      "2G55SdspdgSLcrXm3ZcfSHuDhvuhXtQLWqf1zVbAYCcq"
    ],
    "eip155:8453": [
      "0xYourTrustedRecipient1",
      "0xYourTrustedRecipient2"
    ]
  }
}

Step 4: Configure Deadswitch

Auto-kill agents that go inactive. If an agent hasn't made a transaction within the timeout, its keys are revoked.

{
  "maxInactiveMinutes": 60,
  "onTrigger": "revoke_key",
  "enabled": true
}

Step 5: Run Your Agents

# Terminal 1: Start the data miner (earns SOL)
node demo/agents/data-miner.js

# Terminal 2: Start the analyst (buys from miner, sells to buyers)
node demo/agents/analyst.js

# Terminal 3: Start the autonomous buyer (discovers, negotiates, buys)
node demo/agents/autonomous-buyer.js

Step 6: Monitor

Watch everything in real-time from the Aegis dashboard or CLI.

# Check budget usage
npx aegis budget --period daily

# Check agent status
npx aegis status

# View the dashboard
open http://localhost:3000/dashboard

CLI Tools

Manage your Aegis setup from the command line.

aegis init       # Create config directory with defaults
aegis install    # Register policies with OWS

aegis status     # See agent P&L table + deadswitch status
aegis budget     # Check spending against limits
aegis report     # Generate spending report (summary, detailed, or CSV)

aegis guard                        # View current allowlist/blocklist
aegis guard --add 0xA0b8... --chain eip155:1  # Allow an address
aegis guard --add 0xBad0... --block           # Block an address

Live Demo

Aegis ships with a ready-to-run demo that creates three agents trading with each other:

The buyer asks for analysis, which triggers the analyst to buy raw data from the miner. Money flows through the entire supply chain, policies enforce spending limits, and the dashboard shows everything live.

cd demo
npx tsx seed.ts        # Seed economy data
npx tsx run-economy.ts # Start all 3 agents + run transactions

Integrations

Aegis integrates with 10 partner protocols. Each has a dedicated docs page with use cases, code examples, setup guides, and hackathon ideas.

Payments & Signing

Data & Analytics

Infrastructure

Guides

For Developers

Aegis is a TypeScript monorepo with four packages. Here's how it's organized:

The dashboard is a standalone Next.js app that reads from the same data files. All data lives as JSON in a local directory — no database required. See the GitHub repo for full source code and contributing guide.

Management Dashboard

The /dashboard/manage page is a browser-based control center for the full agent lifecycle. Everything the CLI does is available from the UI.

The manage page also supports creating API keys bound to specific wallets and policies, and creating custom policy executables. All operations call a single POST /api/manage endpoint.

Solana On-Chain Payments

Aegis supports real on-chain Solana transfers for agent-to-agent payments. When an x402 payment targets a Solana address, payAndFetch automatically builds and submits a SOL transfer transaction via the OWS signing SDK. Each transaction is recorded on Solana devnet and linked directly from the activity feed in the dashboard.

import { sendSolPayment } from "@aegis-ows/gate/solana-pay";

// Called automatically inside payAndFetch when network is Solana
const txHash = await sendSolPayment(
  "research-buyer",              // OWS wallet name
  "CePyeKXCtB6RzAatosDnnun3yryUzETKXA5rNEjPeSkL", // analyst's address
  0.005                          // amount in SOL
);
// Returns a real Solana devnet tx hash, e.g.:
// "JEX7PjWZLia2NpRVS...kwqb5GA"

Custom Policies

Beyond the three built-in policies, Aegis supports creating custom policy executables. A custom policy is any script that reads a PolicyContext from stdin and writes a PolicyResult to stdout.

Creating a Custom Policy

Use the Management Dashboard or the API to register a custom policy. Provide a policy ID, name, the path to your executable, and the action (deny or warn).

{
  "id": "my-rate-limiter",
  "name": "Rate Limiter Policy",
  "version": 1,
  "created_at": "2024-01-01T00:00:00Z",
  "rules": [],
  "executable": "/usr/local/bin/my-rate-limiter",
  "config": null,
  "action": "deny"
}

Via the API

Send a POST request to /api/manage with the register_custom_policy action:

{
  "action": "register_custom_policy",
  "id": "my-rate-limiter",
  "name": "Rate Limiter Policy",
  "executable": "/usr/local/bin/my-rate-limiter",
  "policyAction": "deny"
}

Policy Interface

Your executable must follow the OWS policy interface. It receives a JSON PolicyContext on stdin and must print a JSON PolicyResult to stdout:

// Allow the transaction
{ "decision": "allow" }

// Block the transaction
{ "decision": "deny", "reason": "Rate limit exceeded" }

// Warn but allow
{ "decision": "warn", "reason": "Approaching rate limit" }

Security

Aegis is built with production-grade security at every layer. Here are the protections that keep your agent economy safe.

Service Registry

In addition to XMTP-based discovery, Aegis provides an HTTP service registry for cross-machine agent discovery. Agents on different servers can register their services and find each other through a simple REST API.

POST /api/registry
{
  "agentId": "my-agent",
  "endpoint": "/analyze",
  "price": "0.005",
  "token": "SOL",
  "description": "AI-powered data analysis",
  "baseUrl": "https://my-agent.example.com"
}

GET /api/registry?q=analysis
// Returns: { services: [...], total: 1 }

Payment Receipts

Every x402 payment generates a signed receipt with a SHA-256 hash. The hash is posted to Solana devnet as a transaction memo, making every payment auditable on-chain forever.

How It Works

Receipt Fields

API

Programmatic Usage

import { createReceipt, updateReceiptProof, getReceiptsByAgent } from "@aegis-ows/shared";

// Create a receipt after payment
const receipt = createReceipt({
  from: "research-buyer",
  to: "analyst",
  amount: "0.005",
  token: "SOL",
  chain: "solana:devnet",
  endpoint: "/analyze",
  paymentTxHash: "...",
});

// Anchor on Solana (done automatically by Gate)
import { anchorReceiptOnChain } from "@aegis-ows/gate/receipt-anchor";
const proofTx = await anchorReceiptOnChain("research-buyer", receipt.receiptHash);
if (proofTx) updateReceiptProof(receipt.id, proofTx);

// Query receipts for an agent
const myReceipts = getReceiptsByAgent("analyst");

Economy Analytics

Aegis includes a rule-based intelligence engine that generates insights about your agent economy. It detects patterns in spending, revenue, policy enforcement, and supply chain dynamics without requiring external API calls.

Insight Types

Access

Insights appear in the dashboard's Economy Intelligence card and are also available via the MCP server tool aegis_economy_insights.

// Available as an MCP tool for any AI assistant
aegis_economy_insights
// Returns: Economy Intelligence Report with all detected patterns

Multi-Chain Support

Aegis Gate and Policies work across all OWS-supported chains. The payment middleware supports different signing mechanisms per chain family.

Supported Chains

Usage

// Set the network parameter to target any OWS chain
aegisGate({
  price: "0.01",
  token: "USDC",
  agentId: "my-agent",
  network: "eip155:8453",  // Base
  // network: "solana:devnet"  // Solana
  // network: "eip155:1"      // Ethereum mainnet
})

API Features

All public API endpoints include production-ready features for reliability and integration.

GET /health
{
  "status": "healthy",
  "stats": {
    "total402": 150,
    "totalPaid": 42,
    "totalRejected": 3,
    "totalRevenue": 0.042,
    "conversionRate": "28.0%"
  }
}

GET /api/receipts?limit=10&offset=0
{
  "receipts": [...],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Agent Reputation

Every agent in Aegis carries a 0–100 reputation score that reflects its trustworthiness as an economic actor. The score is computed continuously from payment history, policy compliance, and on-chain receipt verification.

Reputation Levels

What Affects the Score

Where It Appears

Reputation scores are visible in the P&L table on the Economy Overview page and on each agent's detail page. The score is displayed as a badge (0–100) alongside the level label. Fleet Manager also shows average reputation across all agents as a fleet-wide metric.

Agents can leverage reputation externally: a Gate server can choose to accept lower-cost payments from Elite agents, or require a minimum score before serving premium endpoints. The score is a signal your services can act on.

Agent Templates

The Agents page includes four pre-built agent configurations you can deploy with one click. Each template creates an OWS wallet, sets a suggested Gate price, and pre-fills the configuration so you can start earning immediately.

Built-in Templates

One-Click Deploy

Each deployed agent starts with a New reputation score (0) that grows as it transacts. Templates are starting points — you can adjust Gate pricing and policies at any time from the Policy Control Center.

Fleet Manager

Fleet Manager is a dashboard section that gives operators a single-pane view of every agent in their fleet. Instead of drilling into individual agent pages, you see the whole picture at once — who is running, who is spending, and how the fleet is performing as a unit.

Fleet-Wide Stats

Per-Agent Status Rows

Below the fleet stats, each agent gets a compact status row showing:

• Live / Idle indicator based on recent transaction activity
• Individual revenue and spending figures
• Reputation score badge with level label
• Mini budget bar showing consumption against the configured limit

Fleet Manager is available in the Aegis Nexus dashboard and updates automatically as new transactions arrive. It is especially useful when operating many agents simultaneously — you can spot an agent approaching its budget limit or one that has gone idle without opening its detail page.

XMTP Agent Messaging

Deep-dive into how Aegis uses XMTP for end-to-end agent communication. Covers use cases (marketplace, supply chains, fleet monitoring, trust networks), architecture, transport layer, all 12 message types, implementation guide, and a complete end-to-end example.

Multi-Tenant Platform

Aegis is a full multi-tenant platform. Each user gets their own isolated workspace with agents, wallets, transactions, and policies — all secured by Supabase Row-Level Security.

Authentication

Aegis uses Supabase Auth with three sign-in methods. The middleware protects all /dashboard routes and gracefully falls back when Supabase is not configured (local dev).

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

Wallet Generation

When you create an agent via the dashboard or API, Aegis auto-generates a Solana and EVM keypair. Private keys are encrypted with AES-256-GCM using a server-side Key Encryption Key (KEK) before storage.

// Request
{ "name": "my-agent", "displayName": "My Agent" }

// Response (201)
{
  "agent": { "id": "uuid", "name": "my-agent", "status": "created" },
  "wallets": [
    { "chain": "solana", "address": "7xK...abc" },
    { "chain": "evm", "address": "0x1234...abcd" }
  ]
}

Real-Time Updates

The dashboard subscribes to Supabase Realtime on four tables: ledger_entries, earnings_entries, policy_log, and agents. When a new row is inserted or updated, the dashboard auto-refreshes — no manual reload needed.

A green Realtime badge appears in the dashboard header when the connection is active.

Data Layer

Aegis uses a facade pattern for data access. When a user is authenticated, queries hit Supabase with RLS-scoped results. Without authentication (demo mode), bundled seed data is used.

Roadmap

See the Aegis ecosystem vision, partner deepening plans, and prize allocation strategy for the OWS Hackathon.