Sparky 开发者文档
欢迎使用 Sparky 开发者文档。Sparky 是运行在 EVM 链上的永续合约 DEX：撮合在链下的 Rust 引擎中完成，保证金托管在链上 Vault 合约，所有成交通过 TradeRecorder 合约做链上存证。本站覆盖平台核心概念与完整 API 参考。
内容地图
核心概念
API 参考
- 永续合约 — Binance USDT-M 兼容的
/fapi/v1/*+/fapi/v2/*REST、WebSocket 推送与 Sparky 扩展接口 - 推荐返佣 — 推荐码、阶梯返佣、链下 / 链上领取
支持的链
Sparky 每条链一套独立后端部署。每套部署有自己的 Base URL、数据库和 Vault，因此账户余额、持仓与 API Key 都是按链隔离的：在 Avalanche 创建的 Key 不能用于 Arbitrum。
| 网络 | Chain ID | 原生 Gas | 结算资产 | 状态 |
|---|---|---|---|---|
| Avalanche C-Chain | 43114 | AVAX | USDT（6 位精度） | 主网 |
| Arbitrum One | 42161 | ETH | USDT（6 位精度） | 主网 |
| BNB Chain | 56 | BNB | USDT | 主网 |
| Avalanche Fuji | 43113 | AVAX（测试） | 测试 USDT | 测试网 |
| Arbitrum Sepolia | 421614 | ETH（测试） | 测试 USDT | 测试网 |
各部署的 API Base URL 见 基本信息 › Base URL。
链上合约
合约地址通过环境变量注入到各链的后端部署（VAULT_ADDRESS、TRADE_RECORDER_*、REFERRAL_*），每条链不同，本文档不硬编码任何地址。请从接口读取实时地址：
| 合约 | 作用 | 获取地址 |
|---|---|---|
| Vault | 托管用户保证金。用户调用 deposit(amount, referralCode)；提现需要后端 EIP-712 签名（withdraw(user, amount, nonce, expiry, signature)）。后端监听 Deposit / Withdraw 事件入账与解冻。 | POST /api/v1/deposit/prepare → contract_address；POST /api/v1/withdraw/request → vault_address |
| TradeRecorder | 所有成交的链上只增记录。后端把成交批量写入 onchain_trade_records outbox，由 recorder worker 提交合约，形成可审计的链上成交账本。 | 目前无接口暴露；来自部署配置 TRADE_RECORDER_* |
| ReferralStorage / ReferralRebate | 链上推荐码注册表（推荐码、关系、等级）与返佣账本。后端每小时同步返佣（batchSyncRebates）；用户持后端签名调用 claimRebate(amount, deadline, signature) 领取。 | GET /api/v1/referral/on-chain/operator-status → contract_address |
双引擎架构
Sparky 后端在同一 API 域名下承载两套交易引擎：
| 引擎 A — Orderly 网关 | 引擎 B — Sparky 自研引擎 | |
|---|---|---|
| 交易对 | Orderly Network 已上架的主流深度品种 | Orderly 未上架的长尾、RWA、自定义品种 |
| 撮合 | Orderly 链下撮合 | Sparky 无锁内存订单簿 |
| 结算 | Orderly Vault | 本链上的 Sparky Vault |
| 客户端路径 | ANY /api/v1/dex/* 透传代理（客户端自签的 Orderly 鉴权头改名后按字节转发；严格路径白名单；资金移动类接口永不代理） | /api/v1/* 原生 JSON API 与 Binance 兼容的 /fapi/* |
| 链上存证 | POST /api/v1/orderly/record-fill → TradeRecorder | onchain_trade_records outbox → TradeRecorder |
两套引擎共用同一钱包身份（用户 EOA 地址）。交易对归属以市场元数据的 engine 字段为准，客户端不得按 symbol 格式猜测。本文档只覆盖引擎 B：/fapi/* 与 /api/v1/*（/api/v1/dex/* 除外）全部指向 Sparky 自研引擎。
状态
🚧 持续建设中。 Base URL 在域名分配前为占位符；各端点页面已对照后端路由表核对，Binance 定义但 Sparky 未提供的端点标记为 空缺（暂未实现）。