# Binance Web3 API 文档 > Complete documentation for Large Language Models --- ## Document: 概览 URL: /zh-CN/dev-docs/introduction # 概览 Binance Web3 API 是一套面向开发者的链上数据与交易服务平台，提供统一的 RESTful API 接口，覆盖行情、交易聚合、链上交易模拟与广播等核心能力。 ## 平台架构 ``` Client │ ▼ Gateway ← 认证 / 签名验签 / 限流 │ ├──→ 行情 API ← 实时行情、K 线、代币分析 ├──→ 兑换 API ← 跨 DEX 聚合报价与兑换 ├──→ 链上交易 API ← 链上交易模拟与广播 └──→ 钱包 API ← 钱包余额查询 ``` ## API 模块总览 | 模块 | 说明 | | ------------------------------------------------------ | ------------------------ | | [行情 API](/products/market-api/introduction) | 实时价格、K 线、代币分析 | | [兑换 API](/products/trading-api/introduction) | 跨 DEX 聚合报价与兑换 | | [链上交易 API](/products/transaction-api/introduction) | 链上交易模拟与广播 | | [钱包 API](/products/wallet-api/introduction) | 多链钱包余额查询 | ## 统一响应格式 所有接口均返回 `OCResult` 格式： ```json { "code": 0, "msg": "success", "data": {}, "timestamp": 1713500000000, "success": true } ``` - `code = 0` 表示成功，非零为错误码 - `data` 为业务数据，类型因接口而异 - `timestamp` 为服务器时间戳（毫秒） - `success` 为便捷布尔值，由 `code == 0` 派生 --- ## Document: 鉴权 URL: /zh-CN/dev-docs/authentication # 鉴权 import { Callout } from "zudoku/ui/Callout.js"; Binance Web3 API 所有 API 接口均受 **API Key 鉴权**保护。每个请求都必须使用您的 Secret Key 进行签名，确保只有持有有效凭证的授权客户端才能访问平台。 --- ## 第一步 — 获取 API 凭证 前往[**开发者平台**](https://web3.binance.com/zh-CN/dev-portal/project)创建项目，生成 **API Key** 和 **Secret Key**： | 凭证 | 说明 | | ------------ | ------------------------------------------------------ | | `API Key` | 唯一标识您的应用（请求头 `X-OC-APIKEY`） | | `Secret Key` | 用于签名请求（HMAC-SHA256 模式），请妥善保管，切勿泄露 | --- ## 第二步 — 了解必填请求头 每个认证请求都必须携带以下三个请求头： | 请求头 | 必填 | 说明 | | ------------------ | ---- | ------------------------------------------------------------------------- | | `X-OC-APIKEY` | 是 | 您的 API Key 字符串 | | `X-OC-TIMESTAMP` | 是 | 当前 UTC 时间，**ISO 8601** 格式（含毫秒），如 `2026-05-11T10:08:57.715Z` | | `X-OC-SIGN` | 是 | 请求签名（Base64 编码），详见[第三步](#第三步--生成签名) | | `X-OC-RECV-WINDOW` | 否 | 允许的时间偏差（毫秒），默认 `5000`，最大 `60000` | | `X-OC-NONCE` | 否 | 唯一请求标识符，用于防重放；若未填写则使用 `X-OC-SIGN` 值代替 | --- ## Base URL 与必填的 `/build` 前缀 所有接口均由同一域名提供服务，并固定使用 **`/build` 基础路径**： ``` Base URL = https://web3.binance.com/build ``` 这意味着 HTTP 线上传输的每个请求行都以 `/build/api/v1/...` 开头，并且**参与签名的 `requestPath`（见第三步）也必须包含 `/build` 前缀** —— 与线上传输的路径完全一致。 **关键提示 —— `40102 Invalid signature` 的首要原因：** 漏掉 `/build` 前缀。即使请求本身 能被正确路由，签名串里写成裸 `/api/v1/...` 也会导致签名校验失败。构造待签名字符串时，务必 在路径前显式带上 `/build`。 | 项目 | 取值 / 规则 | | ------------------------ | ------------------------------------------------- | | Base URL | `https://web3.binance.com/build` | | 完整请求 URL | `https://web3.binance.com/build` + `/api/v1/...` | | 参与签名的 `requestPath` | `/build/api/v1/...`（如有 query 再追加 `?query`） | | `Host` 请求头 | `web3.binance.com`（不带路径） | 裸 `https://web3.binance.com/api/v1/...`（不带 `/build`）会在边缘层被重定向到 `/build` 前缀 —— 但**不要依赖重定向来生成签名**。请始终在请求 URL 和签名的 `requestPath` 中显式带上 `/build`。 --- ## 第三步 — 生成签名 ### 3.1 构造待签名字符串（preHash） 将以下四个部分**直接拼接**（无分隔符）： ``` preHash = timestamp + method + requestPath + body ``` | 组成部分 | 规则 | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timestamp` | `X-OC-TIMESTAMP` 请求头的值（ISO 8601，如 `2026-05-11T10:08:57.715Z`） | | `method` | HTTP 方法**大写**（如 `GET`、`POST`） | | `requestPath` | 完整 HTTP 路径，**含 `/build` 基础路径前缀**，加上查询字符串，以 **原始 URL 编码形式**表示，如 `/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT`。详见 [Base URL](#base-url-与必填的-build-前缀)。 | | `body` | `POST`/`PUT`/`DELETE` 请求的原始请求体字符串；`GET`/`HEAD` 请求使用**空字符串 `""`** | **重要：** `requestPath` 必须使用 HTTP 线上传输的原始编码形式 —— 不做 URL 解码、不对查询参数排序、不合并参数。它**必须**以 `/build` 前缀开头；漏掉前缀是 `40102 Invalid signature` 最常见的原因。 #### 示例（GET 请求） ``` timestamp = "2026-05-11T10:08:57.715Z" method = "GET" requestPath = "/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT" body = "" preHash = "2026-05-11T10:08:57.715ZGET/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT" ``` #### 示例（POST 请求） ``` timestamp = "2026-05-11T10:08:57.715Z" method = "POST" requestPath = "/build/api/v1/dex/swap" body = '{"chainId":1,"fromToken":"0xEEEE...","toToken":"0xA0b8...","amount":"1000000000000000000"}' preHash = "2026-05-11T10:08:57.715ZPOST/build/api/v1/dex/swap{\"chainId\":1,...}" ``` --- ### 3.2 使用 HMAC-SHA256 签名（默认） 以 `Secret Key` 对 `preHash` 计算 **HMAC-SHA256**，再对结果进行 **Base64 编码**： ``` signature = Base64( HMAC-SHA256(preHash, secretKey) ) ``` 所有字符串均以 **UTF-8** 编码后参与运算。 #### JavaScript / Node.js ```js javascript const crypto = require("crypto"); const timestamp = new Date().toISOString(); // 如 "2026-05-11T10:08:57.715Z" const method = "GET"; // 注意：路径必须包含 /build 基础路径前缀 —— 它是参与签名的 requestPath 的一部分。 const pathWithQuery = "/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT"; const body = ""; // GET 请求为空字符串 const preHash = timestamp + method + pathWithQuery + body; const signature = crypto .createHmac("sha256", secretKey) .update(preHash, "utf8") .digest("base64"); ``` #### Python ```python python import hmac, hashlib, base64 from datetime import datetime, timezone now = datetime.now(timezone.utc) timestamp = now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z" method = "GET" # 注意：路径必须包含 /build 基础路径前缀 —— 它是参与签名的 requestPath 的一部分。 path_query = "/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT" body = "" pre_hash = timestamp + method + path_query + body signature = base64.b64encode( hmac.new(secret_key.encode("utf-8"), pre_hash.encode("utf-8"), hashlib.sha256).digest() ).decode("utf-8") ``` #### Java ```java java import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.util.Base64; // pathWithQuery 必须包含 /build 基础路径前缀 —— 它是参与签名的 requestPath 的一部分。 String pathWithQuery = "/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT"; String preHash = timestamp + method + pathWithQuery + body; Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256")); String signature = Base64.getEncoder().encodeToString( mac.doFinal(preHash.getBytes("UTF-8")) ); ``` --- ### 3.3 使用 Ed25519 签名（高级） 若您的 API Key 配置为 **Ed25519** 签名模式，请使用 **Ed25519 私钥**对 `preHash` 签名并 Base64 编码： ``` signature = Base64( Ed25519Sign(preHash, privateKey) ) ``` 创建 API Key 时需在开发者平台上传 **Ed25519 公钥**（Base64 编码，X.509 DER 格式）。 #### Java ```java java import java.security.*; import java.util.Base64; Signature signer = Signature.getInstance("Ed25519"); signer.initSign(ed25519PrivateKey); signer.update(preHash.getBytes("UTF-8")); String signature = Base64.getEncoder().encodeToString(signer.sign()); ``` --- ## 第四步 — 发送请求 在每个认证请求中附加三个必填请求头： ```http GET /build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT HTTP/1.1 Host: web3.binance.com X-OC-APIKEY: your-api-key-here X-OC-TIMESTAMP: 2026-05-11T10:08:57.715Z X-OC-SIGN: k3Y2mNpQr...base64sig...== ``` #### 完整 JavaScript 示例 ```js javascript const crypto = require("crypto"); const axios = require("axios"); const API_KEY = process.env.OC_API_KEY; const SECRET_KEY = process.env.OC_SECRET_KEY; // BASE_URL 已包含 /build 基础路径前缀。 // 传入的 path 用 /api/v1/... 形式，由下面的函数统一在 URL 和签名中补上 /build 前缀。 const BASE_URL = "https://web3.binance.com/build"; const BUILD_PREFIX = "/build"; async function get(path, params = {}) { // 使用 encodeURIComponent 编码，空格转为 %20（而非 URLSearchParams 的 +），与 HTTP 线上传输一致 const queryStr = Object.entries(params) .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`) .join("&"); const fullPath = queryStr ? `${path}?${queryStr}` : path; const timestamp = new Date().toISOString(); // requestPath 即 HTTP 线上传输的完整路径 —— 必须包含 /build 前缀。 const requestPath = BUILD_PREFIX + fullPath; const body = ""; // GET 请求 body 为空字符串 const preHash = timestamp + "GET" + requestPath + body; const signature = crypto .createHmac("sha256", SECRET_KEY) .update(preHash, "utf8") .digest("base64"); const resp = await axios.get(BASE_URL + fullPath, { headers: { "X-OC-APIKEY": API_KEY, "X-OC-TIMESTAMP": timestamp, "X-OC-SIGN": signature, }, }); return resp.data; } // 使用示例 —— path 不带 /build，由函数统一在 URL 和签名中补上。 get("/api/v1/dex/aggregator/supported/chain", { binanceChainId: "56" }).then( console.log, ); ``` 无论您选择哪种风格 —— 显式传入 `/build/...` 路径，或由辅助函数统一补 `/build` —— 核心要求都是： **签名的 `requestPath`** 与 **请求 URL** 必须同时携带 `/build` 前缀。两者不一致（例如签名不带 `/build` 但请求带了）会产生 `40102 Invalid signature`。 --- ## 时间戳与防重放 网关对每个认证请求都会校验 `X-OC-TIMESTAMP`： 1. **格式**：必须是合法的 ISO 8601 字符串（如 `2026-05-11T10:08:57.715Z`）。 2. **时间窗口**：请求时间戳与服务器时间的误差不得超过 `recv_window` 毫秒。默认 **5 000 ms（5 秒）**，可通过 `X-OC-RECV-WINDOW` 配置（最大 **60 000 ms / 60 秒**）。 3. **防重放**：每个 nonce（`X-OC-NONCE` 或签名本身）在 `2 × recv_window` 时间窗口内仅可使用一次。重放请求将被拒绝，返回错误码 `40103`。 请确保您的服务器时钟与 NTP 同步，避免因时钟偏差导致时间戳校验失败。 --- ## 频率限制 认证请求同时受四个维度的频率限制约束： | 维度 | 默认上限 | 时间窗口 | 响应头 | | ---------- | ------------- | -------- | -------------------------- | | 单 IP | 1 200 次请求 | 60 秒 | `X-OC-RateLimit-Limit` | | 单 API Key | 1 200 次请求 | 60 秒 | `X-OC-RateLimit-Remaining` | | 单用户 | 6 000 次请求 | 60 秒 | `X-OC-Used-Weight` | | 单接口 | 5 RPS（默认） | 1 秒 | `X-OC-Used-Weight` | 超过限制时，网关返回 **HTTP 429**，并在响应头中携带 `Retry-After`（单位：秒）。 --- ## 错误码 | HTTP 状态码 | 错误码 | 说明 | | ----------- | ------- | --------------------------------- | | 400 | `40001` | 请求参数无效 | | 401 | `40101` | API Key 缺失、无效或已被禁用/冻结 | | 401 | `40102` | 签名不匹配或缺失 | | 401 | `40103` | 时间戳已过期或请求被重放 | | 403 | `40104` | API Key 权限不足 | | 429 | `42900` | 请求频率超限 | | 500 | `50000` | 服务器内部错误 | | 503 | `50001` | 服务暂时不可用 | 所有错误响应均遵循统一格式： ```json { "code": 40102, "msg": "Invalid signature", "data": null, "timestamp": 1715420937000 } ``` --- ## Postman 快速接入 在 Postman 集合的 **Pre-request Script** 中添加以下脚本，即可为所有请求自动签名。在集合中把 Base URL 设为 `https://web3.binance.com/build`，每个请求的 path 配置为 `/api/v1/...` —— 下方脚本会在构造签名时为路径补上 `/build` 前缀，使签名的 `requestPath` 与线上传输的路径一致。 ```js javascript // Binance Web3 API Gateway — 自动签名脚本 const apiKey = pm.variables.get("api_key"); const secretKey = pm.variables.get("secret_key"); if (!apiKey || !secretKey) { throw new Error("请先在 Collection Variables 中设置 api_key 和 secret_key"); } const timestamp = new Date().toISOString(); const method = pm.request.method.toUpperCase(); const url = pm.request.url; const pathStr = "/" + (url.path || []).join("/"); const qParams = (url.query || []).filter((p) => !p.disabled && p.key); const queryStr = qParams .map( (p) => encodeURIComponent(p.key) + "=" + encodeURIComponent(p.value || ""), ) .join("&"); const pathWithQuery = queryStr ? pathStr + "?" + queryStr : pathStr; // 参与签名的 requestPath 必须包含 /build 基础路径前缀。 // Postman 请求 path 配置为 /api/v1/...（不带 /build），这里统一补上。 const signedRequestPath = pathWithQuery.startsWith("/build") ? pathWithQuery : "/build" + pathWithQuery; const body = method === "GET" || method === "HEAD" ? "" : pm.request.body ? pm.request.body.toString() : ""; const preHash = timestamp + method + signedRequestPath + body; const signature = CryptoJS.enc.Base64.stringify( CryptoJS.HmacSHA256(preHash, secretKey), ); pm.request.headers.upsert({ key: "X-OC-APIKEY", value: apiKey }); pm.request.headers.upsert({ key: "X-OC-TIMESTAMP", value: timestamp }); pm.request.headers.upsert({ key: "X-OC-SIGN", value: signature }); ``` 在**集合 → Variables** 中设置 `api_key` 和 `secret_key` 后，每个请求将自动完成签名。 --- ## Document: SDK 与工具 URL: /zh-CN/dev-docs/sdks-tools/overview # SDK 与工具 官方连接器，帮助您高效集成 Binance API。 import { Link, Typography, LanguageIcon } from "zudoku/components"; import { Card, CardHeader, CardTitle, CardDescription, CardFooter, } from "zudoku/ui/Card"; import { ChevronRight, Github } from "lucide-react"; export const IconTile = ({ children, label }) => ( {children} ); export const REGISTRY_ICONS = { npm: "https://cdn.simpleicons.org/npm", PyPI: "https://cdn.simpleicons.org/pypi", Maven: "https://cdn.simpleicons.org/apachemaven", }; export const CardLink = ({ to, title, description, children, github, registry, }) => (
{children}
{title} {description ? ( {description} ) : null} {(github || registry) && ( {github && ( Git )} {registry && ( {registry.label} )} )}
); --- ## 官方 API 连接器
由 Binance 官方维护的生产级客户端库，覆盖主流编程语言。 每个连接器均包含请求签名工具、类型化模型以及可运行示例。
--- ## Document: Agent 原生 URL: /zh-CN/dev-docs/agent-native/overview # Agent 原生 import { Link } from "zudoku/components"; import { Card, CardHeader, CardTitle, CardDescription } from "zudoku/ui/Card"; import { Bot, FileText, Plug, ChevronRight, Terminal, Lightbulb, Users, } from "lucide-react"; export const IconTile = ({ children, label }) => ( {children} ); export const Badge = ({ children }) => ( {children} ); export const CardLink = ({ to, title, description, children, badge, cta = "了解更多", disabled = false, }) => (
{!disabled && ( )}
{children} {badge && {badge}}
{title} {description} {cta && ( {cta} {!disabled && } )}
); export const ScenarioCard = ({ icon: Icon, title, description }) => (

{title}

{description}

);

