NexusAgent

NexusAgent

-blue)

[](https://web3.okx.com/zh-hans/onchainos)

Demo

[](https://youtu.be/SaQCjcS0few)

▶ Watch on YouTube

---

NexusAgent is a multi-agent commerce and execution framework on X Layer.

It helps third-party AI agents:

• onboard through official-friendly integration paths
• participate in typed multi-agent workflows
• pay per call via x402 (OKX facilitator, on-chain USDT settlement)
• execute bounded actions on X Layer mainnet
• settle outcomes with explorer-verifiable proof

What We Built

NexusAgent is intentionally split into two product surfaces:

1. Builder Surface

This is the real product wedge.

It shows how an external agent can enter the system through:

• AI Skills + Agentic Wallet
• MCP + Agentic Wallet
• Open API + custom integration

The onboarding surface defines:

• required registration fields
• capability declarations
• workflow role declarations
• wallet model expectations

2. Showcase Workflow Surface

This is the demo surface that proves the builder surface has value.

The current hero workflow is:

Check the OKB market signal and, if the run is approved, execute a bounded stablecoin proof transfer on X Layer.

The workflow runs through 9 explicit states:

Onboarding -> Intent -> Signal -> Decision -> Preparation -> Payment -> Execution -> Evaluation -> Settlement

Why This Matters

NexusAgent demonstrates the infrastructure layer of the agentic economy:

• External agents can join through official onboarding paths
• Each agent has role-specific responsibilities and typed inputs/outputs
• Agents hand off work to each other through a deterministic state machine
• Payment and settlement are distinct, auditable steps
• Every outcome produces explorer-verifiable proof on X Layer

Why The Four-Agent Split Exists

The agent roles are intentionally separated:

• Sentinel gathers external context
• Arbiter decides whether execution should proceed
• Executor prepares and performs the bounded action
• Evaluator checks whether the visible chain result matches the expected outcome

This keeps the system from collapsing into a single script that both acts and certifies itself. In particular, the Executor and Evaluator split follows a simple evaluator-optimizer principle: action and verification should be distinct when correctness matters.

---

⚡ Stack

| Layer | Technology | Status | |-------|-----------|--------| | Market Signal | OKX Onchain OS Market API (authenticated) | Live | | DEX Routing | OKX Onchain OS DEX Aggregator API | Live (quote-only) | | Payment | x402 protocol via OKX Facilitator (EIP-3009 + on-chain settle) | Live | | Settlement | X Layer ERC-20 transfers | Live (mainnet) | | Agent Identity | ERC-8004 AgentRegistry on X Layer mainnet | Deployed + Integrated | | Agent Commerce | ERC-8183 AgentEscrow on X Layer mainnet | Deployed + Integrated | | Agent Discovery | A2A Agent Card (/.well-known/agent.json, 3 skills) | Live | | Connectivity | MCP server (stdio, 5 tools) | Live | | Wallet Security | OKX Agentic Wallet (sign-info API integrated; TEE via OKX) | Integrated |

Agentic Wallet Integration

NexusAgent integrates with OKX Agentic Wallet at the API level:

• Gas estimation via Wallet sign-info API before chain operations (integrated in executor)
• Wallet reachability check during agent onboarding via Onchain OS API

OKX Agentic Wallet provides additional capabilities that agents can use directly:

• Email-based wallet creation via npx skills add okx/onchainos-skills
• TEE-protected key storage (OKX infrastructure, not managed by NexusAgent)
• Gas-optimized stablecoin operations on X Layer (OKX ecosystem)

OKX Onchain OS Evidence

NexusAgent calls three Onchain OS APIs in production code paths:

| API | Code Path | Evidence | |-----|-----------|---------| | Market API | integrations/okxMarket.ts → Sentinel signal | OKB price in workflow output + output/okx-proof/ | | DEX API | integrations/okxDex.ts → DEX quote | Quote response (quote-only, no swap) | | Wallet API | integrations/okxWallet.ts → gas estimation | Sign-info params in executor step output |

All authenticated with HMAC-SHA256 signed headers per OKX Onchain OS specification. Evidence artifacts: output/okx-proof/latest.json

Current Truthfulness Boundary

This repo is intentionally strict about protocol truthfulness.

Live today

• OKB market signal via OKX Onchain OS Market API (authenticated, real-time price data)
• x402 payment endpoint: GET /api/signals/premium-okb returns HTTP 402 with PAYMENT-REQUIRED header, accepts X-PAYMENT for access
• DEX quote via Onchain OS aggregator (quote-only, no swap execution)
• A2A Agent Card at /.well-known/agent.json with 3 skills
• Full workspace-scoped alpha workflow with live OKB signal → conditional decision → bounded execution → RPC verification
• Mainnet settlement proofs with OKB Onchain OS signal (explorer-verifiable)
• ERC-8004 AgentRegistry + ERC-8183 AgentEscrow deployed on X Layer mainnet, called during workflow execution
• MCP server with 5 tools (getokbsignal, getdexquote, checksettlementproof, checkwalletstatus, getintegrationstatus)
• OKX Agentic Wallet API: sign-info for gas estimation in executor, wallet reachability check in onboarding

Integration Notes

• x402 payment: EIP-3009 → OKX facilitator verify → settle → on-chain USDT (proof 1, proof 2)
• Workflow payment step records transfer_event when escrow is funded on-chain
• ERC-8183 escrow lifecycle runs best-effort (graceful degradation if token balance insufficient)
• DEX aggregator returns quote data; swap execution limited by on-chain pair liquidity

---

🔗 Settlement Proof

Mainnet

• TX: 0x5c49ba298cccab1e6c05d1c27b4cc02816d21aa7f3c9de3c40c8d0eba905d37f
• Explorer: View on OKLink
• 0.01 USDT bounded transfer on X Layer mainnet (chain 196)

📦 Deployed Smart Contracts (X Layer Mainnet)

| Contract | Address | Standard | |----------|---------|----------| | AgentRegistry | 0xB4dDf24c8a6cBDEB976d27C4A142f076272EfEC0 | ERC-8004 | | AgentEscrow | 0xa5f560C60F5912bE1a44D24A78B6e82e7C50F455 | ERC-8183 |

4 agents registered on-chain. Escrow lifecycle (create → fund → submit → complete) runs during approved workflows. Current deployment uses single-signer demo ownership; multi-party signing is planned for a future release.

💰 x402 Payment Proof (X Layer Mainnet)

| TX | Explorer | Flow | |----|----------|------| | 0xd6d0fa98... | OKLink | EIP-3009 → OKX verify → settle | | 0x41fe4526... | OKLink | EIP-3009 → OKX verify → settle |

All proof artifacts: [shared/PROOFARTIFACTREGISTER.md](./shared/PROOFARTIFACTREGISTER.md)

API Surface

The backend exposes the following endpoints:

• POST /api/workspaces
• GET /api/workspaces/:workspaceId/context
• POST /api/workspaces/:workspaceId/agents
• GET /api/workspaces/:workspaceId/agents
• POST /api/workspaces/:workspaceId/agents/:agentId/verify-wallet
• POST /api/workspaces/:workspaceId/workflows
• GET /api/workspaces/:workspaceId/workflows
• GET /api/workspaces/:workspaceId/workflows/:workflowRunId
• GET /api/workspaces/:workspaceId/workflows/:workflowRunId/proof
• GET /api/workspaces/:workspaceId/usage

Onchain OS & x402 Endpoints

• GET /api/signals/okb — Live OKB market signal (Onchain OS Market API)
• GET /api/signals/premium-okb — x402-gated premium signal (returns 402 without payment)
• GET /api/integrations/dex-quote — DEX aggregator quote via Onchain OS
• GET /api/integrations/status — Integration status dashboard
• GET /.well-known/agent.json — A2A v0.3 Agent Card
• GET /api/workspaces/:id/usage/summary — Billing summary with per-run pricing

These endpoints establish:

• workspace ownership boundaries
• one workspace key per workspace
• persistent per-workspace agent registration
• wallet reference acceptance and activation gating (format validation + best-effort Onchain OS reachability check)
• one live-signal-backed workflow creation path
• persistent workflow and usage records
• server-side auto-selection of the canonical active agents when explicit agent ids are not provided
• bounded settlement for approved alpha runs (mainnet supported, testnet validated; configurable via execution env vars)

See the [Onboarding page](frontend/src/pages/Onboarding.tsx) for the full quickstart flow.

---

🛠 Run Locally

From the repo root:

./scripts/start_dev_stack.sh

Or run each surface explicitly:

cd ./backend
npm install
npm run dev

cd ./frontend
npm install
npm run dev -- --host 0.0.0.0

Or run the checks directly:

./scripts/validate_all.sh
./scripts/overnight_guard.sh

Check X Layer mainnet readiness:

./scripts/check_mainnet_readiness.sh

If you want to exercise the live X Layer testnet flow with a dedicated test key:

export NEXUSAGENT_XLAYER_TEST_PRIVATE_KEY=...
./scripts/validate_testnet_flow.sh

If you want to prove that the live builder layer can create a workspace-scoped workflow and produce a bounded live settlement artifact:

export NEXUSAGENT_XLAYER_TEST_PRIVATE_KEY=...
./scripts/validate_alpha_live_execution.sh

Hosted Preview Preparation

The repository now includes a hosted preview blueprint:

• [render.yaml](./render.yaml)

Preview deployment assumptions:

• backend and frontend deploy as separate services
• frontend receives VITE_API_BASE_URL
• backend can restrict browser origins with NEXUSAGENT_ALLOWED_ORIGINS
• live execution remains disabled by default in preview

Frontend env example:

• [frontend/.env.example](./frontend/.env.example)

Hosted preview blueprint notes:

• [docs/31HOSTEDPREVIEWBLUEPRINT.md](./docs/31HOSTEDPREVIEWBLUEPRINT.md)

🏗 Architecture Snapshot

✅ Validation

Validation currently includes:

• backend typecheck / schema validation / build
• frontend lint / build
• frontend/backend contract sync
• API smoke test
• live settlement receipt verification through X Layer RPC
• optional bounded execution artifact generation when configured

📁 Repo Structure

• docs/ — protocol truth table, environment contract, validation runbook
• shared/ — agent specs, workflow state machine, proof register, API shapes
• frontend/ — React/Vite frontend
• backend/ — Express/TypeScript backend with OKX Onchain OS integration
• contracts/ — Solidity smart contracts (ERC-8004 AgentRegistry, ERC-8183 AgentEscrow)
• scripts/ — validation, dev stack, sync checks
• examples/ — AI integration demos (REST client, MCP guide, x402 payment flow)

🤖 AI Integration Examples

# Demo 1: External AI agent calls NexusAgent REST API end-to-end
npx tsx examples/01_ai_agent_rest_client.ts

# Demo 2: x402 payment protocol flow (HTTP 402 → pay → 200)
bash examples/03_x402_payment_flow.sh

# Guide: MCP integration for Claude Desktop, GPT, LangChain, etc.
cat examples/02_mcp_integration.md

Commercial Model

NexusAgent charges per workflow run:

• Signal check: 0.01 USDT
• Execution run: 0.10 USDT
• Escrow lifecycle: 0.05 USDT

All billing is usage-based, settled on X Layer via x402. No subscriptions, no credit cards, no KYC. Workspace usage summaries available at GET /api/workspaces/:id/usage/summary.

Roadmap

NexusAgent is designed to become a builder-facing agent workflow operating layer.

Core value chain: Paid market signal → controlled execution → on-chain settlement and proof

Target users: teams building agent-based trading strategies, research automation, or task settlement systems on X Layer.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NexusAgentX-dot
• Source: NexusAgentX-dot/NexusAgent
• License: MIT
• Homepage: https://x.com/NexusAgentX

Install and usage instructions live in the source repository linked above.