@opacus/sdk

Opacus hosts agent infrastructure via APIs — you run your agent anywhere.

API control plane for agent identity (DID), low-latency routing (Nitro), geo-policy (H3), storage (0G), and settlement (Pay / Escrow).

• REST-first — every SDK call maps 1:1 to a documented endpoint
• Bootstrap + scoped token lifecycle handled automatically
• Safe defaults: retries, timeouts, request IDs, budget-safe errors

Install

npm i opacus-agent-sdk

Quickstart (5 minutes)

1. Create a Project + API Key in Agentboard

2. Set your key:

export OPACUS_API_KEY="op_live_..."

3. Call the API:

import { Opacus } from "opacus-agent-sdk";

const opacus = new Opacus({ apiKey: process.env.OPACUS_API_KEY! });

// Bootstrap: performs /challenge + /register, issues DID + scoped tokens
await opacus.bootstrap();

// Nitro routing — find the fastest execution path
const route = await opacus.routing.optimize({
  intent: "swap",
  chain: "base",
  mode: "fast",
});
console.log("route", route);

// H3 geo-policy — resolve your agent's hex cell
const loc = await opacus.h3.locate({ resolution: 8 });
console.log("h3", loc);

// 0G storage — store data on decentralized DA layer
const stored = await opacus.ogStorage.store({ key: "value" });
console.log("cid", stored.rootHash);

Scoped Tokens

bootstrap() issues 3 scoped tokens, refreshed automatically:

| Token | TTL | Scopes | |-------|-----|--------| | AGENT | 24 h | nitro.execute, h3.routing | | DATA | 24 h | 0g.upload, 0g.download | | PAY | 1 h | pay.gas_subsidy, pay.escrow |

Budget Model (Locks) & 402

Some services require a minimum USDC lock before first use:

| Service | Lock | |---------|------| | Nitro Routing | $10 | | H3 Location | $8 | | Data Bridge | $12 | | OpacusPay | $5 |

If the lock is below minimum, calls return:

HTTP 402  { "code": "BUDGET_EXHAUSTED" }

Fix: add funds or increase the service lock in Agentboard → Billing.

Configuration

const opacus = new Opacus({
  apiKey: process.env.OPACUS_API_KEY!,
  baseUrl: "https://opacus.xyz",   // default
  chain: "base",                    // default chain for operations
});

Subpath Imports

Each module is tree-shakeable and independently importable:

import { Opacus } from "opacus-agent-sdk";          // Golden Path (recommended)
import { NitroClient } from "opacus-agent-sdk/nitro";
import { H3RoutingClient } from "opacus-agent-sdk/h3";
import { latLngToH3Cell } from "opacus-agent-sdk/h3-utils"; // zero deps
import { BridgeClient } from "opacus-agent-sdk/bridge";
import { EscrowClient } from "opacus-agent-sdk/escrow";

Error Handling

| Status | Code | Action | |--------|------|--------| | 402 | BUDGET_EXHAUSTED | Add funds / increase lock | | 429 | RATE_LIMITED | Back off and retry | | 5xx | — | Retry with jitter |

import { OpacusError } from "opacus-agent-sdk";

try {
  await opacus.routing.optimize({ intent: "swap", chain: "base" });
} catch (e) {
  if (e instanceof OpacusError && e.status === 402) {
    console.error("Top up your lock in Agentboard");
  }
}

REST-Only Usage

Prefer curl? Every SDK method maps directly to a REST endpoint:

curl -X POST https://opacus.xyz/v1/router/execute \
  -H "Authorization: Bearer $OPACUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent":"swap","chain":"base","mode":"fast"}'

Full reference: API Docs

Examples

See examples/ for runnable scripts:

• mainnet-quick-start.ts — Bootstrap + route + store
• 0g-da-storage.ts — Decentralized storage upload
• auto-payment-example.ts — OpacusPay automation

Links

| | | |-|-| | Docs | opacus.xyz/docs | | API Reference | opacus.xyz/docs/api-reference.html | | Agentboard | opacus.xyz/agentboard.html | | Changelog | CHANGELOG.md | | Issues | GitHub Issues |

License

MIT