orderly-one-dex

Orderly Network：Orderly One DEX

Orderly One（https://dex.orderly.network）是一个平台，任何人都可以在 Orderly Network 上启动白标永续合约 DEX，无论是否编写代码。它既提供：

1. Web UI：dex.orderly.network，用户可通过分步向导创建、配置和部署 DEX。
2. REST API：AI agent 或脚本可以调用该 API，以编程方式完成相同操作。

重要提示： 对于毕业认证和经纪商 ID 创建（这一步可解锁手续费收入），Agent 可以通过 x402 HTTP 支付协议（POST /api/graduation/graduate）付款，并在单个请求中注册经纪商，无需浏览器。对于非技术用户，https://dex.orderly.network/dex 上的网页门户仍是最简单的途径；请务必告知他们还有此选项。

两种启动途径

途径	说明	毕业认证费用	适用对象
低代码	通过 Orderly One 门户或 API 创建品牌化 DEX 前端。系统会分叉模板仓库并部署到 GitHub Pages。	$100	希望快速启动且尽量减少前端工作量的团队
自定义 SDK/API	使用 Orderly SDK 或 API 构建完全自定义的前端。通过 Orderly One 完成毕业认证以获取经纪商 ID——无需 DEX 前端。	$10	钱包、现有交易所、希望完全掌控项目的团队

请参阅官方构建者入门指南：https://orderly.network/docs/introduction/getting-started/builder-onboarding

适用场景

• 创建自定义永续合约 DEX
• 管理 DEX 部署、域名或主题
• 办理毕业认证以参与手续费分成

---

核心概念

• 经纪商 ID：Orderly 生态系统中的唯一标识符。初始值为 "demo"，毕业认证后会变为真实的经纪商 ID。这是你的 DEX 赚取交易手续费的方式。
• 毕业认证：支付 $10-$100 并注册为经纪商，将演示 DEX 转变为可赚取手续费的 DEX 的流程。
• 模板仓库：为每个低代码 DEX 分叉的 GitHub 仓库，其中包含 Orderly SDK 交易前端。
• 每位用户只能创建一个 DEX：每个钱包地址只能创建一个 DEX。

---

API 基础 URL

环境	基础 URL
主网	https://dex-api.orderly.network
测试网	https://testnet-dex-api.orderly.network

API 在根路径提供交互式 OpenAPI 规范（Scalar）：GET /

支持毕业认证的链（支付）

主网：Ethereum (1)、Arbitrum (42161)、Base (8453) 测试网：Sepolia、Arbitrum Sepolia、Base Sepolia

---

API 类别

使用 get_orderly_one_api_info MCP 工具获取完整的端点详情。

类别	描述	关键端点
auth	钱包签名身份验证	/api/auth/nonce、/api/auth/verify、/api/auth/validate
dex	DEX 的增删改查、域名和部署	/api/dex、/api/dex/{id}、/api/dex/{id}/custom-domain、/api/dex/{id}/workflow-status
theme	AI 主题生成	/api/theme/modify、/api/theme/fine-tune
graduation	演示版 → 完整 DEX，并共享费用	/api/graduation/graduate (x402)、/api/graduation/verify-tx、/api/graduation/fee-options、/api/graduation/refund
leaderboard	跨 DEX 排名	/api/leaderboard、/api/leaderboard/broker/{brokerId}
stats	平台统计数据	/api/stats、/api/stats/swap-fee-config

---

创建/更新 DEX

POST /api/dex（创建）和 PUT /api/dex/{id}（更新）都使用 multipart/form-data。

必填字段

字段	类型	约束
brokerName	string	3-30 个字符，只能包含字母数字、空格、点号或连字符

可选字段

链：

字段	类型	说明
chainIds	number[] (JSON)	例如 [42161, 10, 8453]
defaultChain	number	默认链 ID

品牌（文件）：

字段	类型	最大大小
primaryLogo	File	250KB
secondaryLogo	File	100KB
favicon	File	50KB
pnlPoster0..N	File	每个 250KB

主题：

字段	类型	说明
themeCSS	string	用于覆盖默认主题的 CSS 变量
tradingViewColorConfig	string	图表颜色的 JSON

社交：

字段	类型	说明
telegramLink	string	URL
discordLink	string	URL
xLink	string	URL

身份验证/钱包：

字段	类型	说明
walletConnectProjectId	string	WalletConnect 项目 ID
privyAppId	string	Privy 应用 ID
privyTermsOfUse	string	条款 URL
privyLoginMethods	string	以逗号分隔
enableAbstractWallet	boolean	启用 Abstract 钱包
disableEvmWallets	boolean	禁用 EVM 钱包
disableSolanaWallets	boolean	禁用 Solana 钱包

网络：

字段	类型	说明
disableMainnet	boolean	禁用主网
disableTestnet	boolean	禁用测试网

