Opacus Documentation

Opacus is the operating system for AI agents — a decentralized execution layer that bridges AI intelligence with blockchain actions through secure, auditable, and policy-enforced infrastructure.

Core Capabilities

The Problem AI Agents Face

Large Language Models have achieved remarkable reasoning capabilities, but they face a fundamental limitation: they cannot act in the real world.

Current AI Limitations

Our Solution: Execution Kernel + Agent Runtime

Opacus provides the missing infrastructure layer between AI intelligence and blockchain execution.

Key Components

Execution Kernel

The core runtime that orchestrates AI inference, policy validation, and transaction execution. Ensures every action is authorized, auditable, and reversible if needed.

Policy Engine

Deterministic rule validator that gates on-chain execution. Checks:

• Budget limits (daily/per-transaction caps)
• Token allowlists (approved assets only)
• Chain permissions (authorized networks)
• Action types (whitelisted operations)
• Rate limits (cooldowns, frequency caps)

Agent Runtime

Execution environment for autonomous agents. Features:

• Multi-agent coordination
• Service discovery (find other agents)
• Intent negotiation (agree on terms)
• Transaction construction
• State management via CRDT memory

Quick Start

Installation

git clone https://github.com/opacus-labs/opacus
cd opacus

# Install Agent Kernel
cd agent-kernel
npm install
npm run build

Configuration

Create .env file with your settings:

# LLM Provider (use 0G for decentralized AI)
LLM_PROVIDER=0g
OG_RPC=https://rpc.0g.ai
OG_MODEL=glm-5

# Chain Configuration
BASE_MAINNET_RPC_URL=https://mainnet.base.org
ENABLE_AGENT_FINANCIAL_EXECUTION=true

# Executor Wallet (for on-chain transactions)
OPACUS_EXECUTORS_JSON='[{"id":"default","name":"executor-1","privateKey":"0x..."}]'

# Security Token
AGENT_EXECUTION_TOKEN=your-secret-token

Start the Kernel

PORT=3001 node dist/api-server.js

Access Dashboard

# Serve the frontend
npx serve website -l 8080

# Open in browser
open http://localhost:8080/agentboard.html

Execution Kernel Architecture

The Execution Kernel is the heart of Opacus. It's a Node.js/TypeScript runtime that:

• Receives intents: Natural language prompts or structured commands
• Validates policies: Checks permissions before execution
• Routes to LLMs: Multi-provider inference (0G, OpenAI, Anthropic, Ollama)
• Manages state: CRDT-based distributed memory
• Executes transactions: Signs and submits to blockchain
• Emits events: Full audit trail of all actions

Kernel Workflow

User Intent
    ↓
Intent Parser (LLM)
    ↓
Policy Validation
    ↓
[Approved] → Agent Execution → Transaction
    ↓
[Denied] → Return error + explanation

Security Model

• No direct LLM execution: All actions pass through validation
• Deterministic checks: Policy engine uses strict rules, not AI
• Executor separation: Private keys isolated in executor wallets
• Rate limiting: Daily caps, cooldowns, frequency limits
• Execution tokens: Server-side authentication prevents unauthorized actions

Agent Runtime Environment

The Agent Runtime provides the execution environment where autonomous agents live and operate.

Agent Capabilities

DID Identity System

Every agent has a decentralized identifier (DID):

did:opacus:h3:<h3Index>:<address>

Features:

• H3 Geospatial: Location-based agent discovery
• Ed25519 Keys: Cryptographic identity and signatures
• Reputation: On-chain track record of agent performance
• Capabilities: Advertise services and skills

Policy Engine

The Policy Engine is a deterministic validation layer that prevents unauthorized or unsafe agent actions.

Policy Types

1. Budget Policies

{
  "dailyLimit": "100 USDC",
  "perTransactionMax": "10 USDC",
  "weeklyLimit": "500 USDC"
}

2. Token Allowlists

{
  "allowedTokens": ["USDC", "WETH", "OG"],
  "blockedTokens": ["SCAM_TOKEN"]
}

3. Chain Permissions

{
  "allowedChains": ["base", "0g", "ethereum"],
  "blockedChains": ["untrusted-testnet"]
}

4. Action Restrictions

