V1 Token System & Bootstrap

Discovery

Any agent can discover Opacus automatically by fetching the standard discovery document:

GET https://opacus.xyz/.well-known/opacus.json

Returns the full service catalog, bootstrap URLs, token definitions, supported networks, and error codes. No authentication required.

GET /api/v1/discovery

Lightweight inline version of the same information.

Token Types

V1 uses 3 scoped tokens — each with a distinct prefix, scope set, and TTL:

Bootstrap Flow

Full zero-touch onboarding in 3 steps:

Step 1: Request Challenge

POST /api/v1/bootstrap/challenge
Content-Type: application/json

{
  "wallet_address": "0xYourWalletAddress",
  "network": "base"          // base | ethereum | solana | 0g
}

Response:

{
  "ok": true,
  "nonce": "a4c61874972bef6bd24e44d89e5a737c",
  "message": "Opacus V1 Bootstrap — Ownership Proof\nWallet: ...\nNonce: ...",
  "expires_at": "2026-04-12T21:33:46.978Z"
}

Step 2: Sign & Register

Sign the message with your wallet (EVM: personal_sign), then submit:

POST /api/v1/bootstrap/register
Content-Type: application/json

{
  "nonce": "a4c61874972bef6bd24e44d89e5a737c",
  "signature": "0x...",
  "agent_name": "my-agent"   // optional
}

Response:

{
  "ok": true,
  "did": "did:opacus:v1:0xabcd...",
  "agent_id": "citadel_abc123_xyz",
  "tokens": {
    "OPACUS_AGENT_TOKEN": "obr_agent_...",
    "OPACUS_DATA_TOKEN": "obr_data_...",
    "OPACUS_PAY_TOKEN": "obr_pay_..."
  },
  "token_details": { ... },
  "network": "base",
  "free_tier": {
    "enabled": true,
    "budget_usd": 5.00,
    "api_calls_per_day": 1000,
    "storage_bytes": 104857600
  }
}

Step 3: Use Tokens

# Set environment variables
export OPACUS_AGENT_TOKEN=obr_agent_...
export OPACUS_DATA_TOKEN=obr_data_...
export OPACUS_PAY_TOKEN=obr_pay_...

# Use any V1 endpoint
curl -H "Authorization: Bearer $OPACUS_AGENT_TOKEN" \
  https://opacus.xyz/api/v1/oracle/query?q=ETH/USD

Authentication

All V1 service endpoints require a valid token in the Authorization header:

Authorization: Bearer obr_agent_...

Or via the X-Opacus-Token header. Each endpoint requires a specific scope — using the wrong token type returns 403 AUTH_SCOPE_DENIED.

Token Refresh

POST /api/v1/auth/refresh
Authorization: Bearer obr_agent_...  // any valid (or recently expired) token

Returns 3 fresh tokens. The old tokens are revoked.

Token Revoke

POST /api/v1/auth/revoke
Authorization: Bearer obr_agent_...

Service Endpoints

Compute & Routing

0G Storage & Compute

Payments & Budget

Monitoring & Agents

Bridge & DataBridge

Public (No Auth)

Standard Error Codes

All V1 errors follow a standard format:

{
  "error": {
    "code": "AUTH_SCOPE_DENIED",
    "message": "Token does not have the required scope",
    "retry_after_seconds": null,
    "docs_url": "https://opacus.xyz/docs"
  }
}

Free Tier

Every bootstrapped agent gets a free tier:

Once limits are hit, requests return BUDGET_EXHAUSTED (402). Top up via the Agentboard billing section.

Full Example (Node.js)

import { ethers } from 'ethers';

// 1. Discovery
const disc = await fetch('https://opacus.xyz/.well-known/opacus.json')
  .then(r => r.json());

// 2. Bootstrap
const wallet = ethers.Wallet.createRandom(); // or your existing wallet
const ch = await fetch(disc.bootstrap.challenge, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ wallet_address: wallet.address, network: 'base' })
}).then(r => r.json());

const sig = await wallet.signMessage(ch.message);
const reg = await fetch(disc.bootstrap.register, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ nonce: ch.nonce, signature: sig })
}).then(r => r.json());

// 3. Use services
const oracle = await fetch('https://opacus.xyz/api/v1/oracle/query?q=ETH/USD', {
  headers: { 'Authorization': 'Bearer ' + reg.tokens.OPACUS_AGENT_TOKEN }
}).then(r => r.json());

console.log('ETH/USD:', oracle);