Agent 原生

两种互补的接口，专为 AI 工具、编程助手和自主 Agent 设计。让 AI 系统能够以编程方式发现、阅读并与 Binance Web3 API 文档交互。

## 核心组件
选择适合您使用场景的集成方式。每个组件服务于不同目的 — 可以单独使用，也可以组合使用。
--- ## 快速开始 ### 通过 llms.txt 获取文档 ```bash # 摘要 — 文档标题、描述和链接 curl -s https://web3.binance.com/zh-CN/dev-docs/llms.txt # 完整内容 — 单个文件中的完整文档 curl -s https://web3.binance.com/zh-CN/dev-docs/llms-full.txt ``` MCP Server 的快速开始指南将在接口上线后发布。 --- ## 适用场景
无论您是使用 AI IDE 开发，还是将文档集成到 Agent 流水线中，都有适合您工作流的工具。
--- ## 工作原理
AI 工具 / Agent
llms.txt → 快速发现："有哪些文档？"
MCP Server → 原生集成："搜索文档、生成代码、测试 API"
--- ## Document: MCP Server URL: /zh-CN/dev-docs/agent-native/mcp-server # MCP Server import { Link } from "zudoku/components"; import { Plug, Hourglass, Terminal } from "lucide-react";

即将推出

MCP Server

通过 Model Context Protocol 为 AI IDE 提供原生集成。在编辑器内直接搜索 Binance Web3 API 文档、生成代码、测试 API 调用 —— 全程无需离开对话。

## 即将提供的能力

编辑器原生工具

把服务器 URL 配置到 Claude Code、Cursor 或 Windsurf，把文档 / 代码生成功能当作 MCP 工具直接调用。

SSE 传输

基于 Server-Sent Events 的低延迟传输，与 llms.txt 共享同一套 Agent 生态。

