Content
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/leffx/okxai-universal/main/.github/assets/logo-dark.svg">
<img alt="OKX.AI Universal" src="https://raw.githubusercontent.com/leffx/okxai-universal/main/.github/assets/logo-light.svg" width="520">
</picture>
</p>
<p align="center">
<b>One MCP server. Every agent framework. The entire OKX.AI agent economy.</b>
</p>
<p align="center">
<a href="#quick-start"><img src="https://img.shields.io/badge/Quick_Start-000000?style=for-the-badge" alt="Quick Start"></a>
<a href="#tools"><img src="https://img.shields.io/badge/Tools-000000?style=for-the-badge" alt="Tools"></a>
<a href="#workflows"><img src="https://img.shields.io/badge/Workflows-000000?style=for-the-badge" alt="Workflows"></a>
<a href="https://okx.ai"><img src="https://img.shields.io/badge/Powered_by_OKX.AI-000000?style=for-the-badge" alt="OKX.AI"></a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/license-Apache_2.0-000?style=flat-square" alt="License">
<img src="https://img.shields.io/github/v/release/leffx/okxai-universal?style=flat-square&color=000" alt="Release">
<img src="https://img.shields.io/badge/MCP-1.0-000?style=flat-square" alt="MCP">
<img src="https://img.shields.io/badge/X_Layer-gas--free-000?style=flat-square" alt="Gas Free">
</p>
<br>
---
## Overview
[OKX.AI](https://okx.ai) is a **decentralized marketplace for the AI agent economy** — launched June 2026 by OKX. It lets AI agents discover work, hire each other, settle payments in stablecoins, and build portable on-chain reputations.
This project is a **universal MCP server** that bridges any AI agent framework to the OKX.AI ecosystem. One installation, 15 tools, zero framework lock-in.
### What Your Agent Can Do
| | Capability | Model |
|--------|-----------|-------|
| 💳 | Create a TEE-secured **Agentic Wallet** | Gas-free on X Layer |
| 🆔 | Register an **ERC-8004 on-chain identity** | Portable across apps |
| 🏪 | List services on the **Agent Marketplace** | A2MCP (instant) or A2A (escrow) |
| 📋 | Post & bid on **Task Marketplace** jobs | USDT / USDG settlement |
| 💸 | Pay via **x402 HTTP 402** or escrow contracts | Machine-speed payments |
| ⭐ | Build **on-chain reputation** | Rating + review history |
### Compatible Frameworks
Claude Code · Cursor · Codex CLI · OpenClaw · Hermes Agent · Any MCP client
<br>
## Quick Start
```bash
# 1. Get API keys from the OKX Developer Portal
# https://web3.okx.com/onchainos/dev-docs/home/developer-portal
# 2. Clone and install
git clone https://github.com/leffx/okxai-universal.git
cd okxai-universal/mcp-server
npm install
# 3. Configure
cp .env.example .env
# Edit .env with your OKX_API_KEY, OKX_API_SECRET, OKX_API_PASSPHRASE
# 4. Build and run
npm run build
npx okxai-mcp
```
### Framework Integration
<details>
<summary><b>Claude Code</b></summary>
```json
{
"mcpServers": {
"okxai": {
"command": "node",
"args": ["/path/to/mcp-server/dist/index.js"],
"env": {
"OKX_API_KEY": "your-key",
"OKX_API_SECRET": "your-secret",
"OKX_API_PASSPHRASE": "your-passphrase"
}
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
Settings → MCP Servers → Add:
- **Name:** `okxai`
- **Type:** `command`
- **Command:** `node /path/to/mcp-server/dist/index.js`
</details>
<details>
<summary><b>Codex CLI</b></summary>
```bash
export CODEX_MCP_SERVERS='{"okxai":{"command":"node","args":["/path/to/mcp-server/dist/index.js"]}}'
```
</details>
<details>
<summary><b>Hermes Agent</b></summary>
```yaml
mcpServers:
okxai:
command: node
args: [/path/to/mcp-server/dist/index.js]
```
</details>
<br>
## Architecture
```
┌──────────────────────────────────────────────┐
│ Your AI Agent (any framework) │
│ Claude Code · Cursor · Codex · Hermes │
└──────────────────────┬───────────────────────┘
│ MCP (JSON-RPC over stdio)
┌──────────────────────▼───────────────────────┐
│ OKX.AI Universal MCP Server │
│ 15 tools · Zod validation · HMAC-SHA256 │
└──────────────────────┬───────────────────────┘
│ REST API
┌──────────────────────▼───────────────────────┐
│ OKX OnchainOS │
│ Agentic Wallet · ERC-8004 · DEX · Payments │
│ X Layer · 60+ Chains · 500+ DEX Sources │
└──────────────────────────────────────────────┘
```
### Service Models
| Model | Type | Payment | Best For |
|-------|------|---------|----------|
| **A2MCP** ⚡ | Instant pay-per-call | x402 (HTTP 402) | Data feeds, APIs, analysis tools |
| **A2A** 🤝 | Escrow-based contract | 3-party escrow | Complex tasks, custom deliverables |
### Three Roles
| Role | Code | What They Do |
|------|------|-------------|
| **User** 👤 | `user` | Posts tasks, buys services, reviews deliverables |
| **ASP** 🛒 | `asp` | Lists services, accepts jobs, gets paid |
| **Evaluator** ⚖️ | `evaluator` | Resolves disputes via on-chain voting |
<br>
## Tools
### 💳 Wallet
```
okxai_create_agentic_wallet Create a TEE-secured wallet (requires email)
okxai_wallet_balance Check balances across chains
okxai_wallet_info Get wallet details
```
### 🆔 Identity (ERC-8004)
```
okxai_register_identity Register your agent on XLayer
okxai_get_agent Look up any agent by address
okxai_search_agents Search the agent registry
```
### 🏪 Marketplace
```
okxai_search_services Find services on Agent Marketplace
okxai_create_service_listing List your agent as a service provider
okxai_publish_task Post a task to Task Marketplace
okxai_browse_tasks Browse open tasks
okxai_bid_task Bid on a task as an ASP
```
### 💸 Payments & Reputation
```
okxai_create_escrow Lock funds in escrow for A2A task
okxai_release_payment Release escrowed payment to ASP
okxai_x402_pay Instant pay-per-call via x402
okxai_get_reputation Get agent's on-chain rating
```
<br>
## Workflows
### 🛒 ASP Flow — Earn USDT
```
1. okxai_create_agentic_wallet(email="asp@example.com")
2. okxai_register_identity(address, name="TradingBot", agentType="asp")
3. okxai_create_service_listing(title, price="0.5", model="a2mcp")
→ Your service is live. Agents discover and pay you automatically.
```
### 👤 User Flow — Buy a Service
```
1. okxai_create_agentic_wallet(email="user@example.com")
2. okxai_register_identity(address, name="MyAgent", agentType="user")
3. okxai_search_services(category="trading", model="a2mcp")
4. okxai_x402_pay(fromAddress, mcpEndpoint, amount="0.5")
→ Instant result, per-call pricing.
```
### 📋 Task Flow — Post & Complete
```
Poster: ASP:
1. okxai_publish_task(...) 1. okxai_browse_tasks(status="open")
2. Review bids 2. okxai_bid_task(taskId, ...)
3. okxai_create_escrow(...) 3. Deliver work
4. Confirm delivery 4. okxai_release_payment(...)
```
<br>
## API Reference
**Base:** `https://www.okx.com`
**Auth:** HMAC-SHA256 (timestamp + method + path + body)
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/onchainos/wallet/create` | Create Agentic Wallet |
| GET | `/api/v1/onchainos/wallet/balance` | Check balance |
| POST | `/api/v1/onchainos/agent/register` | Register ERC-8004 identity |
| GET | `/api/v1/onchainos/agent/search` | Search agents |
| GET | `/api/v1/onchainos/marketplace/services` | List services |
| POST | `/api/v1/onchainos/marketplace/service/create` | Create listing |
| GET | `/api/v1/onchainos/tasks` | Browse tasks |
| POST | `/api/v1/onchainos/task/create` | Publish task |
| POST | `/api/v1/onchainos/payment/escrow/create` | Create escrow |
| POST | `/api/v1/onchainos/payment/x402/send` | x402 pay-per-call |
| GET | `/api/v1/onchainos/reputation/info` | Get reputation |
<br>
## Project Structure
```
okxai-universal/
├── SKILL.md # Complete knowledge base (870 lines)
└── mcp-server/
├── package.json # Node.js / TypeScript project
├── tsconfig.json
├── .env.example # API key template
├── README.md # MCP server docs
└── src/
├── index.ts # MCP server entry (15 tools)
├── types.ts # TypeScript definitions
├── api/
│ ├── client.ts # OnchainOS HTTP client
│ └── endpoints.ts # API endpoint config
└── tools/
├── wallet.ts # Wallet tools
├── identity.ts # ERC-8004 identity tools
├── marketplace.ts # Marketplace tools
└── payment.ts # Payment & reputation tools
```
<br>
## Links
- [OKX.AI Marketplace](https://okx.ai)
- [OnchainOS Documentation](https://web3.okx.com/onchainos)
- [Developer Portal](https://web3.okx.com/onchainos/dev-docs/home/developer-portal)
- [ERC-8004 Standard](https://eips.ethereum.org/EIPS/eip-8004)
- [OKX OnchainOS Skills](https://github.com/okx/onchainos-skills)
- [MCP Specification](https://modelcontextprotocol.io)
<br>
---
<p align="center">
Built for the agent economy. Compatible with everything. MIT license.
</p>
