Welcome to Aegis Documentation

Aegis is a decentralized trust layer for autonomous AI agents on Sui. It tracks onchain metrics - success rate, volume, uptime - and issues verifiable badges that control access permissions for protocols integrating AI agents.

Quickstart

Everything you need to integrate Aegis in your agent or protocol.

Step-by-step Setup

npm install @aegis/sdk
# or
pnpm add @aegis/sdk

import { SuiClient, getFullNodeUrl } from '@mysten/sui/client';
import { PACKAGE_ID, BADGE_REGISTRY_ID } from '@aegis/sdk';

const client = new SuiClient({ url: getFullNodeUrl('testnet') });

import { registerAgent } from '@aegis/sdk';

// Simulates: sui client call --function register_agent
const { objectId } = await registerAgent(signer);
console.log('ReputationObject:', objectId);

import { recordExecution } from '@aegis/sdk';

try {
  await recordExecution(signer, objectId, true, 1_000_000_000, 50);
} catch (err) {
  if (err.code === 'BADGE_REVOKED') activateBackupAgent();
}

import { checkBadgeStatus } from '@aegis/sdk';

const { badge, isValid } = await checkBadgeStatus(agentId);
console.log(`Badge: ${badge}, Valid: ${isValid}`);
// Verify on: suiexplorer.com/testnet/object/${objectId}

Installation

Install the Aegis SDK via npm or pnpm.

npm install @aegis/sdk

# or

pnpm add @aegis/sdk

Basic Usage

Import the client and fetch agent reputation.

import { createClient } from '@aegis/sdk';

const client = createClient({
  network: 'testnet'
});

// Fetch agent reputation
const agent = await client.getAgentReputation('0x...');
console.log(agent.badge); // 'bronze' | 'silver' | 'gold' | null

Key Concepts

API Reference

Complete SDK function signatures. All functions are async and target Sui Testnet.

try {
  await recordExecution({ objectId, success: true, volume: 1e9 });
} catch (err) {
  if (err instanceof BadgeRevokedError) {
    // Trigger fallback logic
    await activateBackupAgent();
  }
}

const { objectId, digest } = await registerAgent(signer);
// objectId = your permanent onchain identity
// digest = transaction hash for verification

import { computeAegisScore, getAgentReputation } from '@aegis/sdk';

const rep = await getAgentReputation(objectId);
const result = computeAegisScore(rep);

console.log(result.score);            // e.g. 98.4
console.log(result.tier);             // 'Platinum' | 'Gold' | 'Silver' | 'Bronze' | 'Unranked'
console.log(result.status);           // 'Active' | 'Supervised' | 'Under Review' | 'Quarantined'
console.log(result.breakdown);        // { performance, reliability, riskPenalty, contribution }

const { bronze, silver, gold } = await getBadgeEligibility(objectId);
// bronze: 10+ execs, 80%+ success
// silver: 50+ execs, 90%+ success
// gold:   200+ execs, 95%+ success, $1M+ volume

Integration Guides by Use Case

How real protocols integrate Aegis across different agent architectures.

Local Development & Testing

Run a full local environment before deploying to testnet.

Testnet Configuration

# Switch to Sui Testnet
sui client switch --env testnet

# Fund your wallet (faucet)
curl https://faucet.testnet.sui.io/gas?address=0xYOUR_ADDRESS

# Verify balance
sui client balance

Mocking Aegis for Unit Tests

import { mockAegisProvider } from '@aegis/sdk/testing';

const mock = mockAegisProvider({
  defaultBadge: 'gold',
  autoRevoke: false,
  simulatedLatency: 200,
});

test('agent executes with gold badge', async () => {
  const agent = await mock.registerAgent();
  expect(await agent.getBadge()).toBe('gold');
});

Running Integration Tests

# Run against live testnet
pnpm test:integration --network=testnet --agent=mock

# Simulate revocation flow
pnpm test:revocation --scenario=consecutive-failures

# Stress test (volume spike)
pnpm test:stress --duration=60s --rps=100

MemWal Integration

Aegis works seamlessly with MemWal for private agent memory:

• Private rationale - Agent's reasoning stays encrypted in Walrus
• Public metrics - Success/slippage verified onchain by Aegis
• Linked audit trail - MemWal blob_id anchored in ReputationObject

import { logExecution } from '@aegis/sdk';
import { memwalService } from '@aegis/sdk';

// 1. Store decision rationale in MemWal (private)
await memwalService.storeRationale({
  agentId: '0x...',
  reasoning: 'Market conditions favorable',
  decision: 'Execute with conservative slippage'
});

// 2. Record execution publicly on Aegis (onchain)
await recordExecution(signer, objectId, true, 1_000_000_000, 50);
// blob_id is automatically anchored in the ReputationObject

Troubleshooting & Error Codes

Common errors returned by the SDK and how to resolve them.

Security & Contract Audit

Full validation matrix for Aegis API, Move contracts, and integration patterns.

API Security Layer

API Key Handling

Move Contract Audit — reputation.move · badge_registry.move

Component Architecture — Separation of Concerns

Protocol Integrator Checklist

Delivery Modules

Suggested Timeline (10 Weeks)

Success KPIs (Phase 2)

Sustainability & Incentives

Business Model

Aegis is designed to be self-sustaining: the better agents perform, the more value the ecosystem creates - for everyone.

How Value Flows

Revenue Sources

Source	Description	Stage
Protocol Integration Fee	Small % on verified executions - waived during hackathon/testnet	Post-Mainnet
Premium Analytics	Advanced dashboards & alerting for enterprise users	Roadmap Q3
Grant-Funded Development	Ecosystem grants from Sui Foundation & ecosystem partners	Active

Agent Incentives

Gold Badge Agents

Priority access to high-value protocols + potential reward sharing from Aegis Treasury

Performance-Based

Fees and rewards scale with Aegis Score - bad actors earn nothing and face auto-revocation

No Pay-to-Play

Badges cannot be bought. Only earned via verifiable onchain performance - no shortcuts

Transparency Commitment