开发者平台
主题
介绍
指南
使用 AI 搭建
搭建兑换应用
DEX SDK
兑换 API
介绍
API 参考
设置分佣
做市商接入
意圖交易接入
意图交易solver詢價意图交易solver求解意图交易solver結算意图交易Solver管理
智能合约错误码FAQ
交易上链 API
介绍
API 参考
错误码
资源
使用 WidgetAPI 费用智能合约安全支持
兑换 API

OKX Intent 概述#

OKX Intent 採用並行拍賣機制:系統在不同的時間視窗與批次中並行推進多場拍賣,並同步觸發 Solver 的求解與獲勝者選定流程,不需等待上一輪完全結算後才開始下一輪。此機制能更充分地利用 Solver 的算力以及鏈上區塊時間,大幅降低從下單到結算的端到端延遲,為使用者提供更穩定且更快速的交易體驗。

名詞說明#

名詞說明
Intent Order使用者基於 Intent 的訂單,包含 fromTokenAddress、fromTokenAmount、toTokenAddress、toTokenAmount、validTo 等欄位。
Quote使用者向 Solver 取得的訂單價格預估。
Orderbook使用者與協議互動的入口。負責接收使用者的詢價請求,驗證並儲存使用者已簽章的訂單。
Autopilot協議的核心調度引擎。維護全域狀態、建立批次拍賣、將拍賣分發給 Solver,並選出最佳解決方案。
結算合約 (Settlement Contract)鏈上負責執行交易的合約。僅有白名單中的 Solver 可以呼叫。
Auction(拍賣)一種批次拍賣機制,將時間視窗內的所有待處理訂單彙總,讓 Solver 競爭以提出最佳解。
Parallel Auction(並行拍賣)多場拍賣同時進行(分發、求解、獲勝者選定與結算可重疊),以縮短使用者等待時間。
Solution(解)Solver 針對某場拍賣提交的可執行方案,包含哪些訂單被成交、執行數量、結算價格等。
Clearing Prices(結算價)在單場拍賣的結算中,每個 Token 都有一個結算價,用於計算結算時的執行數量,以及驗證每筆訂單的最低收到數量是否被滿足。
最低收到數量 (Minimum Received Amount)使用者在取得最佳報價後,簽署 Intent 訂單時所指定的最低可接受收到數量。
Baseline(基準)由 Baseline Solver 提供的參考報價,作為基準用以判斷某 Solver 的報價是否低於市場一般水準。
Surplus(盈餘)最終實際執行結果與使用者報價中可接受的最低價格之間的差額。
Score(評分)一個 Solution 中所有訂單 Surplus 的加總。

系統概覽#

流程#

  • Trader(使用者): 發出詢價請求 → 選擇報價 → 簽署訂單(EIP-712 / eth_sign / EIP-1271 / presign)。
  • Orderbook: 驗證並儲存訂單。
  • Autopilot: 定期將訂單批次化,並行地將訂單 / 結算價 / 約束條件分發給 Solver。
  • Solver: 計算最佳的撮合 / 路由方案,並提交 Solution;Autopilot 從中選出評分最高者為獲勝者。
  • 獲勝 Solver(鏈上): 呼叫 Settlement.settle(tokens, clearingPrices, trades, interactions[0..2]),在單筆交易中完成結算。

接入前置條件#

Solver KYB#

  • 完成 CeFi KYB 並提供 UID。

Solver 地址白名單#

  • 支援的地址類型:EOA / 合約錢包
  • 白名單申請流程:KYB 完成後 → 提交地址 → 鏈上白名單生效

Solver 端需提供的資料 / 資訊#

合約白名單資料:

  • Chain(鏈)
  • Solver 地址

Gateway 白名單資料:

  • 接入網域名稱

設定平台白名單資料:

  • Chain ID
  • Solver 地址
  • 接入網域名稱
  • 是否需要限流要求