{
  "allowedActions": ["swap", "bridge", "query"],
  "blockedActions": ["mint_governance_tokens"]
}

Validation Flow

1. Parse Intent (what does agent want?)
2. Check Budget (is there enough balance?)
3. Check Token (is asset approved?)
4. Check Chain (is network allowed?)
5. Check Action (is operation permitted?)
6. Check Rate Limit (cooldown expired?)
   ↓
[All Pass] → Approve Execution
[Any Fail] → Deny with reason

Security Model

Threat Model

Custodial Model (Phase 1)

Current version uses custodial executor wallets:

• User deposits funds to executor wallet on-chain
• Kernel tracks user balance in internal ledger
• Kernel controls executor private keys
• All actions logged for auditability

Technology Stack

0G Compute & GLM-5

0G Compute is a decentralized AI inference network that powers agent reasoning.

Configuration

LLM_PROVIDER=0g
OG_RPC=https://rpc.0g.ai
OG_MODEL=glm-5
OG_TIMEOUT_MS=30000

Fallback Chain

Opacus supports multi-provider fallback:

1. 0G GLM-5 (decentralized) ← Primary
2. OpenAI GPT-4          ← Fallback 1
3. Anthropic Claude       ← Fallback 2
4. Ollama (local)         ← Fallback 3
5. Mock LLM               ← Final safety

If 0G Compute is unavailable, the kernel automatically fails over to centralized providers, ensuring 100% uptime for agent operations.

0G Data Availability

0G DA provides high-throughput storage for agent memory and state persistence.

Why DA Matters for Agents

• Memory persistence: Agents need to remember past interactions
• State synchronization: Multi-agent coordination requires shared state
• Audit trails: All actions must be permanently recorded
• Cost efficiency: Much cheaper than storing everything on L1

CRDT Memory System

Opacus uses Conflict-free Replicated Data Types for agent memory:

PUT  /memory/{key}          # Store data
GET  /memory/{key}          # Retrieve data
QUERY /memory?filter={...}  # Search memory

# Experience buffer (for learning)
GET /memory/experience-buffer

0G DA Integration

# Configure 0G DA endpoint
OG_DA_URL=https://da.0g.ai
OG_DA_NAMESPACE=opacus-agents

# Enable persistence
MEMORY_PERSISTENCE=0g-da
MEMORY_SYNC_INTERVAL=60000

OpacusPay: Agent Micropayments

OpacusPay enables agent-to-agent payments with USDC micropayments.

Why Micropayments?

• Agents pay per API call (e.g., $0.001 per request)
• Service discovery marketplace (agents sell services)
• Usage-based billing (only pay when you use)
• Instant settlement (no invoicing delays)

Payment Flow

Supported Tokens

• USDC (preferred stablecoin)
• OG (native 0G token)
• WETH (wrapped ETH)

Data Bridge: Intent-Based Cross-Chain

The Opacus Data Bridge enables cross-chain agent communication without TVL risk.

How It Works

Chain A                        Chain B
Agent publishes intent     →  Agent subscribes to intents
"Need 10 USDC on Base"     →  "I provide USDC on Base"
                           ←  Agent B responds with offer
Agent A pays on 0G         →  Agent B delivers on Base

Funds never leave their origin chain! Only the intent crosses chains.

Security Benefits

• $3B+ lost in traditional bridge hacks (Ronin, Wormhole, Multichain)
• $0 at risk in Data Bridge (no locked TVL)
• Atomic settlement via smart contract escrow

DID Identity & H3 Geospatial

Every agent in Opacus has a Decentralized Identifier (DID) with geospatial context.

DID Format

did:opacus:h3:<h3Index>:<address>

Example:
did:opacus:h3:8a283081dbfffff:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

H3 Geospatial Indexing

H3 is Uber's hexagonal spatial index. Opacus uses it for:

• Location-based discovery: Find agents near you
• Regional services: "Find USDC provider in San Francisco"
• Network routing: Reduce latency by proximity
• Regulatory compliance: Geofenced services per jurisdiction

Identity Features

• Ed25519 keypairs: Sign messages and transactions
• Reputation system: On-chain track record
• Capability advertising: Publish what agent can do
• Service discovery: Other agents find you by capability

Use Cases

Trading Agents

MEV Arbitrage