交易：

字段	类型	说明
swapFeeBps	number (0-100)	以基点表示的 Swap 费用（需要在 enabledMenus 中启用 "Swap"）
symbolList	string	以逗号分隔（PERP_ETH_USDC）

菜单：

字段	类型	说明
enabledMenus	string	以逗号分隔。选项：Trading、Portfolio、Markets、Leaderboard（默认）、Swap、Rewards、Vaults、Points
customMenus	string	格式："Name,URL;Name2,URL2"

SEO：

字段	类型	限制
seoSiteName	string	最多 100 个字符
seoSiteDescription	string	最多 300 个字符
seoSiteLanguage	string	"en" 或 "en-US"
seoSiteLocale	string	"en_US"
seoTwitterHandle	string	"@handle"
seoThemeColor	string	"#1a1b23"
seoKeywords	string	最多 500 个字符

其他：

字段	类型	说明
availableLanguages	string	JSON 数组。选项：en、zh、tc、ja、es、ko、vi、de、fr、ru、id、tr、it、pt、uk、pl、nl
analyticsScript	string	Base64 编码
enableServiceDisclaimerDialog	boolean	显示免责声明
enableCampaigns	boolean	启用 ORDER 代币活动和 Points 菜单
restrictedRegions	string	以逗号分隔的国家名称（例如："United States,China"）
whitelistedIps	string	IP 白名单

响应

创建（201）： { id, brokerId, brokerName, repoUrl, userId, createdAt }

更新（200）： 包含所有字段的完整 DEX 对象

---

关键工作流

身份验证

Orderly One 拥有独立的身份验证系统，与 Orderly Network API（api.orderly.org）分离。它使用标准 EVM personal_sign（EIP-191）——仅支持 EVM 钱包（0x 地址）。

1. 使用 { "address": "0x..." } 调用 POST /api/auth/nonce → 返回 { message, nonce }
2. 使用 personal_sign（EIP-191）对返回的 message 签名
3. 使用 { "address": "0x...", "signature": "0x..." } 调用 POST /api/auth/verify → 返回 { user: { id, address }, token }
4. 后续所有请求都使用 Authorization: Bearer {token}（有效期 24 小时）
5. 验证：使用 { "address", "token" } 调用 POST /api/auth/validate → 返回 { valid: true/false }

注意： 毕业流程中的“最终确定管理员钱包”步骤需要通过 Orderly Network API（api.orderly.org）进行身份验证——这是一个使用 EIP-712 或 Ed25519 签名的独立系统。请参阅下方的毕业流程。

创建 DEX 流程

1. 使用上述字段构建 multipart/form-data
2. 调用 POST /api/dex → 返回 { id, brokerId, repoUrl }
3. 轮询 GET /api/dex/{id}/workflow-status，直到 conclusion: "success"

毕业（费用分成）

前提条件： 已创建 brokerId: "demo" 的 DEX（尚未毕业），并在 Base、Arbitrum 或 Ethereum 上持有原生 USDC，用于支付 x402 费用。

步骤 1 — 获取费用选项：

GET /api/graduation/fee-options → { usdc: { amount }, receiverAddress, payerAddress }

• 低代码：100 美元 | 自定义 SDK：10 美元 — 通过 x402 使用 USDC 支付
• payerAddress 是经过身份验证的钱包——必须与付款钱包相同

步骤 2 — 通过 x402 支付（适合 Agent）：

使用 Authorization: Bearer 调用 POST /api/graduation/graduate?brokerId=…&makerFee=…&takerFee=…&rwaMakerFee=…&rwaTakerFee=…——在单个请求中支付费用并注册经纪商。

• 首次 POST 返回 402，并带有 payment-required 响应头（base64 JSON）：每个网络（base 8453、arbitrum 42161、ethereum 1）各提供一个 EIP-3009 USDC transferWithAuthorization 选项
• 对 EIP-712 授权签名，并通过 payment-signature 请求头重试 → 200：转账已在链上结算（交易哈希位于 PAYMENT-RESPONSE 响应头的 .transaction 字段），经纪商会自动注册
• 付款方无需支付 Gas 费——服务器会中继结算；参数无效时会在扣款前返回 400/401，并取消付款
• EIP-3009 付款钱包必须与通过 Bearer 验证的账户钱包相同
• x402 客户端（@x402/fetch）的 spendControls.maxAmountPerPayment 默认值为 1 美元——请提高此值以覆盖费用
• 两步模式：不带查询参数发送 POST（无需 Bearer——付款即为身份验证），然后在步骤 3 中调用 verify-tx，并传入结算交易哈希和 paymentType: "usdc"
• 如果付款已结算但毕业失败，可申请退款：调用 POST /api/graduation/refund {txHash, chain}（需 Bearer，使用付款钱包）

