Connect Agent Widget — Opacus Docs

1. Overview

The Opacus Agent Widget lets any web app (including apps built by 0G App) integrate agent execution in seconds. Drop a single <script> tag and your users can connect their Opacus agent, run skills, and pay agent-to-agent — without leaving your app.

2. Quick Start

<!-- 1. Include the widget -->
<script src="https://opacus.xyz/agent-widget.js" data-opacus-app="my-app"></script>

<!-- 2. (Optional) manual init with config -->
<script>
OpacusAgent.init({
  appId: 'my-app',
  position: 'bottom-right',   // bottom-right | bottom-left | top-right | top-left
  theme: 'dark'               // dark | light (default: dark)
});
</script>

That's it. A floating "Connect Agent" button appears. When the user clicks it, they enter their Opacus API key. The widget authenticates, stores the session, and your app can now call agent skills.

3. API Reference

OpacusAgent.init(config)

Initialize and render the widget. Called automatically if data-opacus-app is present on the script tag.

Option	Type	Default	Description
`appId`	string	required	Your app identifier (used for session scoping)
`position`	string	`bottom-right`	Button placement on screen
`theme`	string	`dark`	Widget color theme

OpacusAgent.connect()

Programmatically open the connect modal.

document.getElementById('myBtn').addEventListener('click', () => {
  OpacusAgent.connect();
});

OpacusAgent.getAgent()

Returns the connected agent's info, or null if not connected.

const agent = OpacusAgent.getAgent();
// { agentId, agentName, did, balance, kineticScore, scope }
if (agent) {
  console.log('Connected as:', agent.agentName);
}

OpacusAgent.execute(skill, params)

Execute an agent skill. Throws if no agent is connected.

const result = await OpacusAgent.execute('swap', {
  tokenIn: 'USDC',
  tokenOut: 'W0G',
  amountIn: 10
});
console.log(result);

OpacusAgent.pay(toAgentId, amountUsdc, description)

Send USDC from the connected agent to another agent.

await OpacusAgent.pay('agent_xyz', 1.50, 'Data access fee');

OpacusAgent.buyData(listingId)

Purchase a Data Market listing on behalf of the connected agent.

const purchase = await OpacusAgent.buyData('dm_abc123');
console.log(purchase.dataHash); // 0G DA root hash

OpacusAgent.disconnect()

Disconnect the current agent and clear session storage.

OpacusAgent.on(event, callback)

Subscribe to widget events.

Event	Payload	Description
`connected`	`{ agentId, agentName, ... }`	Fired when agent connects successfully
`disconnected`	`null`	Fired when agent disconnects
`executed`	`{ skill, result }`	Fired after a skill executes
`error`	`Error`	Fired on any error

OpacusAgent.on('connected', (agent) => {
  console.log('Agent connected:', agent.agentId);
  document.getElementById('agentStatus').textContent = agent.agentName;
});

4. Backend Endpoint

The widget calls POST /api/agent-kernel?path=/widget/connect with the provided API key. You can also call this from your backend to verify a connected agent:

POST https://opacus.xyz/api/agent-kernel?path=/widget/connect
Content-Type: application/json
Authorization: Bearer <apiKey>

{}

// Response
{
  "ok": true,
  "agent": {
    "agentId": "agent_abc123",
    "agentName": "My Agent",
    "did": "did:opacus:...",
    "balance": 42.50,
    "kineticScore": 850,
    "scope": "user@example.com"
  }
}

5. Integration Example — 0G App

If your app was generated by 0G App, Opacus can be auto-assigned as the execution layer. Add this to your <head>:

<script src="https://opacus.xyz/agent-widget.js" data-opacus-app="{{YOUR_0G_APP_ID}}"></script>
<script>
OpacusAgent.on('connected', function(agent) {
  // Enable your app's agent features
  document.querySelectorAll('[data-requires-agent]').forEach(el => {
    el.removeAttribute('disabled');
  });
});
</script>

6. Security

API keys are stored in sessionStorage (cleared on tab close) and never sent to third parties.
All requests go directly to opacus.xyz — no widget-side key logging.
The widget does not inject any tracking scripts.
Use scoped API keys with limited permissions for untrusted embedding contexts.

7. Customization

/* Override widget button with your own CSS */
#opacus-connect-btn {
  background: #your-brand-color !important;
  font-family: your-font !important;
}

#opacus-agent-popup {
  /* styles for the agent info popup */
}