## 期间替代方案 MCP Server 上线之前，静态的 **llms.txt** 文件已经能覆盖大多数 LLM 工作流里"发现 + 全量内容"的场景。 --- ## Document: /agent-native/llms-txt URL: /zh-CN/dev-docs/agent-native/llms-txt # llms.txt [llms.txt](https://llmstxt.org/) 是一项拟议标准，旨在使网站内容对大语言模型更易于访问。与用于网络爬虫的 `robots.txt` 类似，`llms.txt` 告知 AI 工具有哪些文档可用以及如何访问这些文档。 ## 文件 Binance Web3 API 提供两个 llms.txt 文件： | 文件 | URL | 描述 | | --------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `llms.txt` | /zh-CN/dev-docs/llms.txt | 摘要 — 文档标题、描述和链接（始终为英文，全站统一） | | `llms-full.txt` | /zh-CN/dev-docs/llms-full.txt | 完整内容 — 所有文档汇集在一个文件中（始终为英文） | ## 格式 ### llms.txt（摘要） 摘要文件包含所有文档页面的结构化列表，包括标题、描述和 URL。**注意：内容始终为英文**——`/llms.txt` 是面向 LLM 的统一资源，全站只有一份英文版本，无中文 locale 副本。 ``` # Binance Web3 API > On-chain data & trading services for developers. ## Market API - [Introduction](/market-api/introduction): Market API overview - [Get Price](/market-api/api-reference/get-price): Real-time token price ## Trading API - [Introduction](/trading-api/introduction): DEX aggregator overview - [Swap](/trading-api/api-reference/swap): Execute token swap - [Quote](/trading-api/api-reference/quote): Get swap quote - [Approve Transaction](/trading-api/api-reference/approve-transaction): Token approval ## Transaction API - [Introduction](/transaction-api/introduction): Transaction broadcasting - [Broadcast](/transaction-api/api-reference/broadcast-transactions): Submit signed tx ``` ### llms-full.txt（完整内容） 完整文件包含每个文档页面的完整 Markdown 内容，以标题分隔。这对于将整个文档加载到大语言模型的上下文窗口中非常有用。 ## 使用示例 ### 输入到任意大语言模型 ```bash # 下载并用作上下文 curl -s https://web3.binance.com/zh-CN/dev-docs/llms.txt # 完整文档，用于全面的上下文 curl -s https://web3.binance.com/zh-CN/dev-docs/llms-full.txt ``` ### 与 Claude 配合使用 ``` 请阅读 https://web3.binance.com/zh-CN/dev-docs/llms.txt，并帮助我了解 如何使用 Binance Web3 Trading API 执行代币兑换。 ``` ### 在 Python 脚本中使用 ```python import requests # 获取文档索引 response = requests.get("https://web3.binance.com/zh-CN/dev-docs/llms.txt") docs_index = response.text # 将其作为上下文输入到大语言模型 messages = [ {"role": "system", "content": f"Binance Web3 API 文档:\n{docs_index}"}, {"role": "user", "content": "如何获取兑换报价？"} ] ``` ### 与 LangChain 配合使用 ```python from langchain_community.document_loaders import WebBaseLoader loader = WebBaseLoader("https://web3.binance.com/zh-CN/dev-docs/llms-full.txt") docs = loader.load() ``` ## 何时使用 llms.txt - **llms.txt** — 您希望快速让大语言模型了解所有可用文档 - **llms-full.txt** — 您希望将完整文档加载到大语言模型的上下文窗口中 --- ## Document: Python URL: /zh-CN/dev-docs/sdks-tools/connectors/python # Python Binance Web3 Wallet API 官方 Python 连接器，专为运行在 Python 上的后端应用程序而设计。 该连接器以 `binance-web3-wallet` PyPI 包形式发布，支持 Web3 Wallet REST API，并提供内置的请求签名以及强类型的请求/响应模型。 如需查看源代码、问题反馈及版本说明，请访问 GitHub 上的 [binance-web3-connector-python](https://github.com/binance/binance-web3-connector-python) 仓库。 ## 支持的环境 - Python 3.9 或更高版本 - 后端 Python 应用程序及服务 > 本连接器仅适用于服务端使用。不支持交互式或客户端 Python 环境。 ## 典型使用场景 - 查询余额、交易记录及支持链的后端服务 - 构建并提交兑换与转账交易 - 将 Web3 Wallet 行情与价格数据集成到后端系统 ## 主要特性 - 支持 Binance Web3 Wallet REST API - 内置针对需要身份验证接口的请求签名 - 强类型的请求与响应模型 - 一致的 API 设计 ## 快速开始 安装该包： ```bash pip install binance-web3-wallet ``` 创建客户端并发送请求： ```python from binance_sdk_web3_wallet.web3_wallet import Web3Wallet, ConfigurationRestAPI configuration_rest_api = ConfigurationRestAPI( api_key=os.environ["BINANCE_API_KEY"], api_secret=os.environ["BINANCE_API_SECRET"], ) client = Web3Wallet(config_rest_api=configuration_rest_api) response = client.rest_api.get_supported_chains() ``` 上述示例使用基于 API Secret 的 HMAC 身份验证。同样支持使用私钥的非对称密钥身份验证方式。 如需 REST API 示例，请参阅该包的文档。 ## 注意事项与最佳实践 - 使用环境变量或密钥管理工具安全存储 API 密钥 - 构建高吞吐量服务时，注意监控频率限制和接口权重 --- ## Document: JavaScript URL: /zh-CN/dev-docs/sdks-tools/connectors/javascript # JavaScript Binance Web3 Wallet API 官方 JavaScript 连接器，专为运行在 Node.js 上的后端应用程序而设计。 该连接器以 `@binance-web3/wallet` npm 包形式发布，支持 Web3 Wallet REST API，并提供内置的请求签名、连接管理以及 TypeScript 类型定义。 如需查看源代码、问题反馈及版本说明，请访问 GitHub 上的 [binance-web3-connector-js](https://github.com/binance/binance-web3-connector-js) 仓库。 ## 支持的环境 - Node.js v22.12.0 或更高版本（推荐使用 LTS 版本） - JavaScript 和 TypeScript 后端应用程序 > 本连接器仅适用于服务端使用。 > 目前不支持浏览器环境。 ## 典型使用场景 - 查询余额、交易记录及支持链的后端服务 - 构建并提交兑换与转账交易 - 将 Web3 Wallet 行情与价格数据集成到后端系统 ## 主要特性 - 支持 Binance Web3 Wallet REST API - 内置针对需要身份验证接口的请求签名 - 完整的 TypeScript 类型定义 - 可配置的超时、重试与代理支持 - 一致的 API 设计 ## 快速开始 安装该包： ```bash npm install @binance-web3/wallet ``` 创建客户端并发送请求： ```ts import { Web3Wallet, Web3WalletRestAPI } from "@binance-web3/wallet"; const configurationRestAPI = { apiKey: process.env.BINANCE_API_KEY, apiSecret: process.env.BINANCE_API_SECRET, }; const client = new Web3Wallet({ configurationRestAPI }); const response = await client.restAPI.getSupportedChains(); const data = await response.data(); ``` 上述示例使用基于 API Secret 的 HMAC 身份验证。同样支持使用私钥的非对称密钥身份验证方式。 如需 REST API 示例，请参阅该包的文档。 ## 注意事项与最佳实践 - 使用环境变量或密钥管理工具安全存储 API 密钥 - 构建高吞吐量服务时，注意监控频率限制和接口权重 --- ## Document: Java URL: /zh-CN/dev-docs/sdks-tools/connectors/java # Java Binance Web3 Wallet API 官方 Java 连接器，专为运行在 JVM 上的后端应用程序和服务而设计。 该连接器为 Web3 Wallet REST API 提供符合 Java 惯例的接口，内置请求签名以及强类型的请求与响应模型，助您构建可靠且易于维护的集成方案。 如需查看源代码、问题反馈及版本说明，请访问 GitHub 上的 [binance-web3-connector-java](https://github.com/binance/binance-web3-connector-java) 仓库。 ## 支持的环境 - Java 11 或更高版本 - 后端 Java 应用程序及基于 JVM 的服务 > 本连接器仅适用于服务端使用。 ## 典型使用场景 - 查询余额、交易记录及支持链的后端服务 - 构建并提交兑换与转账交易 - 将 Web3 Wallet 行情与价格数据集成到后端系统 ## 主要特性 - 支持 Binance Web3 Wallet REST API - 内置针对需要身份验证接口的请求签名 - 强类型的请求与响应模型 - 一致且符合 Java 惯例的 API 设计 ## 快速开始 添加 Web3 Wallet 连接器依赖项： ```xml io.github.binance binance-web3-wallet ``` 创建客户端并发送请求： ```java import com.binance.connector.client.common.configuration.ClientConfiguration; import com.binance.connector.client.common.configuration.SignatureConfiguration; import com.binance.connector.client.web3_wallet.rest.Web3WalletRestApiUtil; import com.binance.connector.client.web3_wallet.rest.api.Web3WalletRestApi; public class Main { public static void main(String[] args) throws Exception { SignatureConfiguration signatureConfiguration = new SignatureConfiguration(); signatureConfiguration.setApiKey(System.getenv("BINANCE_API_KEY")); signatureConfiguration.setSecretKey(System.getenv("BINANCE_API_SECRET")); ClientConfiguration clientConfiguration = Web3WalletRestApiUtil.getClientConfiguration(); clientConfiguration.setSignatureConfiguration(signatureConfiguration); Web3WalletRestApi web3WalletApi = new Web3WalletRestApi(clientConfiguration); web3WalletApi.getSupportedChains(); } } ``` 上述示例使用基于 API Secret 的 HMAC 身份验证。同样支持使用私钥的非对称密钥身份验证方式。 如需 REST API 示例，请参阅该包的文档。 ## 注意事项与最佳实践 - 使用环境变量或密钥管理工具安全存储 API 密钥 - 构建高吞吐量服务时，注意监控频率限制和接口权重 --- ## Document: 支持的 Skills URL: /zh-CN/dev-docs/products/wallet-skills/supported-skills # 支持的 Skills Binance Wallet Skills 已在 [binance-skills-hub](https://github.com/binance/binance-skills-hub/tree/main/skills/binance-web3) 发布，包括 7 个只读 **Wallet Skills** 和用于链上交易的 **Agentic Wallet Skill**。 ## 总览 ### 已发布 Wallet Skills | Skill | 类别 | 状态 | 需要钱包连接 | | ------------------------------------- | ---- | ------- | ------------ | | **query-token-info** | Read | ✅ Live | 否 | | **query-token-audit** | Read | ✅ Live | 否 | | **query-address-info** | Read | ✅ Live | 否 | | **crypto-market-rank** | Read | ✅ Live | 否 | | **meme-rush** | Read | ✅ Live | 否 | | **trading-signal** | Read | ✅ Live | 否 | | **binance-tokenized-securities-info** | Read | ✅ Live | 否 | ### Agentic Wallet Skills | Skill | 类别 | 状态 | 需要钱包连接 | | -------------------------- | ------------ | ------- | ------------ | | **binance-agentic-wallet** | Read + Write | ✅ Live | 是（写操作） | --- ## 已发布 Wallet Skills ### query-token-info 代币全面信息查询，从发现到深度分析一站解决。 **支持操作** | 操作 | 说明 | | ---------- | ----------------------------------------------------- | | 代币搜索 | 按名称、Symbol 或合约地址搜索，返回价格、市值、流动性 | | 元数据查询 | 描述、创建者、审计状态、社交链接等静态信息 | | 实时行情 | 多时间维度价格变化（5m/1h/4h/24h）、买卖量、持币分析 | | K 线数据 | OHLCV K 线，支持 1s 到 1 月多种时间粒度 | **支持链：** BSC、Base、Solana ``` BNB 现在多少钱？ 查一下这个代币的持币分布 给我 SOL 过去 4 小时的 K 线数据 ``` --- ### query-token-audit 交易前安全审计，帮助识别风险合约和恶意代币。 **支持操作** | 操作 | 说明 | | -------- | ------------------------------------------- | | 风险评分 | 输出 LOW / MEDIUM / HIGH 风险等级（1–5 分） | | 蜜罐检测 | 识别能买不能卖的欺诈合约 | | 税率分析 | 返回买入/卖出税率，超过 10% 标记为高危 | | 合约验证 | 检查源码是否已公开验证 | **支持链：** Ethereum、BSC、Base、Solana > ⚠️ 审计结果仅供参考，LOW 风险不等于安全背书，请自行做好研究。 ``` 帮我审计一下这个合约地址是否安全 这个代币有没有蜜罐风险？ ``` --- ### query-address-info 查询指定钱包地址在链上持有的全部代币及估值。 **支持操作** | 操作 | 说明 | | -------- | ------------------------------------ | | 持仓查询 | 返回地址所有代币余额、数量、合约地址 | | 价格数据 | 每个代币当前 USD 价格及 24h 涨跌幅 | | 分页支持 | 通过 offset 参数翻页查看大量持仓 | **支持链：** BSC、Base、Solana ``` 查一下这个地址持有哪些代币 0xABC... 在 BSC 上有什么仓位？ ``` --- ### crypto-market-rank 多维度加密货币市场排行榜，覆盖热度、资金流向、Meme 排名与交易者收益。 **支持操作** | 操作 | 说明 | | -------------- | ------------------------------------------------------------ | | 社交热度榜 | 按社区讨论量排名，含情绪分析（正/负/中性） | | 综合排行榜 | 支持趋势币、搜索热榜、Binance Alpha 精选、代币化股票等多类型 | | 智能钱包流入榜 | 聪明钱净买入最多的代币 TOP 榜 | | Meme 币榜 | Pulse 发射台前 100 Meme 代币，按爆发潜力评分 | | 交易者 PnL 榜 | 地址级别 7d/30d/90d 已实现盈亏排行 | **支持链：** BSC、Base、Solana ``` 最近哪些代币社交热度最高？ 聪明钱最近在买什么？ 给我看 Binance Alpha 精选代币榜单 ``` --- ### meme-rush Meme 代币实时追踪 + AI 热门话题发现，适合快节奏 Meme 交易场景。包含两大核心功能： **Meme Rush — 发射台代币生命周期追踪** | 操作 | 说明 | | ---------- | -------------------------------------------------- | | 新发代币 | 追踪处于 Bonding Curve 阶段的新上线代币 | | 即将迁移 | 监控 Bonding Curve 接近完成、即将迁移到 DEX 的代币 | | 已迁移代币 | 刚完成迁移的代币列表，捕捉早期流动性机会 | **Topic Rush — AI 热门话题发现** | 操作 | 说明 | | -------- | --------------------------------------- | | 最新话题 | 发现最新的市场热门话题及关联代币 | | 上升话题 | 正在崛起的话题（历史最高流入 $1k–$20k） | 每个话题返回：话题名称、AI 摘要、净流入金额（总计/1h）、关联代币列表（含市值、流动性、净流入、持币人数等）。 **支持链：** Solana（Pump.fun、Raydium 等）、BSC（Four.meme、Flap 等） ``` Solana 上最新上线的 Meme 有哪些？ 有哪些 Meme 快要迁移到 DEX 了？ 现在什么话题最火？ 有哪些正在崛起的热门话题？ ``` --- ### trading-signal 监控链上聪明钱交易行为，输出结构化买卖信号供参考。 **支持操作** | 操作 | 说明 | | -------- | ------------------------------------------------------------ | | 信号获取 | 聪明钱地址在 Solana / BSC 上的买卖信号 | | 价格比对 | 信号触发价 vs 当前价，判断是否已错过入场时机 | | 信号质量 | 返回历史最大涨幅（maxGain）和聪明钱退出比例（exitRate） | | 代币标签 | 标注社交事件、发射平台（Pumpfun 等）、敏感事件（巨鲸买卖等） | | 信号状态 | 区分 active / timeout / completed，聚焦仍有效信号 | **支持链：** Solana、BSC ``` 最近有哪些聪明钱买入信号？ BNB Chain 上有没有新的链上信号？ 这个信号自触发后最高涨了多少？ ``` --- ### binance-tokenized-securities-info 查询 Ondo Finance 代币化美股在链上的实时数据与状态。 **支持操作** | 操作 | 说明 | | ------------ | ---------------------------------------------------------------- | | 资产列表 | 所有支持的代币化股票及合约地址 | | 公司信息 | CEO、行业、概念标签、证明报告链接 | | 市场状态 | Ondo 市场是否开放/暂停，下次开收盘时间 | | 企业行动 | 每只代币的停牌状态（分拆、派息、并购等） | | 实时链上行情 | 代币价格、24h 涨跌、持有人数、流通量、市值，及 PE/股息率等基本面 | | K 线数据 | OHLC 数据，支持 1 分钟到 1 天多种粒度 | **支持链：** Ethereum、BSC > 注意：每个代币代表 `multiplier` 股而非 1 股，价格换算需除以 sharesMultiplier。 ``` 当前 Ondo 市场开放了吗？ 查一下 AAPL 代币化股票的当前价格 有哪些代币化股票因企业行动停牌了？ ``` --- ## Agentic Wallet Skill `binance-agentic-wallet` 提供钱包管理、代币转账、市价兑换和限价单功能。 → 详见 [Agentic Wallet 文档](../agentic-wallet/introduction) --- ## 相关页面 - [Binance Wallet Skills 概览](./introduction) --- ## Document: Binance Wallet Skills URL: /zh-CN/dev-docs/products/wallet-skills/introduction # Binance Wallet Skills Binance Wallet Skills 是面向开发者的可组合 AI 模块，将 Binance Web3 的链上能力封装成任何 LLM Agent 或应用都能直接调用的形式。 ## 什么是 Skills 传统 API 需要开发者手动解析意图、调用接口、处理错误。Skills 将这一切封装成 AI 可以直接理解和调用的模块： - 由**自然语言意图**触发 — 无需编写 API 调用 - 每个 Skill 是独立模块 — 可单独集成或组合使用 - 兼容 Claude、ChatGPT、Copilot 和主流 AI Agent 环境 ## 已发布的 Wallet Skills (binance-web3) 目前已在 [binance-skills-hub](https://github.com/binance/binance-skills-hub/tree/main/skills/binance-web3) 发布 8 个 Skills： | Skill | 类型 | 核心能力 | | ------------------------------------- | ------------ | ----------------------------------------------------------- | | **binance-agentic-wallet** | Read + Write | 钱包管理、代币转账、市价兑换、限价单（BSC/ETH/Base/Solana） | | **query-token-info** | Read | 代币搜索、元数据、实时行情、K 线图 | | **query-token-audit** | Read | 代币安全审计：风险评分、蜜罐检测、合约验证 | | **query-address-info** | Read | 钱包地址代币持仓、价格、余额 | | **crypto-market-rank** | Read | 市场排行榜：社交热度、聪明钱流入、Meme 币、交易者 PnL | | **meme-rush** | Read | Meme 代币追踪（新发/迁移中/已迁移）+ AI 叙事发现 | | **trading-signal** | Read | 链上聪明钱信号，含信号状态和历史最大涨幅 | | **binance-tokenized-securities-info** | Read | 代币化证券（Ondo Finance）— 实时价格、市场状态、链上数据 | → [查看完整 Skills 列表](./supported-skills) --- ## Document: 钱包 API 介绍 多链钱包余额与交易查询 URL: /zh-CN/dev-docs/products/wallet-api/introduction # 钱包 API 介绍 Wallet API 提供链上钱包数据服务，包括支持的链查询、多链代币余额查询以及链上交易历史查询。 ## 功能概览 | 功能 | 接口 | 方法 | 描述 | | ------------ | ----------------------------------------------------------- | ---- | ------------------------------ | | 支持的链 | `/api/v1/dex/balance/supported/chain` | GET | 查询支持的区块链网络 | | 全部代币余额 | `/api/v1/dex/balance/all-token-balances-by-address` | GET | 查询钱包地址的全部代币余额 | | 特定代币余额 | `/api/v1/dex/balance/token-balances-by-address` | POST | 查询指定代币的余额 | | 交易历史 | `/api/v1/dex/post-transaction/transactions-by-address` | GET | 查询钱包地址的链上交易历史 | | 交易详情 | `/api/v1/dex/post-transaction/transaction-detail-by-txhash` | GET | 根据交易 Hash 查询链上交易详情 | --- ## Document: 错误码 Wallet API 错误码参考——完整的业务错误码列表，包含原因说明与排查指引。 URL: /zh-CN/dev-docs/products/wallet-api/error-codes # 错误码 ## 响应格式 所有 Wallet API 响应（包括错误响应）均返回 **HTTP 200**，业务结果通过响应体中的 `code` 字段标识。 ```json { "code": 0, "msg": "success", "data": { ... }, "timestamp": 1718000000000 } ``` `code` 非零时表示请求出错，可通过 `msg` 字段获取可读的错误描述。 --- ## 成功 | 错误码 | 说明 | | ------ | -------- | | `0` | 请求成功 | --- ## 参数错误 | 错误码 | 错误信息 | 原因 | 涉及接口 | | ------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | | `40001` | `Parameter [field] error: ` | 请求参数校验失败——字段格式非法、值超出范围、必填参数缺失或枚举值不支持。`msg` 字段会包含具体的字段名和原因。 | 所有接口 | **`40001` 常见触发场景：** - `address` 为空或缺失 - `pageSize` 超出范围（必须满足 `1 ≤ pageSize ≤ 100`） - `POST /token-balances-by-address` 请求中 `tokenContractAddresses` 列表包含无效条目（`binanceChainId` 或 `tokenContractAddress` 为空） - 必填的 `@RequestParam` 或 `@RequestBody` 字段缺失 --- ## 认证与授权错误 以下错误码由 API 网关在请求到达 Wallet API 服务之前统一拦截。 | 错误码 | 错误信息 | 原因 | | ------- | ------------------- | ------------------------------------------------------------------------------ | | `40101` | `Invalid API Key` | `X-OC-APIKEY` 请求头缺失、格式错误，或该密钥已被删除 / 禁用 | | `40102` | `Signature error` | `X-OC-SIGN` 的值与预期的 HMAC-SHA256 或 Ed25519 签名不匹配 | | `40103` | `Timestamp expired` | `X-OC-TIMESTAMP` 超出相对于服务器时间的允许 `recv_window` 范围（默认 ±5000ms） | | `40104` | `Permission denied` | 该 API Key 没有访问此接口所需的权限 | --- ## 频率限制错误 | 错误码 | 错误信息 | 原因 | | ------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `42900` | `Request rate limit exceeded. Please refer to the API docs and reduce request frequency` | 已触发 IP、API Key、用户或接口维度的频率限制。请在 `Retry-After` 响应头指定的时间后重试。 | --- ## 合规错误 ### IP 合规 | 错误码 | 错误信息 | 原因 | | ------- | ------------------------------------------------------ | -------------------------------------------------------------------------- | | `40301` | `Service not available in your region` | 客户端 IP 来自受制裁地区（如朝鲜、伊朗、古巴、叙利亚或 OFAC 制裁名单地区） | | `40302` | `Proxy or VPN detected. Please use direct connection` | 检测到客户端使用高风险 VPN 或代理 | | `40303` | `Unusual IP activity detected. Please contact support` | 检测到异常 IP 行为，如频繁切换地区或同时多地区访问 | --- ## 服务端错误 | 错误码 | 错误信息 | 原因 | | ------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `50000` | `Internal server error, please retry later` | 服务端发生未预期的错误（如空指针、序列化异常）。若问题持续存在，请携带请求时间戳联系技术支持。 | | `50001` | `Service temporarily unavailable, please retry later` | 上游余额数据提供方不可达或返回错误。请稍后重试。 | --- ## 各接口错误码速查 | 接口 | 可能的错误码 | | --------------------------------------------------------------- | ------------------------- | | `GET /api/v1/dex/balance/supported/chain` | `40001`, `50000` | | `GET /api/v1/dex/balance/all-token-balances-by-address` | `40001`, `50000`, `50001` | | `POST /api/v1/dex/balance/token-balances-by-address` | `40001`, `50000`, `50001` | | `GET /api/v1/dex/post-transaction/transactions-by-address` | `40001`, `50000`, `50001` | | `GET /api/v1/dex/post-transaction/transaction-detail-by-txhash` | `40001`, `50000`, `50001` | --- ## 排查指引 | 现象 | 可能的错误码 | 处理方式 | | ----------------- | ------------ | -------------------------------------------------------------------------------------------------------- | | 签名不匹配 | `40102` | 检查签名原文格式：`timestamp + METHOD + requestPath + body`，确保 `requestPath` 包含完整的原始查询字符串 | | 时间戳偏差 | `40103` | 使用 NTP 服务器同步系统时钟；可通过 `X-OC-RECV-WINDOW` 扩大容忍范围（最大 60000ms） | | pageSize 超出范围 | `40001` | 将 `pageSize` 控制在 `[1, 100]` 范围内 | | 持续返回 `50001` | `50001` | 上游余额服务降级，请查看[状态页](https://developers.binance.com)或联系技术支持 | --- ## Document: 兑换 API 介绍 跨 DEX 聚合报价和兑换，支持权益代币（RWA）交易 URL: /zh-CN/dev-docs/products/trading-api/introduction # 兑换 API 介绍 Trading API 提供跨去中心化交易所的代币报价、兑换和授权服务，自动选择最优路径完成代币交换。同时支持**权益代币交易**（RWA / 真实世界资产，包括 Ondo 和 BStock 股票代币）的 RFQ（询价订单）流程。 ## 功能概览 | 功能 | 接口 | 方法 | 描述 | | ----------------- | -------------------------------------------- | ---- | --------------------------------------------- | | 支持的链 | `/api/v1/dex/aggregator/supported/chain` | GET | 查询支持的区块链网络 | | 获取报价 | `/api/v1/dex/aggregator/quote` | GET | 获取代币兑换报价（支持 SWAP 和 RFQ 两种模式） | | 执行兑换 | `/api/v1/dex/aggregator/swap` | GET | 生成兑换交易数据或 RFQ 待签名数据 | | 授权交易 | `/api/v1/dex/aggregator/approve-transaction` | GET | 生成代币授权交易数据 | | 获取交易状态 | `/api/v1/dex/aggregator/history` | GET | 通过 txHash 查询 DEX 兑换交易状态 | | 提交 RFQ 订单 | `/api/v1/dex/aggregator/order/submit` | POST | 提交已签名的 RFQ 订单（仅权益代币使用） | | 查询 RFQ 订单状态 | `/api/v1/dex/aggregator/order/{orderId}` | GET | 轮询 RFQ 订单结算状态 | ## 执行模式 `/quote` 响应中的 `executionMode` 字段决定后续交易流程： | 模式 | 适用代币类型 | 流程说明 | | ------ | --------------------------- | ----------------------------------------------------------------------------------------------------------- | | `SWAP` | 普通加密货币代币 | 对 `/swap` 返回的 `tx` 签名后直接广播到链上 | | `RFQ` | 权益代币（Ondo、BStock 等） | 对 `/swap` 返回的 `rfq.typedDataToSign` 做 EIP-712 签名，通过 `/order/submit` 提交，轮询 `/order/{orderId}` | ## 权益代币交易（RWA） Trading API 支持代币化权益资产（真实世界资产），包括： - **Ondo 代币**（type=1）：代币化股票和 ETF（如 NKEon/耐克、NVDAon/英伟达、EEMon/iShares ETF）。始终通过 **3-vendor RFQ**（InchFusion + CowSwap + PcsXRfq）路由，所有路由返回 `executionMode=RFQ`。 - **BStock 代币**（type=3）：交易所上市股票代币（如 PALLon/钯金、TSLAB/特斯拉）。通过 **LiquidMesh（SWAP）+ PcsXRfq（RFQ）混合**路由，同一次询价可能同时返回一条 SWAP 路由和一条 RFQ 路由。 > **注意**：Ondo 和 BStock 代币集严格互斥，同一个代币只属于其中一种类型。 ### SWAP 模式流程（普通代币及 BStock LiquidMesh 路由） ``` GET /quote → GET /swap → 对 tx 签名 → 广播到链上 ``` ### RFQ 模式流程（Ondo 代币及 BStock PcsXRfq 路由） ``` GET /quote → GET /swap → 对 rfq.typedDataToSign 做 EIP-712 签名 → POST /order/submit → GET /order/{orderId}（轮询直到 FILLED / FAILED） ``` ### 权益代币交易关键约束 | 约束条件 | 详情 | | ---------------------------------- | ------------------------------------------------------------------------------------- | | `userWalletAddress` | RFQ 路由时 `/quote` **必填**。该地址将作为 RFQ 订单的接收方。 | | `quoteId` 有效期 | 30 秒。需在 `/quote` 后 30 秒内调用 `/swap`，否则返回 `QUOTE_EXPIRED`（40401）。 | | EIP-712 签名 | 对 `/swap` 返回的 `rfq.typedDataToSign` 签名，签名钱包须与 `userWalletAddress` 一致。 | | `/approve-transaction` 的 `vendor` | 权益代币**必填**，从 `/quote` 响应的 `vendorName` 字段取值。 | | 幂等性（`requestId`） | 重试 `/order/submit` 时复用同一 UUID；使用新 UUID 会创建新订单。 | | 交易时段 | Ondo 代币在美股非交易时段可能不可用（错误码 40367）；BStock 同理（40369）。 | --- ## Document: 错误码 兑换 API 错误码参考 — 完整的业务错误码列表、原因说明与排查建议。 URL: /zh-CN/dev-docs/products/trading-api/error-codes # 错误码 ## 响应格式 所有兑换 API 响应（包括错误）均返回 **HTTP 200**。业务结果由响应体中的 `code` 字段标识。 ```json { "code": 0, "msg": "success", "data": { ... }, "timestamp": 1718000000000 } ``` 非零 `code` 表示错误，详情参见 `msg` 字段的描述。 --- ## 成功 | 码值 | 说明 | | ---- | -------- | | `0` | 请求成功 | --- ## 参数错误 | 码值 | 消息 | 原因 | 影响接口 | | ------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | | `40001` | `Parameter [field] error: ` | 请求参数校验失败 — 字段格式无效、值超出范围、必填参数缺失或枚举值不支持。`msg` 字段包含具体字段名称和原因。 | 所有接口 | **常见 `40001` 触发场景：** - `chainId` 不是正整数或不在支持链白名单中 - `fromTokenAddress` / `toTokenAddress` 不是有效的 EVM 地址或 Solana 公钥 - `amount` 不是正数字符串 - `slippagePercent` 不是有效的小数字符串 - `gasLevel` 不是允许的枚举值之一 - 必填的 `@RequestParam` 缺失 - 询价 Ondo（RFQ）代币对时缺少 `userWalletAddress` --- ## 鉴权错误 以下错误码由 API 网关在请求到达兑换 API 服务前强制执行。 | 码值 | 消息 | 原因 | | ------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `40101` | `Invalid API Key` | `X-OC-APIKEY` 头缺失、格式错误，或对应 Key 已被删除/禁用 | | `40102` | `Signature error` | `X-OC-SIGN` 的值与预期的 HMAC-SHA256 或 Ed25519 签名不匹配。对于 `/order/submit`：`userSignature` 与 `/quote` 中的 `userWalletAddress` 不匹配 — 确认签名钱包正确且使用了 EIP-712 typed data 签名（非普通文本签名） | | `40103` | `Timestamp expired` | `X-OC-TIMESTAMP` 超出相对服务器时间允许的 `recv_window` 范围（默认 ±5000 毫秒） | | `40104` | `Permission denied` | API Key 没有访问该接口所需的权限 | --- ## 频率限制错误 | 码值 | 消息 | 原因 | | ------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `42900` | `Request rate limit exceeded. Please refer to the API docs and reduce request frequency` | IP、API Key、用户或接口级别的频率限制已达上限。根据响应头 `Retry-After` 指示的时间后重试 | --- ## 合规错误 ### IP 合规 | 码值 | 消息 | 原因 | | ------- | ------------------------------------------------------ | ------------------------------------------------------------------------------ | | `40301` | `Service not available in your region` | 客户端 IP 来自受制裁地区（如朝鲜、伊朗、古巴、叙利亚或 OFAC 制裁名单上的地区） | | `40302` | `Proxy or VPN detected. Please use direct connection` | 检测到客户端使用高风险 VPN 或代理 | | `40303` | `Unusual IP activity detected. Please contact support` | 检测到异常 IP 活动，如频繁切换位置或多地区并发访问 | ### KYT（了解你的交易） | 码值 | 消息 | 原因 | | ------- | --------------------------------------------------------- | -------------------------------------------------------------------- | | `40311` | `Transaction rejected due to high-risk address` | 交易对手地址风险评分 ≥ 70，交易被直接拒绝 | | `40312` | `Address is on sanctions list` | 地址匹配 OFAC 或联合国制裁名单 | | `40313` | `Transaction rejected due to risky fund origin` | 上游资金溯源（3-5 跳）发现与制裁地址、赌博网站或暗网实体关联 | | `40314` | `Medium-risk address detected. Please confirm to proceed` | 风险评分 40-69，客户端须向用户展示确认提示并在用户明确确认后重新提交 | --- ## 兑换 API 业务错误 ### 链支持 | 码值 | 消息 | 原因 | 影响接口 | | ------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- | | `40411` | `This chain is not supported` | 传入的 `chainId` 不在支持链白名单中，或该链已通过配置临时禁用 | `/approve-transaction`、`/quote`、`/swap`、`/history` | | `40412` | `DEX contract not configured for this chain, please contact administrator` | 该链的链上 approve 合约地址尚未在后端配置，属于运维配置问题，请联系支持 | `/approve-transaction` | ### 报价 | 码值 | 消息 | 原因 | 影响接口 | | ------- | ----------------------------------------------------------- | -------------------------------------------------------------------------- | -------- | | `40401` | `Quote expired. Please request a new quote` | `quoteId` 在缓存中未找到 — `/quote` 调用后 30 秒 TTL 已过期，或 ID 无效 | `/swap` | | `40421` | `Insufficient liquidity for this trading pair` | 当前没有活跃的流动性提供商（vendor）可为请求的链或代币对报价 | `/quote` | | `40441` | `No valid quote result from any vendor, please retry later` | 所有 vendor 均已联系但均未返回有效报价（响应为空、包含错误或输出数量为 0） | `/quote` | | `40442` | `fromTokenAddress and toTokenAddress must be different` | `fromTokenAddress` 和 `toTokenAddress` 相同 | `/quote` | ### 兑换 | 码值 | 消息 | 原因 | 影响接口 | | ------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `40461` | `No valid swap route found, please try other token pair` | `quoteId` 对应的路由引用了未知或缺失的 vendor — 请重新询价后重试 | `/swap` | | `40462` | `quoteId does not match request parameters` | `quoteId` 在缓存中存在，但一个或多个参数与原始询价请求不一致（`chainId`、`fromTokenAddress`、`toTokenAddress` 或 `amount`） | `/swap` | | `40463` | `Price impact exceeds protection threshold` | vendor 报告的价格影响超过保护阈值（默认 90%）。传入 `priceImpactProtectionPercent=100` 可禁用此检查 | `/swap` | | `40464` | `slippagePercent out of allowed range` | `slippagePercent` 不是有效数字，或超出允许范围：EVM 链 `[0, 100]`，Solana `[0, 99.9]` | `/swap` | | `40465` | `Vendor swap call failed, please retry later` | vendor 构造 swap 交易失败。常见子原因：vendor 超时、响应为 null、Gas 估算失败、Solana ALT 账户解析错误、EVM 代理地址未配置、或缺少 API Key 上下文。稍后重试 | `/swap` | ### Gas | 码值 | 消息 | 原因 | 影响接口 | | ------- | -------------------------------------------------- | ------------------------------------------------------------------- | ---------------------- | | `40432` | `Failed to estimate gas price, please retry later` | Gas 价格服务（`wallet-direct`）未返回数据，通常是瞬时问题，稍后重试 | `/approve-transaction` | ### RFQ 订单（权益代币错误） 以下错误码专用于权益 / RWA 代币交易（Ondo 和 BStock 代币）。 | 码值 | 消息 | 原因 | 影响接口 | | ------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `40374` | `RWA_INSUFFICIENT_LIQUIDITY` | RWA 代币在所有 vendor（LiquidMesh + PcsXRfq）均无可用流动性。常见于新上市或流动性较差的权益代币。 | `/quote` | | `40365` | `ONDO_TOKEN_PAIR_NOT_SUPPORTED` | 代币对两侧均不是 Ondo 代币，但已启用仅 Ondo 模式（`only-ondo-mode=true`）。确保 `fromTokenAddress` 或 `toTokenAddress` 中至少有一个是 Ondo 代币。 | `/quote` | | `40366` | `ONDO_MAX_SINGLE_ORDER_LIMIT` | 订单数量超过做市商为该 Ondo 代币配置的单笔最大限额。 | `/quote` | | `40367` | `ONDO_MARKET_STATE_NOT_TRADABLE` | Ondo 代币的底层资产市场当前处于关闭状态（如美股交易时段外或停牌期间）。待市场重新开放后重试。 | `/quote` | | `40368` | `ONDO_STABLECOIN_PAIR_INVALID` | Ondo 代币配对了不在白名单中的稳定币（如 BSC 上须与 USDT 配对，ETH 上须与 USDC 配对）。请使用支持的稳定币作为对价代币。 | `/quote` | | `40369` | `BSTOCK_INVALID_TRADING_TIME` | BStock 代币的底层证券交易所当前处于非交易时段。请在交易时段内重试。 | `/quote` | | `40370` | `BSTOCK_INVALID_TRADING_PAIR` | BStock 代币配对了不在 BStock 白名单中的代币。请使用支持的对价代币。 | `/quote` | | `40375` | `ONDO_FROM_USD_AMOUNT_TOO_SMALL` | Ondo 询价的 `fromTokenAmount` 低于最小 USD 门槛。请提高订单金额以满足最低要求（具体最低金额在 `msg` 中返回，如 "Minimum order amount is 20 USD."）。 | `/quote` | | `42901` | `ORDER_SUBMIT_IN_PROGRESS` | 相同 `requestId` 的并发提交请求已在处理中。等待首次请求完成后，使用相同 `requestId` 重试。 | `/order/submit` | --- ## 服务端错误 | 码值 | 消息 | 原因 | | ------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `50000` | `Internal server error, please retry later` | 服务端发生意外错误（如空指针、数据库故障、序列化错误）。如问题持续，请携带请求时间戳联系支持 | | `50001` | `Service temporarily unavailable, please retry later` | 上游依赖（如交易历史服务）不可达或返回错误。稍后重试 | --- ## 各接口错误码映射 | 接口 | 可能的错误码 | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `GET /supported/chain` | `40001`、`50000` | | `GET /approve-transaction` | `40001`、`40411`、`40412`、`40432`、`50000` | | `GET /quote` | `40001`、`40411`、`40421`、`40441`、`40442`、`40365`、`40366`、`40367`、`40368`、`40369`、`40370`、`40374`、`40375`、`50000` | | `GET /swap` | `40001`、`40401`、`40411`、`40461`、`40462`、`40463`、`40464`、`40465`、`50000` | | `GET /history` | `40001`、`40411`、`50001`、`50000` | | `POST /order/submit` | `40001`、`40101`、`40102`、`40401`、`42901`、`50000` | | `GET /order/{orderId}` | `40001`、`40101`、`50000` | --- ## 排查指南 | 现象 | 可能的错误码 | 处理建议 | | ------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | API 签名不匹配 | `40102` | 验证预哈希字符串构造：`timestamp + METHOD + requestPath + body`。确保 `requestPath` 包含原始查询字符串 | | RFQ 用户签名被拒绝 | `40102` | 确保 `userSignature` 是对 `rfq.typedDataToSign` 的 EIP-712 签名（使用 `eth_signTypedData_v4`），且签名钱包与 `userWalletAddress` 一致 | | 时间戳偏差 | `40103` | 将系统时钟与 NTP 服务器同步。使用 `X-OC-RECV-WINDOW` 扩展容差（最大 60000 毫秒） | | 询价成功但兑换失败 | `40401` | 立即在 `/quote` 后调用 `/swap`，quoteId TTL 为 30 秒 | | 兑换返回参数不匹配 | `40462` | 确保传给 `/swap` 的 `chainId`、`fromTokenAddress`、`toTokenAddress` 和 `amount` 与 `/quote` 请求完全一致 | | 价格影响警告 | `40463` | 减少交易金额，或传入 `priceImpactProtectionPercent=100` 跳过检查（大额订单不建议） | | 链不支持 | `40411` | 调用 `GET /supported/chain` 获取当前白名单后再构建请求 | | 持续返回 `50001` | `50001` | 历史记录服务降级，请检查状态页面或联系支持 | | Ondo 代币询价失败 | `40367` | 底层资产市场已关闭，请确认美股交易时段并在市场重新开放后重试 | | BStock 代币不可用 | `40369` | 非交易时段，请在证券交易所交易时间内重试 | | RWA 代币无报价 | `40374` | 该代币当前无任何 vendor 流动性，可尝试其他代币或稍后重试 | | `/order/submit` 并发重复被拒绝 | `42901` | 等待进行中的请求处理完毕，然后使用相同 `requestId` 重试 | --- ## Document: 链上交易 API 介绍 链上交易模拟与广播 URL: /zh-CN/dev-docs/products/transaction-api/introduction # 链上交易 API 介绍 Transaction API 提供 Gas 估算、链下模拟以及签名交易广播等能力。 ## 功能概览 | 功能 | 接口 | 方法 | 描述 | | -------------- | --------------------------------------------------- | ---- | ---------------------- | | 支持的链 | `/api/v1/dex/pre-transaction/supported/chain` | GET | 查询支持的区块链网络 | | 获取 Gas 价格 | `/api/v1/dex/pre-transaction/gas-price` | GET | 获取当前链的 Gas 价格 | | 估算 Gas Limit | `/api/v1/dex/pre-transaction/gas-limit` | POST | 估算交易所需 Gas Limit | | 模拟交易 | `/api/v1/dex/pre-transaction/simulate` | POST | 模拟执行交易 | | 广播交易 | `/api/v1/dex/pre-transaction/broadcast-transaction` | POST | 广播签名交易到链上 | | 查询广播订单 | `/api/v1/dex/post-transaction/orders` | GET | 查询广播订单状态 | --- ## Document: 错误码 链上交易 API 错误码对照表 — 完整的业务错误码列表，包含原因说明与排查指引。 URL: /zh-CN/dev-docs/products/transaction-api/error-codes # 错误码 ## 响应格式 链上交易 API 的所有响应（包括错误响应）均返回 **HTTP 200**。业务结果通过响应体中的 `code` 字段标识。 ```json { "code": 0, "msg": "success", "data": { ... }, "timestamp": 1718000000000 } ``` `code` 非零时表示发生了错误，可通过 `msg` 字段获取可读的错误描述。 --- ## 成功 | 错误码 | 说明 | | ------ | -------- | | `0` | 请求成功 | --- ## 参数错误 | 错误码 | 错误信息 | 原因 | 涉及接口 | | ------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | | `40001` | `Parameter [field] error: ` | 请求参数校验失败 — 字段格式不合法、值超出范围、必填参数缺失或枚举值不支持。`msg` 字段中会包含具体的字段名称和失败原因。 | 所有接口 | **`40001` 常见触发场景：** - `binanceChainId` 为空或不在支持链列表中 - `address` 为空或格式不合法 - 广播请求中 `evmTx` 和 `solTx` 均未提供（二者必须提供其一） - `evmTx.gasLimit` 或 `evmTx.gasPrice` 不是合法的数字字符串 - `limit` 超出范围 `[1, 100]` - 必填的 `@RequestParam` 或 `@RequestBody` 字段缺失 --- ## 认证与授权错误 以下错误码由 API 网关在请求到达链上交易 API 服务之前进行拦截。 | 错误码 | 错误信息 | 原因 | | ------- | ------------------- | ---------------------------------------------------------------------------------- | | `40101` | `Invalid API Key` | `X-OC-APIKEY` 请求头缺失、格式不合法，或该 API Key 已被删除 / 禁用 | | `40102` | `Signature error` | `X-OC-SIGN` 的值与预期的 HMAC-SHA256 或 Ed25519 签名不匹配 | | `40103` | `Timestamp expired` | `X-OC-TIMESTAMP` 与服务器时间的偏差超出允许的 `recv_window` 范围（默认 ±5 000 ms） | | `40104` | `Permission denied` | 该 API Key 没有访问此接口所需的权限 | --- ## 频率限制错误 | 错误码 | 错误信息 | 原因 | | ------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `42900` | `Request rate limit exceeded. Please refer to the API docs and reduce request frequency` | 已触发 IP、API Key、用户或接口维度的频率限制。请在 `Retry-After` 响应头指定的时间后重试 | --- ## 合规错误 ### IP 合规 | 错误码 | 错误信息 | 原因 | | ------- | ------------------------------------------------------ | ------------------------------------------------------------------------------ | | `40301` | `Service not available in your region` | 客户端 IP 来自受制裁地区（如朝鲜、伊朗、古巴、叙利亚或 OFAC 制裁名单上的地区） | | `40302` | `Proxy or VPN detected. Please use direct connection` | 检测到客户端使用了高风险 VPN 或代理 | | `40303` | `Unusual IP activity detected. Please contact support` | 检测到异常 IP 行为，如频繁切换地理位置或同时来自多个地区的访问 | ### KYT（了解您的交易） KYT 合规检查在广播交易前执行，以下四个错误码均可能由 `POST /broadcast-transaction` 返回。 | 错误码 | 错误信息 | 原因 | | ------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `40311` | `Transaction rejected due to high-risk address` | 对手方地址风险评分 ≥ 70，交易被直接拦截 | | `40312` | `Address is on sanctions list` | 该地址命中 OFAC 或联合国制裁名单 | | `40313` | `Transaction rejected due to risky fund origin` | 资金溯源（3–5 跳）发现该交易与制裁地址、赌博网站或暗网实体存在关联，交易被拦截 | | `40314` | `Medium-risk address detected. Please confirm to proceed` | 风险评分为 40–69，客户端需向用户展示风险确认提示，并在用户明确确认后重新提交 | | `40434` | `KYT verification failed. Transaction involves high-risk address` | 广播前的最终 KYT 检查未通过，交易被拦截 | --- ## 链上交易 API 业务错误 ### 链支持 | 错误码 | 错误信息 | 原因 | 涉及接口 | | ------- | ----------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- | | `40411` | `This chain is not supported` | 提供的 `binanceChainId` 不在支持链白名单中，或该链已通过配置临时禁用 | `/gas-price`、`/gas-limit`、`/simulate`、`/broadcast-transaction` | ### 广播 | 错误码 | 错误信息 | 原因 | 涉及接口 | | ------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------ | | `40431` | `Transaction broadcast failed, please check gas settings and retry` | `wallet-direct` RPC 服务拒绝了该交易或未返回结果。常见子原因：gas 不足、nonce 冲突、RPC 节点错误或原始交易字节格式不合法 | `/broadcast-transaction` | --- ## 服务端错误 | 错误码 | 错误信息 | 原因 | | ------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `50000` | `Internal server error, please retry later` | 服务端发生意外错误（如空指针、序列化错误、下游服务故障）。如问题持续出现，请携带请求时间戳联系技术支持 | | `50001` | `Service temporarily unavailable, please retry later` | 上游依赖服务（如交易历史服务、订单服务）不可达或返回错误。请稍后重试 | --- ## 各接口错误码速查 | 接口 | 可能返回的错误码 | | -------------------------------------------------------- | ------------------------------------------------------------------------------- | | `GET /api/v1/dex/pre-transaction/supported/chain` | `40001`、`50000` | | `GET /api/v1/dex/pre-transaction/gas-price` | `40001`、`40411`、`50000` | | `POST /api/v1/dex/pre-transaction/gas-limit` | `40001`、`40411`、`50000` | | `POST /api/v1/dex/pre-transaction/simulate` | `40001`、`40411`、`50000` | | `POST /api/v1/dex/pre-transaction/broadcast-transaction` | `40001`、`40311`、`40312`、`40313`、`40314`、`40411`、`40431`、`40434`、`50000` | | `GET /api/v1/dex/post-transaction/orders` | `40001`、`50000`、`50001` | --- ## 排查指引 | 现象 | 可能的错误码 | 处理建议 | | ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ | | 签名不匹配 | `40102` | 检查预签名字符串格式：`timestamp + METHOD + requestPath + body`，确保 `requestPath` 包含完整的原始查询字符串 | | 时间戳偏差过大 | `40103` | 使用 NTP 服务器同步系统时钟；可通过 `X-OC-RECV-WINDOW` 扩大容忍范围（最大 60 000 ms） | | 广播被拒绝 | `40431` | 确认 `gasLimit` 和 `gasPrice` 设置充足；广播前先调用 `/gas-price` 和 `/gas-limit` 获取当前估算值 | | KYT 高风险拦截 | `40311`/`40312`/`40313` | 目标地址已被标记为风险地址；制裁地址的交易无法继续处理 | | KYT 中风险提示 | `40314` | 向用户展示风险警告，并在用户明确确认后携带确认标志重新提交 | | 链不支持 | `40411` | 调用 `GET /api/v1/dex/pre-transaction/supported/chain` 获取当前支持链白名单 | | 多次重试均返回 `50001` | `50001` | 历史记录或订单服务出现故障，请查看[状态页面](https://developers.binance.com)或联系技术支持 | --- ## Document: 技术支持 Binance Web3 API 联系方式与支持渠道 URL: /zh-CN/dev-docs/products/others/support # 技术支持 import { Callout } from "zudoku/ui/Callout.js"; ## 联系我们 如果您在使用 Binance Web3 API 过程中遇到问题，请通过以下渠道联系我们： ### 技术支持（Technical Support） 适用于 API 集成、接口报错、签名校验等技术类问题。 | 语言 | Telegram 群组 | | ------- | ------------------------------------------------------------ | | English | [t.me/binance_api_english](https://t.me/binance_api_english) | | 中文 | [t.me/Binance_api_Chinese](https://t.me/Binance_api_Chinese) | ### 商务支持（Business Support） 适用于合作洽谈、配额申请、商务对接等非技术类问题。 - 提交表单：[forms.gle/3zjCNC1J5dBRUAsr7](https://forms.gle/3zjCNC1J5dBRUAsr7) --- ## 联系前请准备以下信息 为帮助我们更快定位问题，请在咨询时提供： - **请求时间戳**（`X-OC-TIMESTAMP` 的值） - **API Key**（仅提供前 8 位，切勿泄露完整密钥） - **接口路径**及 HTTP 方法 - **错误码**及响应体中的 `msg` 字段 - **复现步骤** 如遇安全事件或怀疑 API Key 泄露，请立即通过 Telegram 技术支持群组联系我们，并第一时间在开发者平台轮换 API Key。 --- ## Document: 更新日志 Binance Web3 API 版本更新记录 URL: /zh-CN/dev-docs/products/others/changelog # 更新日志 ## 2026-06-01 **v1.0.0 — 初始发布** - 发布 Market API：行情数据、K 线、代币搜索与分析 - 发布 Trading API：跨 DEX 聚合报价、兑换、授权 - 发布 Transaction API：链上交易模拟与广播 - 发布 Wallet API：多链钱包余额查询 --- ## Document: 行情 API 介绍 实时行情、K 线数据、代币分析 URL: /zh-CN/dev-docs/products/market-api/introduction # 行情 API 介绍 import { Callout } from "zudoku/ui/Callout.js"; Market API 提供全面的市场数据服务，包括实时价格、K 线数据、代币搜索与代币分析；并支持 RWA 代币的行情、标的信息与发行平台查询。 ## 功能概览 | 功能 | 接口 | 方法 | 描述 | | ------------------------- | ------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- | | 获取支持的链 | `/api/v1/dex/market/supported/chain` | GET | 返回行情服务支持的区块链列表。 | | 获取代币价格 | `/api/v1/dex/market/price` | POST | 获取代币的最新价格，支持批量查询，单次最多查询 100 个代币。 | | 获取代币 K 线数据 | `/api/v1/dex/market/candles` | GET | 返回代币的 K 线数据。 | | 搜索代币 | `/api/v1/dex/market/token/search` | GET | 通过代币符号或代币合约地址搜索代币。 | | 获取热门代币榜单 | `/api/v1/dex/market/token/hot-token` | GET | 获取热门代币排行榜，支持按交易额、涨跌幅、市值等维度排序，并可通过持仓分布、开发者行为、流动性等条件筛选。 | | 获取代币基础信息 | `/api/v1/dex/market/token/basic-info` | POST | 返回代币基础信息：名称、符号、Logo、精度、创建者地址、创建时间及标签。 | | 获取代币高级信息 | `/api/v1/dex/market/token/advanced-info` | GET | 返回代币综合指标，包含创建者与发射信息、各类地址持仓占比（聪明钱、KOL、狙击手、捆绑地址、新地址等）及代币标签。 | | 获取代币交易信息 | `/api/v1/dex/market/price-info` | POST | 获取代币的价格及交易数据（成交量、交易笔数、市值、持仓数等），最多支持批量查询 100 个代币。 | | 获取代币流动性池信息 | `/api/v1/dex/market/token/top-liquidity` | GET | 返回代币的主要流动性池信息，包含流动性池地址、名称、深度及代币组成。 | | 获取代币交易历史 | `/api/v1/dex/market/trades` | GET | 获取代币在链上的交易历史，支持标签与特定地址筛选。 | | 获取代币持有人排行 | `/api/v1/dex/market/token/holder` | GET | 返回代币的持币地址排行，包含持币数量、持币占比、主链币余额、买卖均价、已实现盈亏及资金来源信息。最多返回 100 条记录，不支持分页。 | | 获取代币盈利地址排行 | `/api/v1/dex/market/token/top-trader` | GET | 返回代币的头部盈利地址，按已实现收益从高到低排序。包含持仓、买卖均价、已实现盈亏及资金来源。最多返回 100 条记录，不支持分页。 | | 获取 RWA 代币发行平台列表 | `/api/v1/dex/market/rwa/platforms` | GET | 获取当前支持的所有 RWA 代币发行平台及基础信息。 | | 获取 RWA 代币价格 | `/api/v1/dex/market/rwa/price` | GET | 批量查询 RWA 代币价格，含链上价格与标的参考价格。 | | RWA 代币搜索 | `/api/v1/dex/market/rwa/search` | GET | 通过关键词或合约地址搜索 RWA 代币。 | | 获取 RWA 标的信息 | `/api/v1/dex/market/rwa/underlying-profile` | GET | 获取 RWA 代币对应的标的公司信息。 | | 获取 RWA 代币列表 | `/api/v1/dex/market/rwa/tokens` | GET | 获取 RWA 代币列表及标的信息，支持按平台和板块筛选。 | | 获取 RWA 标的行情 | `/api/v1/dex/market/rwa/underlying-market` | GET | 获取单个 RWA 代币对应的标的资产市场数据。 | --- ## Document: 错误码 行情 API 错误码对照表 — 完整的业务错误码、原因及排查指南。 URL: /zh-CN/dev-docs/products/market-api/error-codes # 错误码 ## 响应格式 所有行情 API 响应（包括错误）均返回 **HTTP 200**。业务结果通过响应体中的 `code` 字段表示。 ```json { "code": 0, "msg": "success", "data": { ... }, "timestamp": 1718000000000 } ``` `code` 非零时表示发生错误，可通过 `msg` 字段获取可读的错误描述。 --- ## 成功 | 错误码 | 描述 | | ------ | -------- | | `0` | 请求成功 | --- ## 参数错误 | 错误码 | 消息 | 原因 | 涉及接口 | | ------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- | | `40001` | `Parameter [field] error: ` | 请求参数校验失败 — 字段格式无效、值超出范围、缺少必填参数或枚举值不支持。`msg` 字段会包含具体字段名和原因说明。 | 所有接口 | **`40001` 常见触发场景：** - `binanceChainId` 为空或不在支持的链列表中 - `tokenContractAddress` 为空或格式无效 - 批量请求列表超过 100 条（`POST /price`、`POST /price-info`） - `limit` 超出范围（如 `GET /trades` 要求 `1 ≤ limit ≤ 500`） - `walletAddressFilter` 包含超过 2 个逗号分隔的地址 - `tagFilter` 设置了不支持的值 - `bar`（K 线周期）不是允许的枚举值之一 - `rankBy`、`rankingTimeFrame`、`pageId` 或 `size` 超出热门代币查询的允许范围 - 请求中缺少必填的 `@RequestParam` 参数 --- ## 鉴权与授权错误 以下错误码由 API 网关在请求到达行情 API 服务之前进行拦截。 | 错误码 | 消息 | 原因 | | ------- | ------------------- | -------------------------------------------------------------------------------- | | `40101` | `Invalid API Key` | `X-OC-APIKEY` 请求头缺失、格式错误，或该密钥已被删除/禁用 | | `40102` | `Signature error` | `X-OC-SIGN` 的值与预期的 HMAC-SHA256 或 Ed25519 签名不匹配 | | `40103` | `Timestamp expired` | `X-OC-TIMESTAMP` 超出相对于服务器时间的允许 `recv_window` 范围（默认 ±5 000 ms） | | `40104` | `Permission denied` | 该 API Key 没有访问此接口所需的权限 | --- ## 频率限制错误 | 错误码 | 消息 | 原因 | | ------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `42900` | `Request rate limit exceeded. Please refer to the API docs and reduce request frequency` | 已达到每 IP、每 API Key、每用户或每接口的频率限制。请在响应头 `Retry-After` 指定的时间后重试 | --- ## 合规错误 ### IP 合规 | 错误码 | 消息 | 原因 | | ------- | ------------------------------------------------------ | ------------------------------------------------------------------------------ | | `40301` | `Service not available in your region` | 客户端 IP 来自受制裁地区（如朝鲜、伊朗、古巴、叙利亚或 OFAC 制裁名单中的地区） | | `40302` | `Proxy or VPN detected. Please use direct connection` | 检测到客户端连接使用了高风险 VPN 或代理 | | `40303` | `Unusual IP activity detected. Please contact support` | 检测到异常 IP 活动，如频繁切换地理位置或同时多地区访问 | --- ## 行情 API 业务错误 ### 链支持 | 错误码 | 消息 | 原因 | 涉及接口 | | ------- | ----------------------------- | ---------------------------------------------------------------------- | ---------------------------------- | | `40411` | `This chain is not supported` | 提供的 `binanceChainId` 不在支持的链白名单中，或该链已通过配置临时禁用 | 所有含 `binanceChainId` 参数的接口 | --- ## 服务端错误 | 错误码 | 消息 | 原因 | | ------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `50000` | `Internal server error, please retry later` | 发生了意外的服务端错误（如空指针、序列化错误）。如问题持续，请携带请求时间戳联系技术支持 | | `50001` | `Service temporarily unavailable, please retry later` | 上游数据提供商（如 CoinMarketCap DEX 服务）不可达或返回错误，请稍后重试 | --- ## 各接口错误码速查 | 接口 | 可能的错误码 | | -------------------------------------------- | ---------------------------------- | | `GET /api/v1/dex/market/supported/chain` | `40001`、`50000` | | `POST /api/v1/dex/market/price` | `40001`、`40411`、`50000`、`50001` | | `POST /api/v1/dex/market/price-info` | `40001`、`40411`、`50000`、`50001` | | `GET /api/v1/dex/market/candles` | `40001`、`40411`、`50000`、`50001` | | `GET /api/v1/dex/market/token/search` | `40001`、`50000`、`50001` | | `POST /api/v1/dex/market/token/basic-info` | `40001`、`40411`、`50000`、`50001` | | `GET /api/v1/dex/market/token/hot-token` | `40001`、`50000`、`50001` | | `GET /api/v1/dex/market/token/advanced-info` | `40001`、`40411`、`50000`、`50001` | | `GET /api/v1/dex/market/token/top-liquidity` | `40001`、`40411`、`50000`、`50001` | | `GET /api/v1/dex/market/token/holder` | `40001`、`40411`、`50000`、`50001` | | `GET /api/v1/dex/market/token/top-trader` | `40001`、`40411`、`50000`、`50001` | | `GET /api/v1/dex/market/trades` | `40001`、`40411`、`50000`、`50001` | --- ## 排查指南 | 现象 | 可能的错误码 | 处理建议 | | ---------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------ | | 签名不匹配 | `40102` | 检查预哈希字符串的拼接方式：`timestamp + METHOD + requestPath + body`，确保 `requestPath` 包含完整的原始查询字符串 | | 时间戳偏差 | `40103` | 使用 NTP 服务器同步系统时钟，或通过 `X-OC-RECV-WINDOW` 扩大容忍范围（最大 60 000 ms） | | 链不支持 | `40411` | 在构建请求前先调用 `GET /api/v1/dex/market/supported/chain` 获取当前白名单 | | 批量请求超限 | `40001` | 将代币列表拆分为每次不超过 100 条的批次请求 | | 多次重试均返回 `50001` | `50001` | 上游数据服务降级，请查看[状态页](https://developers.binance.com)或联系技术支持 | --- ## Document: 教程与使用场景 URL: /zh-CN/dev-docs/products/agentic-wallet/tutorial # 教程与使用场景 完成 [安装 Agentic Wallet](./install) 并登录后，你可以直接用自然语言与 AI Agent 对话，Agentic Wallet Skills 会自动解析意图并执行链上操作。 --- ## 最小教程 最小工作流：查询状态 → 获取报价 → 确认执行兑换。 **1. 确认钱包连接状态** > "我的钱包现在连接了吗？地址是什么？" AI 返回连接状态和钱包地址。 **2. 查询当前余额** > "我有多少 BNB 和 USDT？" AI 返回所有非零余额及估值。 **3. 获取兑换报价（不执行）** > "给我看看把 0.01 BNB 换成 USDT 能换多少，不要执行" AI 返回预估兑换量、滑点和 Gas 估算，不发起链上交易。 **4. 执行兑换** > "好的，执行吧" AI 请求确认后发起链上 Swap，并返回订单 ID 供跟踪。 --- ## 场景一：钱包操作 ### 查询状态 > "我的钱包连接正常吗？" > "我在哪条链上？支持哪些网络？" > "我的钱包地址是什么？" ### 查询余额 > "我现在所有代币的余额是多少？" > "我还有多少 USDT？" > "帮我看一下我的总资产估值" ### 查询交易记录 > "我最近有哪些交易记录？" > "有没有还在 pending 的交易？" > "帮我查一下这笔交易 0xabc123... 的状态" ### 查询每日限额 > "我今天还剩多少可用额度？" > "我的每日交易上限是多少，今天还能用多少？" --- ## 场景二：转账 向白名单地址转账代币。 > **前置条件：** 收款地址必须已在 Binance App 中添加（Wallet → Settings → Address Book）。 **转账原生代币：** > "发送 0.02 BNB 到 0x1234...5678" **转账 ERC-20 代币：** > "转 10 USDT 给 0x1234...5678" AI 将在执行前告知转账金额和目标地址，请求你确认。成功后返回交易哈希，可继续追问状态： > "刚那笔转账上链了吗？" --- ## 场景三：市价兑换（Swap） ### 获取报价 > "把 0.1 BNB 换成 USDT 大概能换多少？只看报价，不要执行" AI 返回预估兑换量、滑点和路由，不发起链上交易。 ### 执行市价兑换 > "把 0.1 BNB 换成 USDT" > "用 50 USDT 买 BNB，滑点控制在 2%" AI 先展示报价等待确认，你说"确认"或"执行"后发起 Swap。 ### 查询订单状态 > "我刚才那笔 Swap 完成了吗？" > "帮我看一下最近的兑换订单" > "有没有还没完成的 Swap？" | 状态 | 说明 | | ---------- | ---------- | | `PENDING` | 上链处理中 | | `FINISHED` | 执行成功 | | `FAILED` | 执行失败 | --- ## 场景四：限价单 设定目标价格，价格到达时 AI 自动执行，无需守盘。 > **注意：** > 限价单仅支持 BSC 和 Solana。买单的支付代币只支持 USDT、USDC、USD1、U、原生代币；卖单的收款代币只支持 USDT、USDC、USD1、U、原生代币。 ### 创建限价买单 > "BNB 价格跌到 $500 时，用 100 USDT 买入 BNB" > "WETH 跌到 $2800 的时候，用 200 USDT 在 BSC 上买一些" AI 创建条件单并返回 strategyId，价格触达时自动执行。 ### 创建限价卖单 > "BNB 涨到 $650 时，把我 1 个 BNB 换成 USDT" > "WETH 到 $3500 帮我在 BSC 上卖 0.5 个" ### 查询限价单 > "我现在有哪些挂单？" > "查一下还在等待触发的限价单" > "帮我看一下这个限价单 9876543210 的状态" | 状态 | 说明 | | ----------- | ---------------- | | `WORKING` | 等待触发价格 | | `TRIGGERED` | 价格达到，执行中 | | `PENDING` | 上链处理中 | | `FINISHED` | 执行成功 | | `FAILED` | 执行失败 | | `EXPIRED` | 已过期 | | `CANCELED` | 已取消 | ### 取消限价单 > "取消我的 BNB 限价买单" > "把所有挂单都取消掉" --- ## 场景五：预测市场 在预测市场中交易 — 浏览市场、下注结果、管理持仓、赎回收益。 ### 浏览市场 > "搜索体育类最热门的预测市场" > "加密货币类的预测市场有哪些？" ### 下注 > "在最近一期 BTC 15 分钟价格市场中买入'涨'" AI 获取报价后展示预期成本和回报，等待你确认后再下单。 ### 查看持仓与盈亏 > "我目前的预测持仓有哪些？" > "查看我的预测组合和未实现盈亏" > "我的预测交易历史" ### 赎回收益 > "有没有已经赢了可以领取的预测？" > "赎回我的预测收益" AI 检查 `PENDING_CLAIM` 状态的持仓并触发赎回。 ### 取消订单 > "取消我的待处理预测订单" | 状态 | 说明 | | ------------------ | -------------------- | | `PENDING` | 订单已创建，尚未提交 | | `SUBMITTED` | 已提交，等待执行 | | `FILLED` | 完全成交 | | `PARTIALLY_FILLED` | 部分成交 | | `CANCELLED` | 已被用户或系统取消 | | `FAILED` | 执行失败 | | `EXPIRED` | 市场结束导致过期 | --- ## 场景六：安全设置 安全设置仅在 Binance App 中修改，你可以随时通过 AI 查询当前配置： > "我现在的每日限额是多少？" > "我的可交易代币范围是什么？" > "异常交易是自动拒绝还是需要二次确认？" 如需修改：**Binance App → Agentic Wallet 管理页 → 右上角设置图标** --- ## 场景七：自动化交易策略 结合 Binance 已发布的 Wallet Skills（如 `meme-rush`、`trading-signal`、`query-token-info`、`query-token-audit`），你可以构建端到端的自动化交易策略。 > **提示：** 以下场景需安装对应的 Skills。从 > [binance-skills-hub](https://github.com/binance/binance-skills-hub/tree/main/skills/binance-web3) > 安装。 ### 策略一：Meme 代币狙击 利用 `meme-rush` 监控新上线或即将迁移的 Meme 代币，结合 `query-token-audit` 进行安全预检，确认安全后下单。 **示例对话：** > "Solana 上有哪些新上线的 Meme 代币？" AI 通过 `meme-rush` 返回处于 Bonding Curve 阶段的新代币列表。 > "帮我审计一下 XXX 这个代币的安全性" AI 通过 `query-token-audit` 返回风险评分、蜜罐检测、税率分析等。 > "看起来风险可控，用 50 USDT 买入" AI 确认后通过 Agentic Wallet 执行市价兑换。 --- ### 策略二：聪明钱跟单 利用 `trading-signal` 实时监控聪明钱买入信号，自动检查后跟进交易。 **基础用法：** > "最近有哪些聪明钱买入信号？" AI 通过 `trading-signal` 返回活跃信号，包括代币、触发价、当前价、最大涨幅等。 > "这个信号对应的代币安全吗？帮我查一下" AI 调用 `query-token-audit` 返回安全审计结果。 > "确认无误，用 50 USDT 买入" AI 通过 Agentic Wallet 执行交易。 **进阶用法 — 自动化跟单：** > "帮我每 5 分钟检查一次聪明钱信号，有新信号就自动审计，如果风险等级是 LOW 就用 50 USDT 买入" AI Agent 会设置定时任务，自动完成：拉取信号 → 安全审计 → 确认后交易。具体实现方式由 Agent 根据你的指令自行规划。 --- ### 策略三：热门叙事捕捉 利用 `meme-rush` 的 AI 叙事识别功能，发现当前市场热点，提前布局。 **示例对话：** > "现在什么叙事最火？资金流入最多的主题是什么？" AI 通过 `meme-rush` 返回按资金净流入排序的叙事主题。 > "这个叙事下有哪些代表性代币？" AI 返回相关代币列表及市场数据。 > "帮我查一下 XXX 的持币分布和流动性" AI 通过 `query-token-info` 返回代币详情、持币分析、流动性数据。 > "流动性够深，设置一个限价单：涨到 $1.2 时卖出 50%" AI 通过 Agentic Wallet 创建限价卖单。 --- ### 最佳实践 | 原则 | 说明 | | ------------ | --------------------------------------------------- | | **先查后买** | 任何非主流代币，交易前先用 `query-token-audit` 审计 | | **小额试水** | 新策略先用小额验证，确认流程无误后再放大 | | **设置止损** | 利用限价卖单设定止损点，避免被套 | | **分散风险** | 不要把所有资金押在单一代币或单一叙事上 | | **持续监控** | 定期检查限价单状态和持仓变化 | > ⚠️ **风险提示：** > 链上交易存在滑点、MEV 攻击、合约风险等。所有交易决策应基于你自己的研究（DYOR），Skills 仅提供信息和执行能力，不构成投资建议。 --- ## 下一步 - [Skills 参考](./skills-reference)：Skills 能力的完整说明 - [支持的 Skills](../wallet-skills/introduction)：查看所有可用的 Wallet Skills --- ## Document: Skills 参考 URL: /zh-CN/dev-docs/products/agentic-wallet/skills-reference # Skills 参考 `binance-agentic-wallet` Skill 通过 `baw` CLI 提供钱包管理和链上交易功能。 **支持链：** BNB Smart Chain (BSC)、Ethereum、Base、Solana --- ## Skill 文档结构 ``` binance-agentic-wallet/ ├── SKILL.md # 主文档：命令路由、安全策略、常用代币地址 └── references/ ├── preflight.md # 预检流程：Skill 版本检查、CLI 版本检查 ├── authentication.md # 登录/登出流程 ├── wallet-view.md # 钱包查询：状态、地址、余额、交易记录等 ├── wallet-setting.md # 安全设置（只读） ├── send.md # 代币转账 ├── market-order.md # 市价兑换 ├── limit-order.md # 限价单 ├── prediction.md # 预测市场交易 └── security.md # 交易前安全预检流程 ``` --- ## 主要功能 ### 钱包管理 查询钱包状态、地址、余额、交易记录、安全设置等。 ``` 我的钱包连接正常吗？ 我的钱包地址是什么？ 我有多少 BNB 和 USDT？ 查一下我最近的交易记录 今天还剩多少可用额度？ ``` ### 代币转账 向通讯录地址转账代币。收款地址须在 Binance App 通讯录中。 ``` 发送 0.02 BNB 到 0x1234...5678 转 10 USDT 给 0x1234...5678 ``` ### 市价兑换 获取报价或以当前市价执行代币兑换。支持自定义滑点和 MEV 保护。 ``` 把 0.1 BNB 换成 USDT 大概能换多少？只看报价 把 0.1 BNB 换成 USDT 用 50 USDT 买 BNB，滑点控制在 2% ``` ### 限价单 设定目标价格，价格到达时自动执行。 > **注意：** 限价单仅支持 BSC 和 Solana。 ``` BNB 价格跌到 $500 时，用 100 USDT 买入 BNB 涨到 $650 时，卖出 1 BNB 换 USDT 查看我的挂单 取消我的 BNB 限价单 ``` ### 预测市场 在预测市场中交易 — 浏览市场、下注结果、跟踪持仓、赎回收益。 ``` 搜索体育类最热门的预测市场 在最近一期 BTC 15 分钟价格市场中买入"涨" 我当前的预测持仓有哪些？ 查看我的预测盈亏 赎回我的预测收益 取消我的待处理预测订单 ``` --- ## 相关页面 - [安装 Agentic Wallet](./install) - [教程与使用场景](./tutorial) --- ## Document: Binance Agentic Wallet URL: /zh-CN/dev-docs/products/agentic-wallet/introduction # Binance Agentic Wallet ## 什么是 Binance Agentic Wallet 链上操作正在变得越来越复杂：限价挂单、多链资产管理……每一步都需要用户手动操作，随时盯盘，一不小心就错过最佳时机。 **Binance Agentic Wallet 改变了这一切。** 它让你可以用自然语言告诉 AI 你想做什么——AI 负责理解你的意图、选择最优路径，并在你设定的安全规则范围内自动执行链上操作。你不需要懂合约地址，不需要手动输参数，不需要守在屏幕前。 ### 为什么选择 Binance Agentic Wallet **MPC Keyless 安全机制** 与 Binance Wallet 采用完全相同的 MPC Keyless 技术：私钥永远不会在任何单一设备或服务器上被完整重建，AI Agent 无法直接持有或转移你的私钥，所有操作均有链上日志可审计。 **你制定规则，AI 在规则内执行** 在 Binance App 中设定每日限额、可交易代币范围和异常交易处理方式。这些规则在 API 层面约束 Agent 的行为，任何超出规则的操作都会被自动拒绝或发起二次确认。 **自然语言即操作界面** 兑换、转账、挂单、查余额——全部通过对话完成。安装 Skills 后，接入 Claude、ChatGPT、Copilot 等主流 AI Agent，Agentic Wallet 即刻可用。 --- ## 核心能力 | 能力 | 说明 | | --------------------- | -------------------------------------------------- | | **Authentication** | QR 码扫码登录、会话管理、登出 | | **Wallet** | 状态查询、地址、余额、交易记录、每日限额、安全设置 | | **Market Order** | 市价兑换（Swap）、报价查询、订单查询 | | **Limit Order** | 限价挂单（买/卖）、订单管理、取消 | | **Prediction Market** | 浏览市场、下注预测、管理持仓、赎回收益 | > 更多功能持续开发中，敬请期待。 ### Security: MPC Keyless - 私钥永远不会在任何单一设备或服务器上被完整重建 - 所有 Agent 操作均有日志记录，可随时审计 - Agent 在 API 层面受约束，无法突破用户设置的规则 ### 你制定规则 - 在 Binance App 中设置每日限额和可交易代币范围 - 可随时在 App 里登出 Agentic Wallet，取消 Agent 的操作权限 - 异常交易支持自动拒绝或 App 二次确认两种处理模式 --- ## 典型场景 **查询资产状态** > "我的钱包地址是什么？ USDT 余额还有多少？ 今天还能操作多少额度？" **市价兑换** > "把 0.1 BNB 换成 USDT" — AI 自动获取报价， 确认后执行链上兑换。 **限价挂单** > "BNB 价格跌到 $500 时， 用 100 USDT 买入 BNB" — 条件单自动等待触发， 无需守盘。 **代币转账** > "把 10 USDT 转到 0x123 的地址" — 收款地址须在通讯录中， AI 请求确认后执行。 **预测市场交易** > "押注 10 USDT 赌 BTC 5分钟内上涨" — AI 展示当前赔率，确认下注后执行预测。 --- ## 安装 运行以下命令安装 Skills，CLI 会在安装过程中自动完成： ```bash npx skills add binance/binance-skills-hub/skills/binance-web3/binance-agentic-wallet ``` 详见 [安装 Agentic Wallet](./install)。 --- ## 支持链 当前版本支持 4 条主流网络，更多链即将推出。 | 网络 | Chain ID | 状态 | | --------------------- | -------- | ----------- | | BNB Smart Chain (BSC) | 56 | ✅ 支持 | | Ethereum | 1 | ✅ 支持 | | Base | 8453 | ✅ 支持 | | Solana | CT_501 | ✅ 支持 | | 更多网络 | — | 🔜 即将推出 | --- ## Document: 安装 Agentic Wallet URL: /zh-CN/dev-docs/products/agentic-wallet/install # 安装 Agentic Wallet 完成以下两步即可通过 AI 自然语言驱动链上操作。 --- ## 前置条件 **Node.js 18+**：Skills 安装程序需要 Node.js 18 或以上版本。 **Binance 账号 & MPC Wallet** 1. 您需要首先拥有一个币安账号 2. 注册登录好币安账号后，您需要先创建一个 App 端 MPC Wallet，从而拥有创建 Agentic Wallet 的权限 --- ## 第一步：安装 Skills ```bash npx skills add binance/binance-skills-hub/skills/binance-web3/binance-agentic-wallet ``` > 如果你尚未安装 `baw` CLI，Skills 会在第一次使用时自动完成安装。 --- ## 第二步：登录 安装完成后，在 AI Agent 中直接说： > "登录 Binance Agentic Wallet" Agent 会返回一个登录链接。如果您在移动端点击该链接，将直接跳转至 Binance App；如果您在网页端打开，则需要使用 Binance App 扫描二维码，并在 App 内确认登录。 如果这是您第一次登录，我们会在 Binance App 中为您走完整个标准创建流程，创建完成后，您会进入 Agentic Wallet 管理页。 如需登出，直接告诉 AI： > "退出登录" --- ## 安全设置建议 安全规则仅在 Binance App 中配置，AI 只能读取，无法修改。建议初次使用时： - 每日限额设置为较小金额（如 $50） - 可交易代币限定为有限代币范围 - 异常交易处理设为"需 App 二次确认" 如需修改：**Binance App → Agentic Wallet 管理页 → 右上角设置图标** --- ## 下一步 → [教程与使用场景](./tutorial) --- ## API Reference --- ### Binance Web3 API (1.0.0) Cross-chain wallet, market, trading, and transaction APIs for the Binance Web3 API platform. #### General Data ##### `GET /api/v1/dex/market/supported/chain` 获取支持的链 返回行情服务支持的区块链列表。 Operation ID: `getSupportedChains` ##### `POST /api/v1/dex/market/price` 获取代币价格 获取代币的最新价格，支持批量查询，单次最多查询 100 个代币。 Operation ID: `getTokenPrice` ##### `POST /api/v1/dex/market/price-info` 获取代币交易信息 获取代币的价格及交易数据（成交量、交易笔数、市值、持仓数等），最多支持批量查询 100 个代币。 Operation ID: `getTokenTradingInfo` ##### `GET /api/v1/dex/market/candles` 获取代币 K 线数据 返回代币的 K 线数据。 Operation ID: `getCandles` ##### `GET /api/v1/dex/market/token/search` 代币搜索 通过代币符号或代币合约地址搜索代币。 Operation ID: `searchToken` ##### `POST /api/v1/dex/market/token/basic-info` 获取代币基础信息 返回代币基础信息：名称、符号、Logo、精度、创建者地址、创建时间及标签。 Operation ID: `getTokenBasicInfo` ##### `GET /api/v1/dex/market/token/advanced-info` 获取代币高级信息 返回代币综合指标，包含创建者与发射信息、各类地址持仓占比（聪明钱、KOL、狙击手、捆绑地址、新地址等）及代币标签。 Operation ID: `getTokenAdvancedInfo` ##### `GET /api/v1/dex/market/token/hot-token` 获取热门代币榜单 获取热门代币排行榜，支持按交易额、涨跌幅、市值等维度排序，并可通过持仓分布、开发者行为、流动性等条件筛选。 Operation ID: `getHotTokenList` ##### `GET /api/v1/dex/market/token/holder` 获取代币持有人排行 返回代币的持币地址排行，包含持币数量、持币占比、主链币余额、买卖均价、已实现盈亏及资金来源信息。最多返回100条记录，不支持分页。 Operation ID: `getHoldersRanking` ##### `GET /api/v1/dex/market/token/top-trader` 获取代币盈利地址排行 返回代币的头部盈利地址，按已实现收益从高到低排序。包含持仓、买卖均价、已实现盈亏及资金来源。最多返回100条记录，不支持分页。 Operation ID: `getTopTraders` ##### `GET /api/v1/dex/market/token/top-liquidity` 获取代币流动性池信息 返回代币的主要流动性池信息，包含流动性池地址、名称、深度及代币组成。 Operation ID: `getTopLiquidityPools` ##### `GET /api/v1/dex/market/trades` 获取代币交易历史 获取代币在链上的交易历史，支持标签与特定地址筛选。 Operation ID: `getTokenTrades` #### RWA Data ##### `GET /api/v1/dex/market/rwa/platforms` 获取 RWA 代币发行平台列表 获取当前支持的 RWA 代币发行平台及基础信息。 Operation ID: `getRwaTokenIssuancePlatforms` ##### `GET /api/v1/dex/market/rwa/price` 获取 RWA 代币价格 批量查询 RWA 代币价格，含链上价格与标的参考价格。 Operation ID: `getRwaTokenPrice` ##### `GET /api/v1/dex/market/rwa/search` RWA 代币搜索 通过关键词或合约地址搜索 RWA 代币。 Operation ID: `searchRwaToken` ##### `GET /api/v1/dex/market/rwa/underlying-profile` 获取 RWA 标的信息 获取 RWA 代币对应的标的公司信息。 Operation ID: `getRwaUnderlyingInfo` ##### `GET /api/v1/dex/market/rwa/tokens` 获取 RWA 代币列表 获取 RWA 代币列表及标的信息，支持按平台和板块筛选。 Operation ID: `getRwaTokenList` ##### `GET /api/v1/dex/market/rwa/underlying-market` 获取 RWA 标的行情 获取单个 RWA 代币对应的标的资产市场数据。 Operation ID: `getRwaUnderlyingMarketData` #### Trading API ##### `GET /api/v1/dex/aggregator/supported/chain` 获取聚合器支持的链 返回 DEX 聚合服务当前支持的所有区块链信息。支持链列表由服务端动态配置，可能随时变更。 传入 `binanceChainId` 仅返回该链信息；不传则返回全量列表。 Operation ID: `getAggregatorSupportedChains` ##### `GET /api/v1/dex/aggregator/approve-transaction` 获取 ERC-20 代币授权交易数据 在执行 DEX 兑换前，生成授权 DEX Router 操作用户 ERC-20 代币的链上交易数据。 Calldata 按 ERC-20 ABI 标准编码（approve 函数选择器 + spender + 授权数量）。 Operation ID: `getErc20ApproveTransaction` ##### `GET /api/v1/dex/aggregator/quote` 获取聚合交易报价 向多个 vendor 并发询价，返回按 `toTokenAmount` 降序排列的路由列表。 每条路由携带独立的 `quoteId`（TTL 约 30 秒），swap 接口通过它定位要构造 calldata 的路由。 Operation ID: `getAggregatedQuote` ##### `GET /api/v1/dex/aggregator/swap` 执行代币兑换（构造链上交易数据） 基于先前的询价路由构造链上 swap 交易的 calldata。请求按 `quoteId` 命中 Redis 缓存（TTL 约 30 秒）；缓存过期返回 `QUOTE_EXPIRED`（40401）， 参数与缓存不一致返回 `SWAP_QUOTE_MISMATCH`（40462）。 Operation ID: `buildSwapTransaction` ##### `GET /api/v1/dex/aggregator/swap-instruction` 构造 Solana 交易指令 `/swap` 的 Solana 专用对偶接口。共享完整的 quote → route → vendor `buildSwapTx` → priceImpact → minReceive → 指令组装 流水线；唯一区别 在响应：本接口不返回签名序列化后的 base64 完整交易，而是返回 **未编译 （uncompiled）** 的指令列表 + Address Lookup Table (ALT) 地址列表， 由调用方自行完成 v0 交易编译、签名、上链。 适用场景： - 调用方需在签名前追加 / 前置自定义指令（例如手续费拆分、自定义日志）； - 复用平台策划好的路由、滑点、PS 变体重写、ALT 注入、ComputeBudget 覆盖、ATA 合批，同时自行掌控最终上链字节。 仅支持 `binanceChainId=CT_501`（Solana），其他链返回 `CHAIN_NOT_SUPPORTED` (40411)。参数与 `/swap` 的 Solana 子集对齐 （不含 EVM 专用的 `approveTransaction` / `approveAmount` / `gasLimit`）。 Operation ID: `buildSolanaSwapInstructions` ##### `GET /api/v1/dex/aggregator/history` 查询交易状态 根据 `binanceChainId` + `txHash` 查询链上 DEX 兑换交易的详细状态。 响应说明： - 交易不存在：`data` 为 `null`（非 HTTP 404）。 - 交易失败：`status=failed`，含 `errorMsg`；聚合业务字段（`txType`、`dexRouter`、 `fromTokenDetails`、`toTokenDetails`）为 `null`。 - 交易成功：`status=success`，有聚合事件时包含完整 token 详情。 Operation ID: `getTransactionStatus` ##### `POST /api/v1/dex/aggregator/order/submit` 提交 RFQ 订单 将已签名的 RFQ 订单提交至后端，由后端转发给对应 vendor relayer 完成链上撮合。 仅当 `executionMode=RFQ`（Ondo、BStock 等权益 / RWA 代币）时使用。 **流程**：`GET /quote` → 选择 RFQ 路由 → `GET /swap` → 对 `rfq.typedDataToSign` 做 EIP-712 签名（`eth_signTypedData_v4`）→ 调用本接口 → 轮询 `GET /order/{orderId}` 直到 `FILLED` 或 `FAILED`。 **幂等性**：30 分钟内相同 `requestId` 重复提交直接返回首次结果，不重复调 vendor。 每次新提交生成新 UUID；重试时复用同一 UUID。 Operation ID: `submitRfqOrder` ##### `GET /api/v1/dex/aggregator/order/{orderId}` 查询 RFQ 订单状态 按平台 `orderId`（由 `POST /order/submit` 返回）查询 RFQ 订单的结算状态。 持续轮询直到 `status` 到达终态：`FILLED`（链上已结算）或 `FAILED`（结算失败）。 Operation ID: `getRfqOrderStatus` #### Transaction API ##### `GET /api/v1/dex/pre-transaction/supported/chain` 获取链上交易支持的链 返回 Transaction 服务当前支持的区块链列表（用于 Gas 估算、模拟和广播）。 支持链由服务端动态配置，可能随时变更。 Operation ID: `getTransactionSupportedChains` ##### `GET /api/v1/dex/pre-transaction/gas-price` 获取 Gas 价格 查询指定链当前的网络 Gas 价格。返回结构因链族而异： - EVM 链：同时返回 `evmLegacyGasPrice`（传统 gasPrice）和 `eip1559GasPrice`（baseFee + priority/max fee，链支持 EIP-1559 时）。 - Solana 链：返回 `solanaGasPrice`（compute-unit 价格和 Jito 小费）。 与当前链族无关的字段为 `null`。 Operation ID: `getGasPrice` ##### `POST /api/v1/dex/pre-transaction/gas-limit` 估算 Gas Limit 为未签名交易估算 Gas Limit（Solana 链则为 compute-unit 上限）。 根据 `binanceChainId` 提供 `evmTx`（EVM 链）或 `solTx`（Solana 链）。 Operation ID: `getGasLimit` ##### `POST /api/v1/dex/pre-transaction/simulate` 模拟交易 在广播前对交易进行链下模拟，预测执行结果。 响应包含预测的执行状态、各账户/代币余额变化以及 ERC-20 授权变化（EVM 链）。 根据 `binanceChainId` 提供 `evmTx`（EVM 链）或 `solTx`（Solana 链）。 Operation ID: `simulateTransactions` ##### `POST /api/v1/dex/pre-transaction/broadcast-transaction` 广播交易 通过 Binance Web3 API 中继将客户端已签名的交易广播到链上。返回 `txHash` 以及内部 `orderId`， 可用于通过 post-transaction 服务跟踪链上状态。 可选的 MEV 保护（仅 EVM 链）会通过私有 mempool 转发交易，缓解抢跑与三明治攻击。 Operation ID: `broadcastTransactions` ##### `GET /api/v1/dex/post-transaction/orders` 查询广播订单 查询通过 `/pre-transaction/broadcast-transaction` 提交的广播订单。 支持按 `txStatus` 或 `orderId` 过滤，并通过 `cursor` 分页。 Operation ID: `getBroadcastOrders` #### Wallet API ##### `GET /api/v1/dex/balance/supported/chain` 获取钱包支持的链 返回 Wallet 服务能够查询余额的区块链列表。支持链由服务端动态配置，可能随时变更。 传入 `binanceChainId` 仅返回该链信息；不传则返回全量列表。 Operation ID: `getWalletSupportedChains` ##### `GET /api/v1/dex/balance/all-token-balances-by-address` 查询地址全部代币余额 返回地址在一个或多个链上的全部代币余额，支持分页。 将 `excludeRiskToken=true` 可过滤空投风险币与蜜罐币（蜜罐检测当前仅支持 ETH / BSC / SOL / BASE）。 Operation ID: `getAllTokenBalancesByAddress` ##### `POST /api/v1/dex/balance/token-balances-by-address` 查询地址特定代币余额 查询指定 (链, 合约) 列表的代币余额，单次请求最多 20 条。 `excludeRiskToken="0"` 过滤风险代币（默认），`"1"` 不过滤。 Operation ID: `getTokenBalancesByAddress` ##### `GET /api/v1/dex/post-transaction/transactions-by-address` 查询地址链上交易历史 返回钱包地址在指定链上的交易历史。仅返回最近 6 个月的记录，按时间倒序排列。 支持游标分页、时间范围筛选和代币合约筛选。 Operation ID: `getTransactionsByAddress` ##### `GET /api/v1/dex/post-transaction/transaction-detail-by-txhash` 根据 Hash 查询交易详情 根据 `binanceChainId` 与 `txHash` 查询链上交易详情，返回交易的输入、输出、内部调用与代币转账明细。 Operation ID: `getTransactionDetailByHash`