接入測試流程#

  • Beta 測試: 使用 Beta 環境與 Beta 合約。在 Beta 環境中測試 /quote、/solve、/settle 等 API,包含手續費測試與壓力測試,涵蓋完整的端到端流程。Solver 使用非生產訂單測試。若需透過 OKX 下單,需 OKX 端配合與支援。
  • Shadow 測試: 使用生產合約進行測試。我們會提供 JS 腳本給 Solver,用於下單並完整跑通 /quote、/solve、/settle 流程。每條鏈需累積 15 筆成功訂單,且成功率高於 80%。
  • Staging 測試: 使用生產合約,在生產環境中與既有 Solver 競爭。此階段不接收真實使用者訂單,Solver 需自行透過 JS 腳本下單。每條鏈需累積 5 筆成功訂單,且成功率高於 80%。
  • Go Live(正式上線): 使用生產環境、生產合約與真實生產訂單,正式上線。

SLA / 效能要求#

/quote 延遲與可用性#

SLA:所有鏈 ≤ 2.5 秒;逾時視為放棄該次報價。

指標鏈通過標準
回應時間ALL≤ 2.5s

單筆訂單拍賣回應時間#

SLA:所有鏈 ≤ 4 秒。

指標鏈通過標準
回應時間ALL≤ 4s
逾時放棄率ALL≤ 10%

多筆訂單拍賣回應時間(各鏈)#

指標鏈通過標準
回應時間ETH≤ 8s
回應時間ARB≤ 4s
回應時間Base≤ 4s
回應時間BSC≤ 6.75s
逾時放棄率ALL≤ 20%

解的品質#

指標鏈通過標準
Solution 回傳率ALL≥ 80%
鏈上成功率(1 小時視窗)ALL≥ 80%

Deadline 內鏈上完成率 — 多筆訂單拍賣#

指標鏈通過標準
在區塊 Deadline 內完成結算ETH≥ 80%(3 區塊)
在區塊 Deadline 內完成結算ARB≥ 80%(40 區塊)
在區塊 Deadline 內完成結算Base≥ 80%(18 區塊)
在區塊 Deadline 內完成結算BSC≥ 80%(40 區塊)

Deadline 內鏈上完成率 — 單筆訂單拍賣#

指標鏈通過標準
在區塊 Deadline 內完成結算ETH≥ 80%(2 區塊)
在區塊 Deadline 內完成結算ARB≥ 80%(30 區塊)
在區塊 Deadline 內完成結算Base≥ 80%(10 區塊)
在區塊 Deadline 內完成結算BSC≥ 80%(22 區塊)

壓力測試(/quote)#

以 30 QPS 並發發送 /quote 請求,驗證 Solver 在高負載下的穩定性。

指標鏈通過標準
目標 QPSALL≥ 30 QPS
高負載下 /quote 回應時間ALL≤ 2.5s
高負載下 /quote 逾時率ALL≤ 10%

Solver API#

端點清單#

  • 向前相容性: 請求 / 回應主體中可能隨時新增欄位,實作時請忽略未知欄位,不要做嚴格的欄位驗證。
  • Solver 應依照本規格實作 API。
  • 所有端點皆使用 POST 方法,並以 JSON 作為請求主體。
  • 所有時間戳皆為毫秒(例如 172120120102)。
  • EVM 相容鏈上,所有地址使用小寫 0x 前綴的十六進位編碼(20 bytes)。非 EVM 鏈則沿用其原生地址格式。
  • 數量欄位使用 String 型別,以最小單位表示。
  • Solver 必須在 deadline 指定的時間內回傳回應。
  • 使用 DIP 服務 — 無需白名單。
    • 若需 IP 白名單:47.243.1.144-159、47.254.152.31、47.89.234.165、18.157.58.16、3.65.240.18、63.181.55.143(共 21 個 IP)。
端點方法URL說明
QuotePOSThttps://your-api-endpoint.com/OKXDEX/intent/quote取得價格預估(報價)。
SolvePOSThttps://your-api-endpoint.com/OKXDEX/intent/solve對傳入的拍賣進行求解。
SettlePOSThttps://your-api-endpoint.com/OKXDEX/intent/settle將已求解的拍賣結算上鏈。
NotifyPOSThttps://your-api-endpoint.com/OKXDEX/intent/notify接收系統通知(如停用通知等)。

統一回應結構#

回應參數

參數型別必填說明
codeInteger是狀態碼。0 表示成功;非零表示失敗。
msgString否成功或錯誤訊息。
dataObject否回應內容(成功時返回)。

成功回應範例

json
{
  "code": 0,
  "msg": "success",
  "data": { ... }
}

錯誤回應範例

json
{
  "code": 500,
  "msg": "Internal server error",
  "data": null
}
目录