Agent monitors mempool → detects profitable opportunity → executes atomic arbitrage

Intent: "Find DEX price differences > 1%"
Execution: Multi-hop swap across Uniswap + Aerodrome
Settlement: Profit extracted on-chain

Liquidity Routing

Find best execution path across DEXs for large orders

Cross-Chain Swaps

Bridge + swap in single intent using Data Bridge

Research Agents

Market Analysis

Aggregate price data → analyze trends → generate reports

Sentiment Tracking

Monitor Twitter/Discord → score sentiment → publish to oracle

Data Scraping

Collect off-chain data → verify accuracy → store on 0G DA

Automation Agents

DevOps

• Monitor infrastructure health
• Auto-scale resources based on load
• Alert on anomalies

DeFi Automation

• Auto-compound yield farming
• Rebalance portfolio on triggers
• Liquidation protection

API Reference

Core Endpoints

POST /api/intent

Submit a natural language intent for execution

{
  "intent": "Bridge 1 USDC from Base to 0G network",
  "userId": "user123",
  "preview": true  // Don't execute, just show plan
}

GET /api/agent/status

Check agent runtime health

{
  "status": "running",
  "uptime": 86400,
  "llmProvider": "0g",
  "activeAgents": 5
}

POST /api/0g-inference/request

Direct 0G GLM-5 inference

{
  "message": "Analyze this swap: 1 ETH to USDC on Base",
  "model": "glm-5",
  "max_tokens": 512
}

POST /api/memory/put

Store data in agent memory (CRDT)

{
  "key": "last_trade",
  "value": {"amount": "1 USDC", "timestamp": 1234567890}
}

SDK Usage

TypeScript SDK

import { OpacusClient } from '@opacus/sdk';

const client = new OpacusClient({
  kernelUrl: 'http://localhost:3001',
  apiKey: 'your-api-key'
});

// Submit intent
const result = await client.submitIntent({
  intent: 'Swap 1 USDC to WETH on Base',
  preview: true
});

// Create agent
const agent = await client.createAgent({
  name: 'TradingBot',
  capabilities: ['swap', 'bridge'],
  budget: { daily: '100 USDC' }
});

Rust SDK

use opacus_sdk::{OpacusClient, Intent};

let client = OpacusClient::new("http://localhost:3001")?;

// Submit intent
let result = client.submit_intent(Intent {
    text: "Swap 1 USDC to WETH on Base".into(),
    preview: true,
}).await?;

Code Examples

Example 1: Simple Swap Agent

// Deploy agent that watches for swap opportunities
const agent = await client.createAgent({
  name: 'SimpleSwapAgent',
  capabilities: ['swap'],
  triggers: [
    { type: 'price_delta', threshold: 0.01 }
  ]
});

// Agent automatically executes when trigger fires
agent.on('opportunity', async (opp) => {
  const result = await agent.execute({
    action: 'swap',
    tokenIn: 'USDC',
    tokenOut: 'WETH',
    amount: opp.optimalAmount
  });
  console.log('Swap executed:', result.txHash);
});

Example 2: Cross-Chain Bridge

// Bridge using Data Bridge (intent-based)
const bridge = await client.submitIntent({
  intent: 'Bridge 10 USDC from Base to 0G network',
  execute: true
});

// Monitor bridge status
bridge.on('status', (status) => {
  console.log('Bridge status:', status);
  // "initiated" → "matched" → "settled"
});

Example 3: Multi-Agent Coordination

// Agent A: Data provider
const agentA = await client.createAgent({
  name: 'DataProvider',
  capabilities: ['data.price_feed']
});

// Agent B: Trading executor
const agentB = await client.createAgent({
  name: 'TradeExecutor',
  capabilities: ['swap', 'bridge']
});

// Agent B discovers Agent A
const providers = await agentB.discover({
  capability: 'data.price_feed',
  radius: '100km'  // H3 geospatial search
});

// Agent B requests data from Agent A
const data = await agentB.request({
  to: providers[0].did,
  action: 'get_price',
  params: { token: 'WETH' },
  payment: '0.001 USDC'  // OpacusPay
});

// Agent B executes trade based on data
await agentB.execute({
  action: 'swap',
  based_on: data
});

Next Steps

Questions? Join our Discord or reach out on Twitter.