步骤 3 — 验证交易（仅适用于两步 x402；如果已自动完成则跳过）：

调用 POST /api/graduation/verify-tx，并传入：

字段	说明
txHash	PAYMENT-RESPONSE 响应头中的结算交易哈希
chain	付款所在的链：base、arbitrum 或 ethereum
brokerId	期望的经纪商 ID（5–15 个字符，^[a-z0-9_-]+$）
makerFee	Maker 费率，单位为 bps（-0.5 至 15，按 0.1 递增；负值表示返利）
takerFee	Taker 费率，单位为 bps（1 至 15，按 0.1 递增）
rwaMakerFee	RWA Maker 费率，单位为 bps（-0.5 至 15）
rwaTakerFee	RWA Taker 费率，单位为 bps（1 至 15）
paymentType	usdc——请显式传入（默认值为 order）

API 会验证：交易是否存在、发送方是否与经过身份验证的用户匹配、接收方是否正确、金额是否达到费用要求、交易是否已被使用，以及 brokerId 是否已被占用。经纪商 ID 会在此处创建——但只有完成步骤 4，毕业流程才算结束。 步骤 4 — 注册管理员钱包（完成毕业流程的必需步骤）：

EVM 钱包（Agent）：

1. GET https://api.orderly.org/v1/registration_nonce?address={yourAddress}
2. 对 EIP-712 类型化数据 { brokerId, chainId, timestamp, registrationNonce } 签名（使用你完成毕业流程时的相同 brokerId 和地址）
3. 使用 { message, signature, userAddress } 执行 POST https://api.orderly.org/v1/register_account → account_id
4. 使用 空 JSON 请求体 {} + Bearer 执行 POST /api/graduation/finalize-admin-wallet — 将你自己的钱包绑定为管理员（Agent 不填写多签字段）

Solana 钱包：

1. 流程相同，但 chainId: 900900900，使用 Solana 钱包签名，chainType: "SOL"

EVM 多签/Gnosis Safe：

1. Safe Wallet → Transaction Builder → 批量调用 Vault 合约上的 delegateSigner，参数为 [keccak256(brokerId), userAddress]
2. 通过签名者批准后执行
3. 使用 { multisigAddress, multisigChainId } 执行 POST /api/graduation/finalize-admin-wallet

注意： 步骤 4 的注册使用 Orderly Network API（api.orderly.org）进行身份验证，而非 Orderly One — 两者使用不同的身份验证系统（EIP-712/Ed25519）。finalize-admin-wallet 本身使用你的 Orderly One Bearer 令牌。调用 GET /api/graduation/graduation-status 进行确认，直到 isGraduated: true。

毕业状态与费用：

端点	说明
GET /api/graduation/status	基本状态：{ currentBrokerId, approved }
GET /api/graduation/graduation-status	详细信息：{ isGraduated, brokerId, isMultisig, multisigAddress }
GET /api/graduation/fees	当前 maker/taker/RWA 费率
GET /api/graduation/tier	Builder Staking Programme 等级
POST /api/graduation/refund	取回已结算但未使用的 x402 付款：{txHash, chain}

---

Orderly MCP

此技能引用了 Orderly MCP 服务。如尚未安装，请参阅 orderly-onboarding 技能了解设置方法。

工具： get_orderly_one_api_info

• { endpoint: "/api/dex" } - 特定端点的详细信息
• { category: "graduation" } - 某个类别中的所有端点
• {} - 完整的 API 概览

---

常见问题

问题	解决方案
DEX 部署卡住	检查 /api/dex/{id}/workflow-runs/{runId}，确认作业是否失败
域名无法使用	将 CNAME 指向 {org}.github.io，等待 DNS 传播
毕业验证失败	从 PAYMENT-RESPONSE 确认结算交易哈希和链，并等待确认
“Broker ID 已被占用”	在 verify-tx 中选择其他 brokerId
“交易哈希已使用”	每笔交易只能使用一次（防重放）。请发送新的付款
x402 已付款，但经纪商未注册	分两步操作：使用结算交易哈希执行 POST /api/graduation/verify-tx（paymentType: "usdc"）；如果失败，则执行 POST /api/graduation/refund
x402 付款因金额过小被拒绝	提高 x402 客户端的 spendControls.maxAmountPerPayment（默认值为 $1），以支付手续费
“必须注册 EVM 地址”	调用 finalize-admin-wallet 前，先完成管理员钱包注册（步骤 4）
“已毕业”	每位用户只能毕业一次
Logo 上传失败	检查文件大小限制（主 Logo 为 250KB，副 Logo 为 100KB）
CSS 无效	提交前验证 themeCSS 语法

---

相关技能

• orderly-onboarding - 账户设置和构建者入门
• orderly-trading-orders - 交易功能