okx-onchain-gateway
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOKX Onchain Gateway API
OKX 链上网关API
6 endpoints for gas estimation, transaction simulation, broadcasting, and order tracking.
Base URL:
https://web3.okx.comBase paths: and
/api/v6/dex/pre-transaction/api/v6/dex/post-transactionAuth: HMAC-SHA256 signature, 4 headers required (, , , )
OK-ACCESS-KEYOK-ACCESS-SIGNOK-ACCESS-PASSPHRASEOK-ACCESS-TIMESTAMPNote: Endpoints #1-2 are GET requests, endpoints #3-5 are POST requests, endpoint #6 is GET.
用于燃气费估算、交易模拟、广播及订单追踪的6个端点。
Base URL:
https://web3.okx.com基础路径: 和
/api/v6/dex/pre-transaction/api/v6/dex/post-transaction身份验证: HMAC-SHA256签名,需4个请求头 (, , , )
OK-ACCESS-KEYOK-ACCESS-SIGNOK-ACCESS-PASSPHRASEOK-ACCESS-TIMESTAMP注意: 端点#1-2为 GET 请求,端点#3-5为 POST 请求,端点#6为 GET 请求。
Authentication & Credentials
身份验证与凭证
API Key Application: OKX Developer Portal
Setup Guide: Developer Portal Docs
Read credentials from environment variables:
- → API key
OKX_API_KEY - → Secret key (system-generated)
OKX_SECRET_KEY - → Passphrase (developer-supplied)
OKX_PASSPHRASE
Never output the above credentials to logs, response content, or any user-visible interface.
typescript
import crypto from 'crypto';
const BASE = 'https://web3.okx.com';
// Signature rule:
// GET → body = "", requestPath includes query string (e.g., "/api/v6/dex/pre-transaction/gas-price?chainIndex=1")
// POST → body = JSON string of request body, requestPath is path only (e.g., "/api/v6/dex/pre-transaction/gas-limit")
// Note: Endpoints #1-2, #6 are GET; endpoints #3-5 are POST
async function okxFetch(method: 'GET' | 'POST', path: string, body?: object) {
const timestamp = new Date().toISOString();
const bodyStr = body ? JSON.stringify(body) : '';
const sign = crypto
.createHmac('sha256', process.env.OKX_SECRET_KEY!)
.update(timestamp + method + path + bodyStr)
.digest('base64');
const headers: Record<string, string> = {
'OK-ACCESS-KEY': process.env.OKX_API_KEY!,
'OK-ACCESS-SIGN': sign,
'OK-ACCESS-PASSPHRASE': process.env.OKX_PASSPHRASE!,
'OK-ACCESS-TIMESTAMP': timestamp,
'Content-Type': 'application/json',
};
const res = await fetch(`${BASE}${path}`, {
method,
headers,
...(body && { body: bodyStr }),
});
if (res.status === 429) throw { code: 'RATE_LIMITED', msg: 'Rate limited — retry with backoff', retryable: true };
if (res.status >= 500) throw { code: `HTTP_${res.status}`, msg: 'Server error', retryable: true };
const json = await res.json();
if (json.code !== '0') throw { code: json.code, msg: json.msg || 'API error', retryable: false };
return json.data;
}Response envelope: . = means success.
{ "code": "0", "data": [...], "msg": "" }code"0"API密钥申请: OKX开发者门户
设置指南: 开发者门户文档
从环境变量读取凭证:
- → API密钥
OKX_API_KEY - → 密钥(系统生成)
OKX_SECRET_KEY - → 密码短语(开发者自定义)
OKX_PASSPHRASE
绝对不要将上述凭证输出到日志、响应内容或任何用户可见界面中。
typescript
import crypto from 'crypto';
const BASE = 'https://web3.okx.com';
// Signature rule:
// GET → body = "", requestPath includes query string (e.g., "/api/v6/dex/pre-transaction/gas-price?chainIndex=1")
// POST → body = JSON string of request body, requestPath is path only (e.g., "/api/v6/dex/pre-transaction/gas-limit")
// Note: Endpoints #1-2, #6 are GET; endpoints #3-5 are POST
async function okxFetch(method: 'GET' | 'POST', path: string, body?: object) {
const timestamp = new Date().toISOString();
const bodyStr = body ? JSON.stringify(body) : '';
const sign = crypto
.createHmac('sha256', process.env.OKX_SECRET_KEY!)
.update(timestamp + method + path + bodyStr)
.digest('base64');
const headers: Record<string, string> = {
'OK-ACCESS-KEY': process.env.OKX_API_KEY!,
'OK-ACCESS-SIGN': sign,
'OK-ACCESS-PASSPHRASE': process.env.OKX_PASSPHRASE!,
'OK-ACCESS-TIMESTAMP': timestamp,
'Content-Type': 'application/json',
};
const res = await fetch(`${BASE}${path}`, {
method,
headers,
...(body && { body: bodyStr }),
});
if (res.status === 429) throw { code: 'RATE_LIMITED', msg: 'Rate limited — retry with backoff', retryable: true };
if (res.status >= 500) throw { code: `HTTP_${res.status}`, msg: 'Server error', retryable: true };
const json = await res.json();
if (json.code !== '0') throw { code: json.code, msg: json.msg || 'API error', retryable: false };
return json.data;
}响应格式: 。 = 表示请求成功。
{ "code": "0", "data": [...], "msg": "" }code"0"Developer Quickstart
开发者快速入门
Get Gas Price
获取燃气价格
typescript
// Get current gas price on Ethereum
const gasPrice = await okxFetch('GET', '/api/v6/dex/pre-transaction/gas-price?' + new URLSearchParams({
chainIndex: '1',
}));
// → gasPrice[].normal, gasPrice[].min, gasPrice[].max (legacy)
// → gasPrice[].eip1559Protocol.suggestBaseFee, .proposePriorityFee (EIP-1559)
console.log(`Gas price: ${gasPrice[0].eip1559Protocol?.suggestBaseFee ?? gasPrice[0].normal} wei`);typescript
// 获取以太坊当前燃气价格
const gasPrice = await okxFetch('GET', '/api/v6/dex/pre-transaction/gas-price?' + new URLSearchParams({
chainIndex: '1',
}));
// → gasPrice[].normal, gasPrice[].min, gasPrice[].max (legacy)
// → gasPrice[].eip1559Protocol.suggestBaseFee, .proposePriorityFee (EIP-1559)
console.log(`Gas price: ${gasPrice[0].eip1559Protocol?.suggestBaseFee ?? gasPrice[0].normal} wei`);Broadcast a Signed Transaction
广播已签名交易
typescript
// Broadcast a signed EVM transaction
const result = await okxFetch('POST', '/api/v6/dex/pre-transaction/broadcast-transaction', {
signedTx: '0xf86c...signed_hex',
chainIndex: '1',
address: '0xYourWallet',
});
// → result[].orderId — use with /post-transaction/orders to track
console.log(`Broadcast success, orderId: ${result[0].orderId}`);typescript
// 广播已签名的EVM交易
const result = await okxFetch('POST', '/api/v6/dex/pre-transaction/broadcast-transaction', {
signedTx: '0xf86c...signed_hex',
chainIndex: '1',
address: '0xYourWallet',
});
// → result[].orderId — 用于配合 /post-transaction/orders 接口追踪订单
console.log(`Broadcast success, orderId: ${result[0].orderId}`);Common Chain IDs
常用链ID
| Chain | chainIndex | Chain | chainIndex |
|---|---|---|---|
| Ethereum | | Arbitrum | |
| BSC | | Base | |
| Polygon | | Solana | |
| 公链 | chainIndex | 公链 | chainIndex |
|---|---|---|---|
| Ethereum | | Arbitrum | |
| BSC | | Base | |
| Polygon | | Solana | |
Endpoint Index
端点索引
| # | Method | Path | Docs |
|---|---|---|---|
| 1 | GET | | onchain-gateway-api-chains |
| 2 | GET | | onchain-gateway-api-gas-price |
| 3 | POST | | onchain-gateway-api-gas-limit |
| 4 | POST | | onchain-gateway-api-simulate-transaction |
| 5 | POST | | onchain-gateway-api-broadcast-transaction |
| 6 | GET | | onchain-gateway-api-orders |
Error Codes: Onchain Gateway Error Codes
| # | 请求方法 | 路径 | 文档 |
|---|---|---|---|
| 1 | GET | | onchain-gateway-api-chains |
| 2 | GET | | onchain-gateway-api-gas-price |
| 3 | POST | | onchain-gateway-api-gas-limit |
| 4 | POST | | onchain-gateway-api-simulate-transaction |
| 5 | POST | | onchain-gateway-api-broadcast-transaction |
| 6 | GET | | onchain-gateway-api-orders |
错误码参考: Onchain Gateway Error Codes
Cross-Skill Workflows
跨Skill工作流
This skill is the final mile — it takes a signed transaction and sends it on-chain. It pairs with swap (to get tx data) and balance (to verify funds).
本Skill是最后一环——接收已签名的交易并将其发送至链上。它可与兑换(获取交易数据)和余额查询(验证资金)Skill配合使用。
Workflow A: Swap → Broadcast → Track
工作流A:兑换 → 广播 → 追踪
User: "Swap 1 ETH for USDC and broadcast it"
1. okx-dex-swap /aggregator/swap → get tx calldata { from, to, data, value, gas }
↓ user signs the tx locally
2. okx-onchain-gateway /pre-transaction/broadcast-transaction → broadcast signed tx → orderId
3. okx-onchain-gateway /post-transaction/orders → track order status until confirmedData handoff:
- ,
tx.data,tx.to,tx.valuefrom swap → user builds & signs →tx.gasfor broadcastsignedTx - from broadcast →
orderIdparam in orders queryorderId
用户:"将1 ETH兑换为USDC并广播交易"
1. okx-dex-swap /aggregator/swap → 获取交易调用数据 { from, to, data, value, gas }
↓ 用户本地签名交易
2. okx-onchain-gateway /pre-transaction/broadcast-transaction → 广播已签名交易 → 获取orderId
3. okx-onchain-gateway /post-transaction/orders → 追踪订单状态直至确认数据传递:
- 从兑换Skill获取 ,
tx.data,tx.to,tx.value→ 用户构建并签名交易 → 生成tx.gas用于广播signTx - 从广播接口获取→ 作为订单查询接口的
orderId参数orderId
Workflow B: Simulate → Broadcast → Track
工作流B:模拟 → 广播 → 追踪
User: "Simulate this transaction first, then broadcast if safe"
1. okx-onchain-gateway /pre-transaction/simulate → check if tx will succeed
↓ simulation passes (no revert)
2. okx-onchain-gateway /pre-transaction/broadcast-transaction → broadcast signed tx
3. okx-onchain-gateway /post-transaction/orders → track order status用户:"先模拟这笔交易,安全的话再广播"
1. okx-onchain-gateway /pre-transaction/simulate → 检查交易是否会成功
↓ 模拟通过(无回滚)
2. okx-onchain-gateway /pre-transaction/broadcast-transaction → 广播已签名交易
3. okx-onchain-gateway /post-transaction/orders → 追踪订单状态Workflow C: Balance Check → Swap → Broadcast
工作流C:余额检查 → 兑换 → 广播
User: "Check if I have enough ETH, swap for USDC, then send it"
1. okx-wallet-portfolio /balance/token-balances-by-address → verify ETH balance
↓ sufficient balance confirmed
2. okx-dex-swap /aggregator/swap → get swap tx calldata
↓ user signs
3. okx-onchain-gateway /pre-transaction/broadcast-transaction → broadcast
4. okx-onchain-gateway /post-transaction/orders → track用户:"检查我是否有足够的ETH,兑换为USDC后发送"
1. okx-wallet-portfolio /balance/token-balances-by-address → 验证ETH余额
↓ 确认余额充足
2. okx-dex-swap /aggregator/swap → 获取兑换交易调用数据
↓ 用户签名
3. okx-onchain-gateway /pre-transaction/broadcast-transaction → 广播交易
4. okx-onchain-gateway /post-transaction/orders → 追踪订单Operation Flow
操作流程
Step 1: Identify Intent
步骤1:识别用户意图
- Estimate gas for a chain →
GET /pre-transaction/gas-price - Estimate gas limit for a specific tx →
POST /pre-transaction/gas-limit - Test if a tx will succeed →
POST /pre-transaction/simulate - Broadcast a signed tx →
POST /pre-transaction/broadcast-transaction - Track a broadcast order →
GET /post-transaction/orders - Check supported chains →
GET /pre-transaction/supported/chain
- 估算某条公链的燃气费 →
GET /pre-transaction/gas-price - 估算特定交易的燃气限额 →
POST /pre-transaction/gas-limit - 测试交易是否会成功 →
POST /pre-transaction/simulate - 广播已签名交易 →
POST /pre-transaction/broadcast-transaction - 追踪广播订单 →
GET /post-transaction/orders - 检查支持的公链 →
GET /pre-transaction/supported/chain
Step 2: Collect Parameters
步骤2:收集参数
- Missing → ask which chain
chainIndex - Missing → remind user to sign the transaction first (this API does NOT sign)
signedTx - Missing wallet → ask user
address - For gas-limit / simulate → need ,
fromAddress,toAddress,txAmountextJson.inputData - For orders query → need and
address, optionallychainIndexorderId
- 缺少→ 询问用户具体公链
chainIndex - 缺少→ 提醒用户先签名交易(本API不提供签名功能)
signedTx - 缺少钱包→ 询问用户
address - 燃气限额估算/交易模拟 → 需要,
fromAddress,toAddress,txAmountextJson.inputData - 订单查询 → 需要和
address,可选参数chainIndexorderId
Step 3: Execute
步骤3:执行操作
- Gas estimation: call or
/gas-price, display results/gas-limit - Simulation: call , check for revert or success
/simulate - Broadcast: call with signed tx, return
/broadcast-transactionorderId - Tracking: call , display order status
/orders
- 燃气费估算: 调用或
/gas-price接口,展示结果/gas-limit - 交易模拟: 调用接口,检查是否回滚或成功
/simulate - 交易广播: 携带已签名交易调用接口,返回
/broadcast-transactionorderId - 订单追踪: 调用接口,展示订单状态
/orders
Step 4: Suggest Next Steps
步骤4:建议后续操作
After displaying results, suggest 2-3 relevant follow-up actions based on the endpoint just called:
| Just completed | Suggest |
|---|---|
| 1. Estimate gas limit for a specific tx → |
| 1. Simulate the transaction → |
| 1. Broadcast the transaction → |
| 1. Track order status → |
| 1. Check wallet balance after confirmation → |
Present conversationally, e.g.: "Transaction broadcast! Would you like to track the order status?" — never expose skill names or endpoint paths to the user.
展示结果后,根据刚调用的接口,建议2-3个相关后续操作:
| 刚完成的操作 | 建议操作 |
|---|---|
| 1. 估算特定交易的燃气限额 → |
| 1. 模拟交易 → |
| 1. 广播交易 → |
| 1. 追踪订单状态 → |
| 1. 确认后检查钱包余额 → |
需以对话形式呈现,例如:"交易已广播!需要帮您追踪订单状态吗?" —— 绝不能向用户暴露Skill名称或接口路径。
API Reference
API参考
1. GET /pre-transaction/supported/chain
1. GET /pre-transaction/supported/chain
No request parameters.
Response:
| Field | Type | Description |
|---|---|---|
| String | Chain unique identifier (e.g., "1") |
| String | Chain name (e.g., "Ethereum") |
| String | Chain logo URL |
| String | Chain short name (e.g., "ETH") |
无请求参数。
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
| 字符串 | 公链唯一标识(例如:"1") |
| 字符串 | 公链名称(例如:"Ethereum") |
| 字符串 | 公链Logo地址 |
| 字符串 | 公链简称(例如:"ETH") |
2. GET /pre-transaction/gas-price
2. GET /pre-transaction/gas-price
| Param | Type | Required | Description |
|---|---|---|---|
| String | Yes | Chain ID (e.g., |
Response:
| Field | Type | Description |
|---|---|---|
| String | Normal gas price (legacy) |
| String | Minimum gas price |
| String | Maximum gas price |
| Boolean | Whether EIP-1559 is supported |
| String | Suggested base fee |
| String | Current base fee |
| String | Proposed priority fee |
| String | Safe (slow) priority fee |
| String | Fast priority fee |
For Solana chains, response includes: , , , .
proposePriorityFeesafePriorityFeefastPriorityFeeextremePriorityFeejson
{
"code": "0",
"data": [{
"normal": "20000000000",
"min": "15000000000",
"max": "30000000000",
"supporteip1559": true,
"eip1559Protocol": {
"suggestBaseFee": "18000000000",
"baseFee": "18000000000",
"proposePriorityFee": "2000000000",
"safePriorityFee": "1000000000",
"fastPriorityFee": "3000000000"
}
}],
"msg": ""
}| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 字符串 | 是 | 公链ID(例如: |
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
| 字符串 | 常规燃气价格(legacy) |
| 字符串 | 最低燃气价格 |
| 字符串 | 最高燃气价格 |
| 布尔值 | 是否支持EIP-1559 |
| 字符串 | 建议基础费用 |
| 字符串 | 当前基础费用 |
| 字符串 | 建议优先费用 |
| 字符串 | 安全(慢速)优先费用 |
| 字符串 | 快速优先费用 |
对于Solana公链,响应还包含:, , , 。
proposePriorityFeesafePriorityFeefastPriorityFeeextremePriorityFeejson
{
"code": "0",
"data": [{
"normal": "20000000000",
"min": "15000000000",
"max": "30000000000",
"supporteip1559": true,
"eip1559Protocol": {
"suggestBaseFee": "18000000000",
"baseFee": "18000000000",
"proposePriorityFee": "2000000000",
"safePriorityFee": "1000000000",
"fastPriorityFee": "3000000000"
}
}],
"msg": ""
}3. POST /pre-transaction/gas-limit
3. POST /pre-transaction/gas-limit
| Param | Type | Required | Description |
|---|---|---|---|
| String | Yes | Chain ID |
| String | Yes | Sender address |
| String | Yes | Recipient / contract address |
| String | No | Transfer value in minimal units (default "0") |
| Object | No | Extended parameters |
| String | No | Encoded calldata (for contract interactions) |
Response:
| Field | Type | Description |
|---|---|---|
| String | Estimated gas limit |
json
{
"code": "0",
"data": [{ "gasLimit": "21000" }],
"msg": ""
}| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 字符串 | 是 | 公链ID |
| 字符串 | 是 | 发送者地址 |
| 字符串 | 是 | 接收者/合约地址 |
| 字符串 | 否 | 转账金额(最小单位,默认"0") |
| 对象 | 否 | 扩展参数 |
| 字符串 | 否 | 编码后的调用数据(用于合约交互) |
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
| 字符串 | 估算的燃气限额 |
json
{
"code": "0",
"data": [{ "gasLimit": "21000" }],
"msg": ""
}4. POST /pre-transaction/simulate
4. POST /pre-transaction/simulate
| Param | Type | Required | Description |
|---|---|---|---|
| String | Yes | Chain ID |
| String | Yes | Sender address |
| String | Yes | Recipient / contract address |
| String | No | Transfer value in minimal units |
| String | No | Gas price in wei (for legacy EVM txs) |
| String | No | Priority fee in micro-lamports (Solana only) |
| Object | Yes | Extended parameters |
| String | Yes | Encoded calldata |
Response:
| Field | Type | Description |
|---|---|---|
| String | Transaction intent description |
| Array | Asset changes from the simulation |
| String | Asset type |
| String | Token name |
| String | Token symbol |
| Number | Token decimals |
| String | Token contract address |
| String | Raw amount change |
| String | Gas consumed in simulation |
| String | Failure reason (empty string = success) |
| Array | Risk information (address, addressType) |
json
{
"code": "0",
"data": [{
"intention": "Token Swap",
"assetChange": [{"assetType": "token", "name": "USDC", "symbol": "USDC", "decimals": 6, "address": "0xa0b8...", "rawValue": "-100000000"}],
"gasUsed": "145000",
"failReason": "",
"risks": []
}],
"msg": ""
}| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 字符串 | 是 | 公链ID |
| 字符串 | 是 | 发送者地址 |
| 字符串 | 是 | 接收者/合约地址 |
| 字符串 | 否 | 转账金额(最小单位) |
| 字符串 | 否 | 燃气价格(wei单位,适用于legacy EVM交易) |
| 字符串 | 否 | 优先费用(微lamports单位,仅Solana) |
| 对象 | 是 | 扩展参数 |
| 字符串 | 是 | 编码后的调用数据 |
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
| 字符串 | 交易意图描述 |
| 数组 | 模拟交易后的资产变化 |
| 字符串 | 资产类型 |
| 字符串 | 代币名称 |
| 字符串 | 代币符号 |
| 数字 | 代币小数位数 |
| 字符串 | 代币合约地址 |
| 字符串 | 原始金额变化 |
| 字符串 | 模拟交易消耗的燃气 |
| 字符串 | 失败原因(空字符串表示成功) |
| 数组 | 风险信息(address, addressType) |
json
{
"code": "0",
"data": [{
"intention": "Token Swap",
"assetChange": [{"assetType": "token", "name": "USDC", "symbol": "USDC", "decimals": 6, "address": "0xa0b8...", "rawValue": "-100000000"}],
"gasUsed": "145000",
"failReason": "",
"risks": []
}],
"msg": ""
}5. POST /pre-transaction/broadcast-transaction
5. POST /pre-transaction/broadcast-transaction
| Param | Type | Required | Description |
|---|---|---|---|
| String | Yes | Fully signed transaction (hex for EVM, base58 for Solana) |
| String | Yes | Chain ID |
| String | Yes | Sender wallet address |
| String | No | JSON string of extra options (must |
extraData| Field | Type | Description |
|---|---|---|
| Boolean | Enable MEV protection (ETH/BSC/SOL/BASE) |
| String | Jito signed transaction (Solana) |
Response:
| Field | Type | Description |
|---|---|---|
| String | OKX order tracking ID |
| String | On-chain transaction hash |
json
{
"code": "0",
"data": [{ "orderId": "123456789", "txHash": "0xabc...def" }],
"msg": ""
}| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 字符串 | 是 | 已完全签名的交易(EVM为十六进制,Solana为base58编码) |
| 字符串 | 是 | 公链ID |
| 字符串 | 是 | 发送者钱包地址 |
| 字符串 | 否 | 扩展选项的JSON字符串(发送前需使用 |
extraData| 字段 | 类型 | 描述 |
|---|---|---|
| 布尔值 | 启用MEV保护(支持ETH/BSC/SOL/BASE) |
| 字符串 | Jito签名交易(仅Solana) |
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
| 字符串 | OKX订单追踪ID |
| 字符串 | 链上交易哈希 |
json
{
"code": "0",
"data": [{ "orderId": "123456789", "txHash": "0xabc...def" }],
"msg": ""
}6. GET /post-transaction/orders
6. GET /post-transaction/orders
| Param | Type | Required | Description |
|---|---|---|---|
| String | Yes | Wallet address |
| String | Yes | Chain ID |
| String | No | Specific order ID (from broadcast response) |
| String | No | Filter by status: |
| String | No | Pagination cursor |
| String | No | Max results per page (default 20) |
Response:
| Field | Type | Description |
|---|---|---|
| String | Pagination cursor for next page |
| Array | Order list (nested under each data element) |
| String | Order ID |
| String | On-chain transaction hash |
| String | Chain ID |
| String | Sender address |
| String | Order status: |
| String | Failure reason (if failed) |
json
{
"code": "0",
"data": [{
"cursor": "1",
"orders": [{
"orderId": "123456789",
"txHash": "0xabc...def",
"chainIndex": "1",
"address": "0x...",
"txStatus": "2",
"failReason": ""
}]
}],
"msg": ""
}| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 字符串 | 是 | 钱包地址 |
| 字符串 | 是 | 公链ID |
| 字符串 | 否 | 特定订单ID(来自广播接口响应) |
| 字符串 | 否 | 按状态过滤: |
| 字符串 | 否 | 分页游标 |
| 字符串 | 否 | 每页最大结果数(默认20) |
响应:
| 字段 | 类型 | 描述 |
|---|---|---|
| 字符串 | 下一页的分页游标 |
| 数组 | 订单列表(嵌套在每个data元素下) |
| 字符串 | 订单ID |
| 字符串 | 链上交易哈希 |
| 字符串 | 公链ID |
| 字符串 | 发送者地址 |
| 字符串 | 订单状态: |
| 字符串 | 失败原因(如果交易失败) |
json
{
"code": "0",
"data": [{
"cursor": "1",
"orders": [{
"orderId": "123456789",
"txHash": "0xabc...def",
"chainIndex": "1",
"address": "0x...",
"txStatus": "2",
"failReason": ""
}]
}],
"msg": ""
}Input / Output Examples
输入/输出示例
User says: "What's the current gas price on Ethereum?"
GET /api/v6/dex/pre-transaction/gas-price?chainIndex=1
-> Display:
Base fee: 18 Gwei
Max fee: 25 Gwei
Priority fee: 2 GweiUser says: "Simulate this swap transaction before I send it"
POST /api/v6/dex/pre-transaction/simulate
Body: {
"chainIndex": "1",
"fromAddress": "0xYourWallet",
"toAddress": "0xDexContract",
"txAmount": "1000000000000000000",
"extJson": { "inputData": "0x..." }
}
-> Display:
Simulation: SUCCESS (failReason is empty)
Estimated gas: 145,000
Intent: Token SwapUser says: "Broadcast my signed transaction"
POST /api/v6/dex/pre-transaction/broadcast-transaction
Body: {
"signedTx": "0xf86c...signed",
"chainIndex": "1",
"address": "0xYourWallet"
}
-> Display:
Broadcast successful!
Order ID: 123456789
Tx Hash: 0xabc...defUser says: "Check the status of my broadcast order"
GET /api/v6/dex/post-transaction/orders?address=0xYourWallet&chainIndex=1&orderId=123456789
-> Response: data[0].orders[0] contains order details
-> Display:
Order 123456789: Success (txStatus=2)
Tx Hash: 0xabc...def
Confirmed on-chain用户提问: "以太坊当前的燃气价格是多少?"
GET /api/v6/dex/pre-transaction/gas-price?chainIndex=1
-> 展示:
基础费用: 18 Gwei
最高费用: 25 Gwei
优先费用: 2 Gwei用户提问: "在我发送之前先模拟这笔兑换交易"
POST /api/v6/dex/pre-transaction/simulate
Body: {
"chainIndex": "1",
"fromAddress": "0xYourWallet",
"toAddress": "0xDexContract",
"txAmount": "1000000000000000000",
"extJson": { "inputData": "0x..." }
}
-> 展示:
模拟结果: 成功(failReason为空)
估算燃气消耗: 145,000
交易意图: 代币兑换用户提问: "广播我的已签名交易"
POST /api/v6/dex/pre-transaction/broadcast-transaction
Body: {
"signedTx": "0xf86c...signed",
"chainIndex": "1",
"address": "0xYourWallet"
}
-> 展示:
广播成功!
订单ID: 123456789
交易哈希: 0xabc...def用户提问: "查询我广播的订单状态"
GET /api/v6/dex/post-transaction/orders?address=0xYourWallet&chainIndex=1&orderId=123456789
-> 响应: data[0].orders[0]包含订单详情
-> 展示:
订单123456789: 成功(txStatus=2)
交易哈希: 0xabc...def
已在链上确认Edge Cases
边缘情况
- MEV protection: Broadcasting through OKX nodes may offer MEV protection on supported chains — confirm with OKX documentation for chain-specific behavior.
- Solana special handling: Solana signed transactions use base58 encoding (not hex). Ensure the format matches the chain.
signedTx - Chain not supported (81104): call first to verify. Not all chains support all endpoints.
/pre-transaction/supported/chain - Node return failed (81451): the underlying blockchain node rejected the transaction. Common causes: insufficient gas, nonce too low, contract revert. Retry with corrected parameters.
- Wallet type mismatch (81108): the address format does not match the chain (e.g., EVM address on Solana chain).
- 429 rate limit: exponential backoff with jitter. See Rate Limit & Fee Docs for tier-specific RPS limits (Trial: 1 RPS, Start-up: 2-50 RPS, Enterprise: custom).
- Cross-skill pipeline rate limit: when chaining calls across multiple skills (e.g., swap → simulate → broadcast), add 300-500ms delay between requests to avoid triggering rate limit (error code ).
50011 - Network error: retry once, then prompt user to try again later
- Request timeout: all API calls must set a 10-second timeout limit
- Transaction already broadcast: if the same is broadcast twice, the API may return an error or the same
signedTx— handle idempotently.txHash
- MEV保护: 通过OKX节点广播交易可能在支持的公链上提供MEV保护——请参考OKX文档确认各公链的具体行为。
- Solana特殊处理: Solana已签名交易使用base58编码(而非十六进制)。确保格式与对应公链匹配。
signedTx - 公链不支持(错误码81104): 先调用接口验证。并非所有公链都支持所有端点。
/pre-transaction/supported/chain - 节点返回失败(错误码81451): 底层区块链节点拒绝了交易。常见原因:燃气不足、nonce值过低、合约回滚。修正参数后重试。
- 钱包类型不匹配(错误码81108): 地址格式与公链不匹配(例如:在Solana链上使用EVM地址)。
- 429请求超限: 使用指数退避策略并添加随机抖动。请参考Rate Limit & Fee Docs查看不同层级的RPS限制(试用版:1 RPS,初创版:2-50 RPS,企业版:自定义)。
- 跨Skill流水线请求超限: 当跨多个Skill链式调用时(例如:兑换→模拟→广播),在请求之间添加300-500ms延迟以避免触发请求超限(错误码)。
50011 - 网络错误: 重试一次,然后提示用户稍后再试
- 请求超时: 所有API调用必须设置10秒超时限制
- 交易已广播: 如果同一被广播两次,API可能返回错误或相同的
signedTx——需处理幂等性。txHash
Amount Display Rules
金额展示规则
- Gas prices in Gwei for EVM chains (), never raw wei
18.5 Gwei - Gas limit as integer (,
21000)145000 - USD gas cost estimate when possible
- Transaction values in UI units (), never base units
1.5 ETH
- EVM公链的燃气价格以Gwei为单位(例如),绝不显示原始wei值
18.5 Gwei - 燃气限额以整数展示(例如,
21000)145000 - 尽可能展示以USD为单位的燃气成本估算
- 交易金额以UI单位展示(例如),绝不显示基础单位
1.5 ETH
Global Notes
全局注意事项
- This skill does NOT sign transactions — it only broadcasts pre-signed transactions
- Amounts in API params use minimal units (wei/lamports)
- Gas price fields: use +
eip1559Protocol.suggestBaseFeefor EIP-1559 chains,eip1559Protocol.proposePriorityFeefor legacynormal - EVM contract addresses must be all lowercase
- For swap quote and execution → use
okx-dex-swap - For market prices → use
okx-dex-market - For balance queries → use
okx-wallet-portfolio - For token search → use
okx-dex-token - For transaction broadcasting → use this skill ()
okx-onchain-gateway
- 本Skill不提供交易签名功能——仅广播已预先签名的交易
- API参数中的金额使用最小单位(wei/lamports)
- 燃气价格字段:对于支持EIP-1559的公链,使用+
eip1559Protocol.suggestBaseFee;对于legacy公链,使用eip1559Protocol.proposePriorityFeenormal - EVM合约地址必须为全小写
- 兑换报价和执行操作 → 使用
okx-dex-swap - 市场价格查询 → 使用
okx-dex-market - 余额查询 → 使用
okx-wallet-portfolio - 代币搜索 → 使用
okx-dex-token - 交易广播 → 使用本Skill ()
okx-onchain-gateway