{ "openapi": "3.0.2", "info": { "title": "Binance Web3 API", "description": "Cross-chain wallet, market, trading, and transaction APIs for the Binance Web3 API platform.", "x-description-cn": "Binance Web3 API 平台跨链钱包、行情、交易和链上交易 API。", "version": "1.0.0", "termsOfService": "https://www.binance.com/en/terms", "contact": { "name": "Binance API Support", "url": "https://www.binance.com/en/support" } }, "x-product-type": "rest-api", "x-skip-connectors-examples": true, "x-auth": "web3wallet", "x-rate-limits-guide": "authentication#rate-limits", "x-rate-limits-guide-cn": "authentication#频率限制", "x-security-guide": "authentication", "x-security-guide-cn": "authentication", "x-api-key-guide": "https://www.binance.com/en/support/faq/detail/360002502072", "x-api-key-guide-cn": "https://www.binance.com/cn/support/faq/detail/360002502072", "externalDocs": { "description": "Web3 Wallet docs", "url": "https://web3.binance.com/en/dev-docs/introduction" }, "tags": [ { "name": "Market API", "x-displayName": "Market API", "x-displayName-cn": "行情 API" }, { "name": "Trading API", "x-displayName": "Trading API", "x-displayName-cn": "交易 API" }, { "name": "Transaction API", "x-displayName": "Transaction API", "x-displayName-cn": "链上交易 API" }, { "name": "Wallet API", "x-displayName": "Wallet API", "x-displayName-cn": "钱包 API" } ], "servers": [ { "url": "https://web3.binance.com/build" } ], "paths": { "/api/v1/dex/market/supported/chain": { "get": { "summary": "Get Supported Chains", "x-summary-cn": "获取支持的链", "description": "Return the list of blockchains supported by the market service.", "x-description-cn": "返回行情服务支持的区块链列表。", "tags": ["Market API"], "operationId": "getSupportedChains", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-supported-chains" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getSupportedChains.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_supported_chains.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetSupportedChainsExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "responses": { "200": { "description": "Supported chains returned successfully.", "x-description-cn": "成功返回支持的链列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0, "description": "Business status code. 0 indicates success.", "x-description-cn": "业务状态码，0 表示成功。" }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "List of supported blockchain networks.", "x-description-cn": "支持的区块链网络列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier.", "x-description-cn": "链唯一标识（例如 \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana）。" }, "name": { "type": "string", "example": "Ethereum", "description": "Full chain name.", "x-description-cn": "链全称。" }, "shortName": { "type": "string", "example": "ETH", "description": "Short chain name.", "x-description-cn": "链简称。" }, "logoUrl": { "type": "string", "example": "https://onchainos.bnbstatic.com/image/admin_mgs_image_upload/20250228/b549e557-76ca-4873-88ef-3a107cf2c9fe.png", "description": "Chain logo image URL.", "x-description-cn": "链 Logo 链接。" }, "caseSensitive": { "type": "boolean", "example": false, "description": "Whether addresses on this chain are case-sensitive.", "x-description-cn": "该链的地址是否区分大小写。" }, "nativeTokenSymbol": { "type": "string", "example": "ETH", "description": "Symbol of the chain's native asset.", "x-description-cn": "原生代币符号。" }, "nativeTokenDecimals": { "type": "integer", "format": "int32", "example": 18, "description": "Native token decimals.", "x-description-cn": "原生代币精度。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/price": { "post": { "summary": "Get Token Price", "x-summary-cn": "获取代币价格", "description": "Get the latest price for tokens. Supports batch queries, up to 100 tokens per request.", "x-description-cn": "获取代币的最新价格，支持批量查询，单次最多查询 100 个代币。", "tags": ["Market API"], "operationId": "getTokenPrice", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-token-price" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getTokenPrice.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_token_price.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetTokenPriceExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "requestBody": { "required": true, "description": "Tokens to price. Up to 100 entries.", "x-description-cn": "待查询的代币列表，单次最多 100 条。", "content": { "application/json": { "schema": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": ["binanceChainId", "tokenContractAddress"], "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识（例如 \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana）。" }, "tokenContractAddress": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7", "description": "Token contract address.", "x-description-cn": "代币合约地址。" } } } }, "examples": { "evm": { "summary": "EVM tokens", "x-summary-cn": "EVM 代币", "value": [ { "binanceChainId": "1", "tokenContractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7" }, { "binanceChainId": "56", "tokenContractAddress": "0x55d398326f99059ff775485246999027b3197955" } ] }, "solana": { "summary": "Solana token", "x-summary-cn": "Solana 代币", "value": [ { "binanceChainId": "CT_501", "tokenContractAddress": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB" } ] } } } } }, "responses": { "200": { "description": "Token prices returned successfully.", "x-description-cn": "成功返回代币价格。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "One price entry per requested token.", "x-description-cn": "每个请求代币对应一条价格信息。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "price": { "type": "string", "example": "1.0002", "description": "Latest USD price of the token.", "x-description-cn": "代币最新美元价格。" }, "time": { "type": "integer", "format": "int64", "example": 1748601600000, "description": "Token price observation time, Unix millisecond timestamp.", "x-description-cn": "代币价格的对应获取时间，Unix 毫秒时间戳。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "201": { "description": "Created.", "x-description-cn": "已创建。" }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/price-info": { "post": { "summary": "Get Token Trading Info", "x-summary-cn": "获取代币交易信息", "description": "Get token price and trading data (volume, transactions, market cap, holders, etc.). Supports batch queries for up to 100 tokens.", "x-description-cn": "获取代币的价格及交易数据（成交量、交易笔数、市值、持仓数等），最多支持批量查询 100 个代币。", "tags": ["Market API"], "operationId": "getTokenTradingInfo", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-token-trading-info" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getTokenTradingInfo.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_token_trading_info.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetTokenTradingInfoExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "requestBody": { "required": true, "description": "Tokens to query. Up to 100 entries.", "x-description-cn": "待查询的代币列表，单次最多 100 条。", "content": { "application/json": { "schema": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": ["binanceChainId", "tokenContractAddress"], "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7", "description": "Token contract address.", "x-description-cn": "代币合约地址。" } } } } } } }, "responses": { "200": { "description": "Price info returned successfully.", "x-description-cn": "成功返回价格信息。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Price info entry per requested token.", "x-description-cn": "每个请求代币对应一条价格信息。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Chain unique identifier.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "price": { "type": "string", "example": "1.0002", "description": "Latest token price, denominated in USD.", "x-description-cn": "代币最新美元价格。" }, "time": { "type": "integer", "format": "int64", "example": 1748601600000, "description": "Token price observation time, Unix millisecond timestamp.", "x-description-cn": "代币价格的对应获取时间，Unix 毫秒时间戳。" }, "marketCap": { "type": "string", "example": "83500000.00", "description": "Token market cap, denominated in USD.", "x-description-cn": "代币市值，美元计价。" }, "priceChange5M": { "type": "string", "example": "0.12", "description": "5-minute price change percentage. \"0.12\" means a 0.12% increase.", "x-description-cn": "5 分钟内价格变动百分比，如 \"0.12\" 表示上涨 0.12%。" }, "priceChange1H": { "type": "string", "example": "1.05", "description": "1-hour price change percentage. \"1.05\" means a 1.05% increase.", "x-description-cn": "1 小时内价格变动百分比，如 \"1.05\" 表示上涨 1.05%。" }, "priceChange4H": { "type": "string", "example": "2.30", "description": "4-hour price change percentage. \"2.30\" means a 2.30% increase.", "x-description-cn": "4 小时内价格变动百分比，如 \"2.30\" 表示上涨 2.30%。" }, "priceChange24H": { "type": "string", "example": "-0.85", "description": "24-hour price change percentage. \"-0.85\" means a 0.85% decrease.", "x-description-cn": "24 小时内价格变动百分比，如 \"-0.85\" 表示下跌 0.85%。" }, "volume5M": { "type": "string", "example": "12500.50", "description": "Trading volume in the last 5 minutes, denominated in USD.", "x-description-cn": "近5分钟交易量，美元计价。" }, "volume1H": { "type": "string", "example": "120000.30", "description": "Trading volume in the last 1 hour, denominated in USD.", "x-description-cn": "近1小时交易量，美元计价。" }, "volume4H": { "type": "string", "example": "550000.20", "description": "Trading volume in the last 4 hours, denominated in USD.", "x-description-cn": "近4小时交易量，美元计价。" }, "volume24H": { "type": "string", "example": "1250000.50", "description": "Trading volume in the last 24 hours, denominated in USD.", "x-description-cn": "近24小时交易量，美元计价。" }, "buyVolume5M": { "type": "string", "example": "6800.00", "description": "Buy volume in the last 5 minutes, denominated in USD.", "x-description-cn": "近5分钟买入量，美元计价。" }, "buyVolume1H": { "type": "string", "example": "65000.00", "description": "Buy volume in the last 1 hour, denominated in USD.", "x-description-cn": "近1小时买入量，美元计价。" }, "buyVolume4H": { "type": "string", "example": "300000.00", "description": "Buy volume in the last 4 hours, denominated in USD.", "x-description-cn": "近4小时买入量，美元计价。" }, "buyVolume24H": { "type": "string", "example": "680000.30", "description": "Buy volume in the last 24 hours, denominated in USD.", "x-description-cn": "近24小时买入量，美元计价。" }, "sellVolume5M": { "type": "string", "example": "5700.00", "description": "Sell volume in the last 5 minutes, denominated in USD.", "x-description-cn": "近5分钟卖出量，美元计价。" }, "sellVolume1H": { "type": "string", "example": "55000.00", "description": "Sell volume in the last 1 hour, denominated in USD.", "x-description-cn": "近1小时卖出量，美元计价。" }, "sellVolume4H": { "type": "string", "example": "250000.00", "description": "Sell volume in the last 4 hours, denominated in USD.", "x-description-cn": "近4小时卖出量，美元计价。" }, "sellVolume24H": { "type": "string", "example": "570000.20", "description": "Sell volume in the last 24 hours, denominated in USD.", "x-description-cn": "近24小时卖出量，美元计价。" }, "txs5M": { "type": "integer", "format": "int64", "example": 60, "description": "Number of transactions in the last 5 minutes.", "x-description-cn": "近5分钟交易笔数。" }, "txs1H": { "type": "integer", "format": "int64", "example": 720, "description": "Number of transactions in the last 1 hour.", "x-description-cn": "近1小时交易笔数。" }, "txs4H": { "type": "integer", "format": "int64", "example": 2880, "description": "Number of transactions in the last 4 hours.", "x-description-cn": "近4小时交易笔数。" }, "txs24H": { "type": "integer", "format": "int64", "example": 1523, "description": "Number of transactions in the last 24 hours.", "x-description-cn": "近24小时交易笔数。" }, "buyTxs5M": { "type": "integer", "format": "int64", "example": 33, "description": "Number of buy transactions in the last 5 minutes.", "x-description-cn": "近5分钟买入笔数。" }, "buyTxs1H": { "type": "integer", "format": "int64", "example": 380, "description": "Number of buy transactions in the last 1 hour.", "x-description-cn": "近1小时买入笔数。" }, "buyTxs4H": { "type": "integer", "format": "int64", "example": 1500, "description": "Number of buy transactions in the last 4 hours.", "x-description-cn": "近4小时买入笔数。" }, "buyTxs24H": { "type": "integer", "format": "int64", "example": 812, "description": "Number of buy transactions in the last 24 hours.", "x-description-cn": "近24小时买入笔数。" }, "sellTxs5M": { "type": "integer", "format": "int64", "example": 27, "description": "Number of sell transactions in the last 5 minutes.", "x-description-cn": "近5分钟卖出笔数。" }, "sellTxs1H": { "type": "integer", "format": "int64", "example": 340, "description": "Number of sell transactions in the last 1 hour.", "x-description-cn": "近1小时卖出笔数。" }, "sellTxs4H": { "type": "integer", "format": "int64", "example": 1380, "description": "Number of sell transactions in the last 4 hours.", "x-description-cn": "近4小时卖出笔数。" }, "sellTxs24H": { "type": "integer", "format": "int64", "example": 711, "description": "Number of sell transactions in the last 24 hours.", "x-description-cn": "近24小时卖出笔数。" }, "maxPrice": { "type": "string", "example": "1.0023", "description": "24-hour high price, denominated in USD.", "x-description-cn": "24小时最高价，美元计价。" }, "minPrice": { "type": "string", "example": "0.9987", "description": "24-hour low price, denominated in USD.", "x-description-cn": "24小时最低价，美元计价。" }, "circSupply": { "type": "string", "example": "83000000000", "description": "Current circulating supply of the token.", "x-description-cn": "代币当前流通量。" }, "liquidity": { "type": "string", "example": "1250000.50", "description": "Token liquidity, denominated in USD.", "x-description-cn": "代币流动性，美元计价。" }, "holders": { "type": "integer", "format": "int64", "example": 45832, "description": "Number of holding addresses.", "x-description-cn": "持币地址数量。" }, "bnVolume5M": { "type": "string", "example": "0", "description": "Trading volume from Binance MPC wallets via Binance Web3 DEX in the last 5 minutes, denominated in USD.", "x-description-cn": "近5分钟 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易量，美元计价。" }, "bnVolume1H": { "type": "string", "example": "0", "description": "Trading volume from Binance MPC wallets via Binance Web3 DEX in the last 1 hour, denominated in USD.", "x-description-cn": "近1小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易量，美元计价。" }, "bnVolume4H": { "type": "string", "example": "0", "description": "Trading volume from Binance MPC wallets via Binance Web3 DEX in the last 4 hours, denominated in USD.", "x-description-cn": "近4小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易量，美元计价。" }, "bnVolume24H": { "type": "string", "example": "35000.80", "description": "Trading volume from Binance MPC wallets via Binance Web3 DEX in the last 24 hours, denominated in USD.", "x-description-cn": "近24小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易量，美元计价。" }, "bnBuyVolume5M": { "type": "string", "example": "0", "description": "Buy volume from Binance MPC wallets via Binance Web3 DEX in the last 5 minutes, denominated in USD.", "x-description-cn": "近5分钟 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易量，美元计价。" }, "bnBuyVolume1H": { "type": "string", "example": "0", "description": "Buy volume from Binance MPC wallets via Binance Web3 DEX in the last 1 hour, denominated in USD.", "x-description-cn": "近1小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易量，美元计价。" }, "bnBuyVolume4H": { "type": "string", "example": "0", "description": "Buy volume from Binance MPC wallets via Binance Web3 DEX in the last 4 hours, denominated in USD.", "x-description-cn": "近4小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易量，美元计价。" }, "bnBuyVolume24H": { "type": "string", "example": "20000.50", "description": "Buy volume from Binance MPC wallets via Binance Web3 DEX in the last 24 hours, denominated in USD.", "x-description-cn": "近24小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易量，美元计价。" }, "bnSellVolume5M": { "type": "string", "example": "0", "description": "Sell volume from Binance MPC wallets via Binance Web3 DEX in the last 5 minutes, denominated in USD.", "x-description-cn": "近5分钟 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易量，美元计价。" }, "bnSellVolume1H": { "type": "string", "example": "0", "description": "Sell volume from Binance MPC wallets via Binance Web3 DEX in the last 1 hour, denominated in USD.", "x-description-cn": "近1小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易量，美元计价。" }, "bnSellVolume4H": { "type": "string", "example": "0", "description": "Sell volume from Binance MPC wallets via Binance Web3 DEX in the last 4 hours, denominated in USD.", "x-description-cn": "近4小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易量，美元计价。" }, "bnSellVolume24H": { "type": "string", "example": "15000.30", "description": "Sell volume from Binance MPC wallets via Binance Web3 DEX in the last 24 hours, denominated in USD.", "x-description-cn": "近24小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易量，美元计价。" }, "bnTxs5M": { "type": "integer", "format": "int64", "example": 0, "description": "Number of transactions from Binance MPC wallets via Binance Web3 DEX in the last 5 minutes.", "x-description-cn": "近5分钟 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易笔数。" }, "bnTxs1H": { "type": "integer", "format": "int64", "example": 0, "description": "Number of transactions from Binance MPC wallets via Binance Web3 DEX in the last 1 hour.", "x-description-cn": "近1小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易笔数。" }, "bnTxs4H": { "type": "integer", "format": "int64", "example": 0, "description": "Number of transactions from Binance MPC wallets via Binance Web3 DEX in the last 4 hours.", "x-description-cn": "近4小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易笔数。" }, "bnTxs24H": { "type": "integer", "format": "int64", "example": 156, "description": "Number of transactions from Binance MPC wallets via Binance Web3 DEX in the last 24 hours.", "x-description-cn": "近24小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的交易笔数。" }, "bnBuyTxs5M": { "type": "integer", "format": "int64", "example": 0, "description": "Number of buy transactions from Binance MPC wallets via Binance Web3 DEX in the last 5 minutes.", "x-description-cn": "近5分钟 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易笔数。" }, "bnBuyTxs1H": { "type": "integer", "format": "int64", "example": 0, "description": "Number of buy transactions from Binance MPC wallets via Binance Web3 DEX in the last 1 hour.", "x-description-cn": "近1小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易笔数。" }, "bnBuyTxs4H": { "type": "integer", "format": "int64", "example": 0, "description": "Number of buy transactions from Binance MPC wallets via Binance Web3 DEX in the last 4 hours.", "x-description-cn": "近4小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易笔数。" }, "bnBuyTxs24H": { "type": "integer", "format": "int64", "example": 89, "description": "Number of buy transactions from Binance MPC wallets via Binance Web3 DEX in the last 24 hours.", "x-description-cn": "近24小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的买入交易笔数。" }, "bnSellTxs5M": { "type": "integer", "format": "int64", "example": 0, "description": "Number of sell transactions from Binance MPC wallets via Binance Web3 DEX in the last 5 minutes.", "x-description-cn": "近5分钟 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易笔数。" }, "bnSellTxs1H": { "type": "integer", "format": "int64", "example": 0, "description": "Number of sell transactions from Binance MPC wallets via Binance Web3 DEX in the last 1 hour.", "x-description-cn": "近1小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易笔数。" }, "bnSellTxs4H": { "type": "integer", "format": "int64", "example": 0, "description": "Number of sell transactions from Binance MPC wallets via Binance Web3 DEX in the last 4 hours.", "x-description-cn": "近4小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易笔数。" }, "bnSellTxs24H": { "type": "integer", "format": "int64", "example": 67, "description": "Number of sell transactions from Binance MPC wallets via Binance Web3 DEX in the last 24 hours.", "x-description-cn": "近24小时 Binance MPC 钱包通过 Binance Web3 DEX 发生的卖出交易笔数。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "201": { "description": "Created.", "x-description-cn": "已创建。" }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/candles": { "get": { "summary": "Get Candles", "x-summary-cn": "获取代币 K 线数据", "description": "Return candlestick (K-line) data for a token.", "x-description-cn": "返回代币的 K 线数据。", "tags": ["Market API"], "operationId": "getCandles", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-candles" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getCandles.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_candles.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetCandlesExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识（例如 \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana）。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7" }, "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, { "name": "bar", "in": "query", "required": false, "schema": { "type": "string", "example": "1m", "default": "1m", "enum": [ "1s", "5s", "30s", "1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "6h", "8h", "12h", "1d", "3d", "1w", "1M" ] }, "description": "Candlestick time granularity, default \"1m\" (1 minute). Available values: 1s (1 second), 5s (5 seconds), 30s (30 seconds), 1m (1 minute), 3m (3 minutes), 5m (5 minutes), 15m (15 minutes), 30m (30 minutes), 1h (1 hour), 2h (2 hours), 4h (4 hours), 6h (6 hours), 8h (8 hours), 12h (12 hours), 1d (1 day), 3d (3 days), 1w (1 week), 1M (1 month).", "x-description-cn": "K 线时间粒度，默认 \"1m\"，即时间粒度为1分钟。可选值：1s（1秒）、5s（5秒）、30s（30秒）、 1m（1分钟）、3m（3分钟）、5m（5分钟）、15m（15分钟）、30m（30分钟）、1h（1小时）、 2h（2小时）、4h（4小时）、6h（6小时）、8h（8小时）、12h（12小时）、1d（1天）、 3d（3天）、1w（1周）、1M（1月）。" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "example": 1748600000000 }, "description": "End time for the query, Unix millisecond timestamp. Returns candles earlier than this time (exclusive).", "x-description-cn": "查询结束时间，Unix 毫秒时间戳。返回早于该时间的 K 线（不含该时间点）。" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "example": 1748000000000 }, "description": "Start time for the query, Unix millisecond timestamp. Returns candles later than this time (exclusive).", "x-description-cn": "查询起始时间，Unix 毫秒时间戳。返回晚于该时间的 K 线（不含该时间点）。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 100, "default": 100 }, "description": "Number of candles to return. Defaults to 100.", "x-description-cn": "返回的 K 线条数，默认 100。" } ], "responses": { "200": { "description": "Candle data returned successfully.", "x-description-cn": "成功返回 K 线数据。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Candlestick data list. Each record contains 7 values in order: open, high, low, close, volume, timestamp (ms), tradeCount.", "x-description-cn": "K 线数据列表，每条记录包含 7 个值，依次为：开盘价、最高价、 最低价、收盘价、成交量、时间戳（毫秒）、交易笔数。", "example": [ [ 1.0001, 1.0023, 0.9987, 1.001, 125000.5, 1748600000000, 42 ], [ 1.001, 1.0035, 1.0001, 1.0028, 187500.3, 1748600060000, 38 ] ], "items": { "type": "array", "description": "Single candlestick: [open, high, low, close, volume, timestamp (ms), tradeCount]. Prices and volume are denominated in USD.", "x-description-cn": "单条 K 线：[开盘价, 最高价, 最低价, 收盘价, 成交量, 时间戳(毫秒), 交易笔数]，价格及成交量均为美元计价。", "example": [ 1.0001, 1.0023, 0.9987, 1.001, 125000.5, 1748600000000, 42 ], "items": { "type": "number", "example": 1.0001 } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/token/search": { "get": { "summary": "Search Token", "x-summary-cn": "代币搜索", "description": "Search tokens by symbol or contract address.", "x-description-cn": "通过代币符号或代币合约地址搜索代币。", "tags": ["Market API"], "operationId": "searchToken", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#search-token" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/searchToken.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/search_token.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/SearchTokenExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "chains", "in": "query", "required": true, "schema": { "type": "string", "example": "1,56,CT_501" }, "description": "List of chain IDs to search, comma-separated.", "x-description-cn": "待搜索的链 ID 列表，英文逗号分隔。" }, { "name": "search", "in": "query", "required": true, "schema": { "type": "string", "example": "USDT" }, "description": "Search keyword. Can be a token address or token symbol.", "x-description-cn": "搜索关键词，可传入代币地址或代币符号。" } ], "responses": { "200": { "description": "Search results returned successfully.", "x-description-cn": "成功返回搜索结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Matching tokens.", "x-description-cn": "匹配的代币列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "tokenName": { "type": "string", "example": "Tether USD", "description": "Token full name.", "x-description-cn": "代币全称。" }, "tokenSymbol": { "type": "string", "example": "USDT", "description": "Token symbol.", "x-description-cn": "代币符号。" }, "tokenLogoUrl": { "type": "string", "nullable": true, "example": "https://static.onchainos.com/tokens/usdt.png", "description": "Token logo link. Null when no logo is available.", "x-description-cn": "代币 Logo 链接，无 Logo 时返回 null。" }, "tokenContractAddress": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "decimals": { "type": "integer", "format": "int32", "example": 6, "description": "Token decimals.", "x-description-cn": "代币精度。" }, "explorerUrl": { "type": "string", "example": "https://etherscan.io/token/0xdac17f958d2ee523a2206206994597c13d831ec7", "description": "Block explorer link for the token.", "x-description-cn": "代币对应的区块链浏览器链接。" }, "change": { "type": "string", "nullable": true, "example": "-5.23", "description": "24-hour price change. \"-5.23\" means a 5.23% decrease. Null when no data.", "x-description-cn": "24 小时价格涨跌幅，如 \"-5.23\" 表示下跌 5.23%，无数据时返回 null。" }, "holders": { "type": "string", "example": "45832", "description": "Number of holder addresses.", "x-description-cn": "持币地址数量。" }, "liquidity": { "type": "string", "example": "1250000.50", "description": "Token liquidity, denominated in USD.", "x-description-cn": "代币流动性，美元计价。" }, "marketCap": { "type": "string", "example": "83500000.00", "description": "Token market cap, denominated in USD.", "x-description-cn": "代币市值，美元计价。" }, "price": { "type": "string", "example": "1.0001", "description": "Latest token price, denominated in USD.", "x-description-cn": "代币最新美元价格。" }, "tagList": { "type": "object", "title": "Tag info.", "x-title-cn": "标签信息。", "properties": { "isRecognized": { "type": "boolean", "nullable": true, "example": true, "description": "True indicates the token is listed on major centralized exchanges or widely recognized by the community.", "x-description-cn": "True 表示代币已在头部中心化交易所上线或被社区广泛认可。" } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/token/basic-info": { "post": { "summary": "Get Token Basic Info", "x-summary-cn": "获取代币基础信息", "description": "Return basic metadata for a token: name, symbol, logo, decimals, creator address, creation time, and tag info.", "x-description-cn": "返回代币基础信息：名称、符号、Logo、精度、创建者地址、创建时间及标签。", "tags": ["Market API"], "operationId": "getTokenBasicInfo", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-token-basic-info" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getTokenBasicInfo.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_token_basic_info.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetTokenBasicInfoExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7" }, "description": "Token contract address.", "x-description-cn": "代币合约地址。" } ], "responses": { "200": { "description": "Token basic info returned successfully.", "x-description-cn": "成功返回代币基础信息。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "title": "Token basic info.", "x-title-cn": "代币基础信息。", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique identifier of the chain.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0xdac17f958d2ee523a2206206994597c13d831ec7", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "tokenName": { "type": "string", "example": "Tether USD", "description": "Token full name.", "x-description-cn": "代币全称。" }, "tokenSymbol": { "type": "string", "example": "USDT", "description": "Token symbol.", "x-description-cn": "代币符号。" }, "tokenLogoUrl": { "type": "string", "nullable": true, "example": "https://static.onchainos.com/tokens/usdt.png", "description": "Token logo link. Null when no logo is available.", "x-description-cn": "代币 Logo 链接，无 Logo 时返回 null。" }, "decimals": { "type": "integer", "format": "int32", "example": 6, "description": "Token decimals.", "x-description-cn": "代币精度。" }, "creatorAddress": { "type": "string", "example": "0x21a31ee1afc51d94c2efccaa2092ad1028285549", "description": "Token creator wallet address.", "x-description-cn": "代币创建者钱包地址。" }, "createTime": { "type": "integer", "format": "int64", "example": 1716892020000, "description": "Token creation time, Unix millisecond timestamp.", "x-description-cn": "代币创建时间，Unix 毫秒时间戳。" }, "tagList": { "type": "object", "title": "Token tag information.", "x-title-cn": "代币标签信息。", "properties": { "isRecognized": { "type": "boolean", "nullable": true, "example": true, "description": "True indicates the token is listed on major centralized exchanges or widely recognized by the community.", "x-description-cn": "True 表示代币已在头部中心化交易所上线或被社区广泛认可。" } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "201": { "description": "Created.", "x-description-cn": "已创建。" }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/token/advanced-info": { "get": { "summary": "Get Token Advanced Info", "x-summary-cn": "获取代币高级信息", "description": "Return comprehensive metrics for a token, including creator and launch info, holding percentages by address type (smart money, KOL, sniper, bundler, fresh wallet, etc.), and token tags.", "x-description-cn": "返回代币综合指标，包含创建者与发射信息、各类地址持仓占比（聪明钱、KOL、狙击手、捆绑地址、新地址等）及代币标签。", "tags": ["Market API"], "operationId": "getTokenAdvancedInfo", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-token-advanced-info" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getTokenAdvancedInfo.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_token_advanced_info.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetTokenAdvancedInfoExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933" }, "description": "Token contract address.", "x-description-cn": "代币合约地址。" } ], "responses": { "200": { "description": "Advanced token info returned successfully.", "x-description-cn": "成功返回代币高级信息。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "isInternal": { "type": "integer", "format": "int32", "example": 0, "description": "Whether the token is internal to the platform. 0 = no, 1 = yes.", "x-description-cn": "是否平台内部代币。0=否，1=是。" }, "protocolId": { "type": "integer", "format": "int32", "nullable": true, "example": 1, "description": "Protocol ID the token belongs to. Null when no protocol is associated.", "x-description-cn": "代币所属协议 ID，无所属协议时返回 null。" }, "progress": { "type": "string", "nullable": true, "example": "75", "description": "Token launch progress for inner-market tokens, range 0–100.", "x-description-cn": "内盘代币发射进度，范围 0–100。" }, "createTime": { "type": "integer", "format": "int64", "example": 1714000000000, "description": "Token creation time, Unix millisecond timestamp.", "x-description-cn": "代币创建时间，Unix 毫秒时间戳。" }, "creatorAddress": { "type": "string", "example": "0x21a31ee1afc51d94c2efccaa2092ad1028285549", "description": "Token creator wallet address.", "x-description-cn": "代币创建者钱包地址。" }, "devCreatedTokenCount": { "type": "integer", "format": "int64", "example": 15, "description": "Total tokens the developer has ever created.", "x-description-cn": "开发者历史创建代币总数。" }, "devMigratedTokenCount": { "type": "integer", "format": "int64", "example": 8, "description": "Total tokens the developer has successfully launched (migrated).", "x-description-cn": "开发者历史发射成功代币数。" }, "devMigratedTokenPercent": { "type": "string", "example": "53.5", "description": "Developer launch success rate. \"53.5\" means 53.5%.", "x-description-cn": "开发者发射成功率，如 \"53.5\" 表示 53.5%。" }, "top10HoldingPercent": { "type": "string", "example": "40.08", "description": "Top 10 addresses combined holding percentage. \"40.08\" means 40.08%.", "x-description-cn": "Top 10 地址合计持仓占比，如 \"40.08\" 表示 40.08%。" }, "devHoldingPercent": { "type": "string", "example": "5.23", "description": "Developer holding percentage. \"5.23\" means 5.23%.", "x-description-cn": "开发者持仓占比，如 \"5.23\" 表示 5.23%。" }, "smartMoneyHoldingPercent": { "type": "string", "example": "2.15", "description": "Smart money holding percentage. \"2.15\" means 2.15%.", "x-description-cn": "聪明钱持仓占比，如 \"2.15\" 表示 2.15%。" }, "kolHoldingPercent": { "type": "string", "example": "1.5", "description": "KOL holding percentage. \"1.5\" means 1.5%.", "x-description-cn": "KOL 持仓占比，如 \"1.5\" 表示 1.5%。" }, "bundlerHoldingPercent": { "type": "string", "example": "12.3", "description": "Bundler holding percentage. \"12.3\" means 12.3%.", "x-description-cn": "捆绑地址持仓占比，如 \"12.3\" 表示 12.3%。" }, "proHoldingPercent": { "type": "string", "example": "4.2", "description": "Professional holder percentage. \"4.2\" means 4.2%.", "x-description-cn": "专业持有者持仓占比，如 \"4.2\" 表示 4.2%。" }, "freshWalletHoldingPercent": { "type": "string", "example": "3.8", "description": "Fresh wallet holding percentage. \"3.8\" means 3.8%.", "x-description-cn": "新地址持仓占比，如 \"3.8\" 表示 3.8%。" }, "sniperHoldingPercent": { "type": "string", "example": "3.1", "description": "Sniper holding percentage. \"3.1\" means 3.1%.", "x-description-cn": "狙击手持仓占比，如 \"3.1\" 表示 3.1%。" }, "insiderHoldingPercent": { "type": "string", "example": "2.5", "description": "Insider holding percentage. \"2.5\" means 2.5%.", "x-description-cn": "内部地址持仓占比，如 \"2.5\" 表示 2.5%。" }, "holders": { "type": "integer", "format": "int64", "example": 45832, "description": "Number of holding addresses.", "x-description-cn": "持币地址数量。" }, "bnHolderCount": { "type": "integer", "format": "int64", "example": 1203, "description": "Number of Binance MPC wallets holding this token.", "x-description-cn": "持有当前代币的 Binance MPC 钱包数。" }, "bnTraderCount7D": { "type": "integer", "format": "int64", "example": 250, "description": "Number of Binance MPC wallets that traded via Binance Web3 DEX in the last 7 days.", "x-description-cn": "近 7 日通过 Binance Web3 DEX 交易的 Binance MPC 钱包数。" }, "tokenTags": { "type": "array", "description": "Token tags. Returns tags matched by the token. Possible values:\n\n- `alpha` — Binance Alpha\n- `tge` — Binance TGE\n- `communityRecognized` — Highly recognized by community\n- `devSellAll` — Developer sold entire holding\n- `devSell` — Developer sold partial holding\n- `devBuy` — Developer bought tokens\n- `smartMoneyBuy` — Smart money buying\n- `smartMoneySell` — Smart money selling\n- `devRemoveLiquidity` — Developer removed liquidity\n- `devAddLiquidity` — Developer added liquidity\n- `devBurnToken` — Developer burned tokens\n- `dexScreenerPaid` — DexScreener paid\n- `volumeSurge` — Volume surge\n- `volumePlunge` — Volume plunge\n- `lowLiquidity` — Low liquidity\n- `washTrading` — Wash trading detected\n- `devWashTrading` — Developer wash trading detected\n- `insiderWashTrading` — Insider wash trading detected\n", "x-description-cn": "代币标签数组。若代币命中对应标签，则进行返回。可选值：\n\n- `alpha` — Binance Alpha\n- `tge` — Binance TGE\n- `communityRecognized` — 社区认可程度高\n- `devSellAll` — 开发者清仓\n- `devSell` — 开发者减仓\n- `devBuy` — 开发者加仓\n- `smartMoneyBuy` — 聪明钱加仓\n- `smartMoneySell` — 聪明钱减仓\n- `devRemoveLiquidity` — 开发者减流动性\n- `devAddLiquidity` — 开发者加流动性\n- `devBurnToken` — 开发者烧币\n- `dexScreenerPaid` — Dexscreener付费\n- `volumeSurge` — 交易量骤增\n- `volumePlunge` — 交易量骤减\n- `lowLiquidity` — 流动性低\n- `washTrading` — 存在刷量交易\n- `devWashTrading` — 存在开发者刷量交易\n- `insiderWashTrading` — 存在内幕交易者刷量交易\n", "items": { "type": "string", "example": "Alpha", "enum": [ "alpha", "tge", "communityRecognized", "devSellAll", "devSell", "devBuy", "smartMoneyBuy", "smartMoneySell", "devRemoveLiquidity", "devAddLiquidity", "devBurnToken", "dexScreenerPaid", "volumeSurge", "volumePlunge", "lowLiquidity", "washTrading", "devWashTrading", "insiderWashTrading" ], "x-enum-descriptions": [ "Binance Alpha", "Binance TGE", "社区认可", "开发者清仓", "开发者减仓", "开发者加仓", "聪明钱加仓", "聪明钱减仓", "开发者减流动性", "开发者加流动性", "开发者烧币", "Dexscreener付费", "交易量骤增", "交易量骤减", "流动性低", "刷量交易", "DEV刷量交易", "内幕交易者刷量交易" ] } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/token/hot-token": { "get": { "summary": "Get Hot Token List", "x-summary-cn": "获取热门代币榜单", "description": "Get hot token ranking list. Supports sorting by volume, price change, market cap, etc., with filters for holding distribution, developer behavior, liquidity, and more.", "x-description-cn": "获取热门代币排行榜，支持按交易额、涨跌幅、市值等维度排序，并可通过持仓分布、开发者行为、流动性等条件筛选。", "tags": ["Market API"], "operationId": "getHotTokenList", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-hot-token-list" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getHotTokenList.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_hot_token_list.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetHotTokenListExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": false, "schema": { "type": "string", "example": "1" }, "description": "Chain identifier. Single value only. Omit to return mixed results across all chains.", "x-description-cn": "链唯一标识，仅支持单值。不传时返回所有链的混合结果。" }, { "name": "rankBy", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 4, "enum": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] }, "description": "Ranking field. 1=price, 2=price change, 3=transactions, 4=volume, 5=market cap, 6=liquidity, 7=creation time, 8=holders, 9=Binance MPC wallet holders, 10=net inflow.", "x-description-cn": "排序字段。1=价格，2=涨跌幅，3=交易笔数，4=交易额，5=市值，6=流动性，7=创建时间，8=持币地址数，9=Binance MPC 钱包持有数，10=净流入。" }, { "name": "rankingTimeFrame", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 3, "default": 3, "enum": [1, 2, 3, 4, 5] }, "description": "Data time range. 1=1 min, 2=5 min, 3=1 hour, 4=4 hours, 5=24 hours. Default 1 hour.", "x-description-cn": "数据的统计时间范围。1=1 分钟，2=5 分钟，3=1 小时，4=4 小时，5=24 小时。默认 1 小时。" }, { "name": "priceChangePercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "5" }, "description": "Minimum price change filter. \"5\" means 5%.", "x-description-cn": "涨跌幅筛选最小值，如 \"5\" 表示 5%。" }, { "name": "priceChangePercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum price change filter. \"100\" means 100%.", "x-description-cn": "涨跌幅筛选最大值，如 \"100\" 表示 100%。" }, { "name": "volumeMin", "in": "query", "required": false, "schema": { "type": "string", "example": "10000" }, "description": "Minimum volume filter, denominated in USD.", "x-description-cn": "成交额筛选最小值，美元计价。" }, { "name": "volumeMax", "in": "query", "required": false, "schema": { "type": "string", "example": "1000000" }, "description": "Maximum volume filter, denominated in USD.", "x-description-cn": "成交额筛选最大值，美元计价。" }, { "name": "txsMin", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Minimum transaction count.", "x-description-cn": "交易笔数筛选最小值。" }, { "name": "txsMax", "in": "query", "required": false, "schema": { "type": "string", "example": "10000" }, "description": "Maximum transaction count.", "x-description-cn": "交易笔数筛选最大值。" }, { "name": "marketCapMin", "in": "query", "required": false, "schema": { "type": "string", "example": "100000" }, "description": "Minimum market cap filter, denominated in USD.", "x-description-cn": "市值筛选最小值，美元计价。" }, { "name": "marketCapMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100000000" }, "description": "Maximum market cap filter, denominated in USD.", "x-description-cn": "市值筛选最大值，美元计价。" }, { "name": "liquidityMin", "in": "query", "required": false, "schema": { "type": "string", "example": "10000" }, "description": "Minimum liquidity filter, denominated in USD.", "x-description-cn": "流动性筛选最小值，美元计价。" }, { "name": "liquidityMax", "in": "query", "required": false, "schema": { "type": "string", "example": "10000000" }, "description": "Maximum liquidity filter, denominated in USD.", "x-description-cn": "流动性筛选最大值，美元计价。" }, { "name": "devHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum developer holding percentage filter. \"5\" means 5%.", "x-description-cn": "开发者持仓占比筛选最小值，如 \"5\" 表示 5%。" }, { "name": "devHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "10" }, "description": "Maximum developer holding percentage filter. \"5\" means 5%.", "x-description-cn": "开发者持仓占比筛选最大值，如 \"5\" 表示 5%。" }, { "name": "inflowUsdMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum net inflow filter, denominated in USD.", "x-description-cn": "净流入筛选最小值，美元计价。" }, { "name": "inflowUsdMax", "in": "query", "required": false, "schema": { "type": "string", "example": "1000000" }, "description": "Maximum net inflow filter, denominated in USD.", "x-description-cn": "净流入筛选最大值，美元计价。" }, { "name": "holdersMin", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Minimum holder count.", "x-description-cn": "持币地址数最小值。" }, { "name": "holdersMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100000" }, "description": "Maximum holder count.", "x-description-cn": "持币地址数最大值。" }, { "name": "bnHolderCountMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum Binance MPC wallet holders.", "x-description-cn": "Binance MPC 钱包持有数最小值。" }, { "name": "bnHolderCountMax", "in": "query", "required": false, "schema": { "type": "string", "example": "10000" }, "description": "Maximum Binance MPC wallet holders.", "x-description-cn": "Binance MPC 钱包持有数最大值。" }, { "name": "top10HoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum top-10 holding percentage. \"5\" means 5%.", "x-description-cn": "前 10 地址持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "top10HoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum top-10 holding percentage. \"5\" means 5%.", "x-description-cn": "前 10 地址持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "sniperHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum sniper holding percentage. \"5\" means 5%.", "x-description-cn": "狙击者持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "sniperHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum sniper holding percentage. \"5\" means 5%.", "x-description-cn": "狙击者持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "smartMoneyHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum smart-money holding percentage. \"5\" means 5%.", "x-description-cn": "聪明钱持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "smartMoneyHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum smart-money holding percentage. \"5\" means 5%.", "x-description-cn": "聪明钱持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "kolHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum KOL holding percentage. \"5\" means 5%.", "x-description-cn": "KOL 持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "kolHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum KOL holding percentage. \"5\" means 5%.", "x-description-cn": "KOL 持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "proHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum pro-trader holding percentage. \"5\" means 5%.", "x-description-cn": "专业持有者持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "proHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum pro-trader holding percentage. \"5\" means 5%.", "x-description-cn": "专业持有者持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "freshWalletHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum fresh-wallet holding percentage. \"5\" means 5%.", "x-description-cn": "新地址持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "freshWalletHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum fresh-wallet holding percentage. \"5\" means 5%.", "x-description-cn": "新地址持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "insiderHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum insider holding percentage. \"5\" means 5%.", "x-description-cn": "内部地址持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "insiderHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum insider holding percentage. \"5\" means 5%.", "x-description-cn": "内部地址持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "bundlerHoldingPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum bundler holding percentage. \"5\" means 5%.", "x-description-cn": "捆绑地址持仓占比最小值，如 \"5\" 表示 5%。" }, { "name": "bundlerHoldingPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum bundler holding percentage. \"5\" means 5%.", "x-description-cn": "捆绑地址持仓占比最大值，如 \"5\" 表示 5%。" }, { "name": "devCreatedTokenCountMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum developer-created token count.", "x-description-cn": "开发者创建代币数量最小值。" }, { "name": "devCreatedTokenCountMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum developer-created token count.", "x-description-cn": "开发者创建代币数量最大值。" }, { "name": "devMigratedTokenCountMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum developer-migrated token count.", "x-description-cn": "开发者迁移代币数量最小值。" }, { "name": "devMigratedTokenCountMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum developer-migrated token count.", "x-description-cn": "开发者迁移代币数量最大值。" }, { "name": "devMigratedTokenPercentMin", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Minimum developer-migrated token percentage. \"5\" means 5%.", "x-description-cn": "开发者迁移代币占比最小值，如 \"5\" 表示 5%。" }, { "name": "devMigratedTokenPercentMax", "in": "query", "required": false, "schema": { "type": "string", "example": "100" }, "description": "Maximum developer-migrated token percentage. \"5\" means 5%.", "x-description-cn": "开发者迁移代币占比最大值，如 \"5\" 表示 5%。" }, { "name": "isDevSoldAll", "in": "query", "required": false, "schema": { "type": "boolean", "example": false }, "description": "When set to true, returns only tokens where the developer has sold all holdings. Not filtered when omitted or false.", "x-description-cn": "设为 true 时，仅返回开发者已全部清仓的代币，不传或设为 false 时不筛选。" }, { "name": "isDevBurned", "in": "query", "required": false, "schema": { "type": "boolean", "example": false }, "description": "When set to true, returns only tokens where the developer has burned tokens. Not filtered when omitted or false.", "x-description-cn": "设为 true 时，仅返回开发者曾销毁代币的项目，不传或设为 false 时不筛选。" }, { "name": "isMint", "in": "query", "required": false, "schema": { "type": "boolean", "example": false, "default": false }, "description": "When set to true, excludes tokens with minting capability. Default false.", "x-description-cn": "设为 true 时，从结果中排除存在可增发功能的代币。默认 false。" }, { "name": "isFreeze", "in": "query", "required": false, "schema": { "type": "boolean", "example": false, "default": false }, "description": "When set to true, excludes tokens with freeze capability. Default false.", "x-description-cn": "设为 true 时，从结果中排除存在可冻结功能的代币。默认 false。" }, { "name": "isHideWashTradingTokens", "in": "query", "required": false, "schema": { "type": "boolean", "example": true, "default": true }, "description": "When set to true, excludes tokens with wash trading behavior. Default true.", "x-description-cn": "设为 true 时，从结果中排除存在刷量行为的代币。默认 true。" }, { "name": "isHideDevWashTradingTokens", "in": "query", "required": false, "schema": { "type": "boolean", "example": true, "default": true }, "description": "When set to true, excludes tokens where the developer has wash trading behavior. Default true.", "x-description-cn": "设为 true 时，从结果中排除开发者存在刷量行为的代币。默认 true。" }, { "name": "isHideInternalWashTradingTokens", "in": "query", "required": false, "schema": { "type": "boolean", "example": true, "default": true }, "description": "When set to true, excludes tokens where insiders have wash trading behavior. Default true.", "x-description-cn": "设为 true 时，从结果中排除内幕交易者存在刷量行为的代币。默认 true。" }, { "name": "pageId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 1, "default": 1 }, "description": "Pagination identifier. Do not pass on the first request; pass the page value from the previous response to get the next page.", "x-description-cn": "分页标识。首次请求时不传，获取下一页时传入上次响应返回的 page 值。" }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 100, "default": 100, "maximum": 100 }, "description": "Page size. Maximum 100. Defaults to 100.", "x-description-cn": "每页返回数量，最大 100，默认 100。" } ], "responses": { "200": { "description": "Hot token list returned successfully.", "x-description-cn": "成功返回热门代币榜单。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "page": { "type": "integer", "format": "int32", "nullable": true, "example": 1, "description": "Current page number. Null when no more data is available.", "x-description-cn": "当前页码，无更多数据时返回 null。" }, "items": { "type": "array", "description": "Hot token list.", "x-description-cn": "代币列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique identifier of the chain.", "x-description-cn": "链唯一标识。" }, "tokenSymbol": { "type": "string", "example": "PEPE", "description": "Token symbol.", "x-description-cn": "代币符号。" }, "tokenLogoUrl": { "type": "string", "nullable": true, "example": "https://static.onchainos.com/tokens/pepe.png", "description": "Token logo URL.", "x-description-cn": "代币 Logo 链接。" }, "tokenContractAddress": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "marketCap": { "type": "string", "example": "5830000.50", "description": "Market cap, denominated in USD.", "x-description-cn": "市值，美元计价。" }, "volume": { "type": "string", "example": "1250000.30", "description": "Trading volume within the specified time, denominated in USD.", "x-description-cn": "指定时间内的交易额，美元计价。" }, "change": { "type": "string", "example": "12.5", "description": "Price change percentage within the specified time. \"-5.23\" means a 5.23% decrease.", "x-description-cn": "指定时间内的价格变动百分比，如 \"-5.23\" 表示下跌 5.23%。" }, "uniqueTraders": { "type": "string", "example": "2341", "description": "Number of unique trading addresses.", "x-description-cn": "独立交易地址数量。" }, "buyTxs": { "type": "string", "example": "1523", "description": "Buy transaction count.", "x-description-cn": "买入交易笔数。" }, "sellTxs": { "type": "string", "example": "987", "description": "Sell transaction count.", "x-description-cn": "卖出交易笔数。" }, "txs": { "type": "string", "example": "2510", "description": "Total transaction count.", "x-description-cn": "总交易笔数。" }, "liquidity": { "type": "string", "example": "680000.00", "description": "Liquidity, denominated in USD.", "x-description-cn": "流动性，美元计价。" }, "price": { "type": "string", "example": "0.00000702", "description": "Token price, denominated in USD.", "x-description-cn": "代币价格，美元计价。" }, "holders": { "type": "string", "example": "45832", "description": "Holder count.", "x-description-cn": "持币地址数量。" }, "inflowUsd": { "type": "string", "example": "125000.50", "description": "Net inflow, denominated in USD. Positive means net inflow, negative means net outflow.", "x-description-cn": "净流入，美元计价。正值为净流入，负值为净流出。" }, "devHoldingPercent": { "type": "string", "example": "5.5", "description": "Developer holding percentage. \"5.23\" means 5.23%.", "x-description-cn": "开发者持仓占比，如 \"5.23\" 表示 5.23%。" }, "bnHolderCount": { "type": "string", "example": "1203", "description": "Number of Binance MPC wallets holding this token.", "x-description-cn": "持有当前代币的 Binance MPC 钱包数。" }, "top10HoldingPercent": { "type": "string", "example": "35.2", "description": "Top 10 addresses holding percentage. \"35.2\" means 35.2%.", "x-description-cn": "前 10 地址持仓占比，如 \"35.2\" 表示 35.2%。" }, "sniperHoldingPercent": { "type": "string", "example": "8.3", "description": "Sniper holding percentage. \"8.3\" means 8.3%.", "x-description-cn": "狙击者持仓占比，如 \"8.3\" 表示 8.3%。" }, "proHoldingPercent": { "type": "string", "example": "12.1", "description": "Professional holder percentage. \"12.1\" means 12.1%.", "x-description-cn": "专业持有者持仓占比，如 \"12.1\" 表示 12.1%。" }, "freshWalletHoldingPercent": { "type": "string", "example": "3.5", "description": "Fresh wallet holding percentage. \"3.5\" means 3.5%.", "x-description-cn": "新地址持仓占比，如 \"3.5\" 表示 3.5%。" }, "smartMoneyHoldingPercent": { "type": "string", "example": "1.52", "description": "Smart money holding percentage. \"1.52\" means 1.52%.", "x-description-cn": "聪明钱持仓占比，如 \"1.52\" 表示 1.52%。" }, "kolHoldingPercent": { "type": "string", "example": "6.5", "description": "KOL holding percentage. \"6.5\" means 6.5%.", "x-description-cn": "KOL 持仓占比，如 \"6.5\" 表示 6.5%。" }, "insiderHoldingPercent": { "type": "string", "example": "2.8", "description": "Insider holding percentage. \"2.8\" means 2.8%.", "x-description-cn": "内部地址持仓占比，如 \"2.8\" 表示 2.8%。" }, "bundlerHoldingPercent": { "type": "string", "example": "6.2", "description": "Bundler holding percentage. \"6.2\" means 6.2%.", "x-description-cn": "捆绑地址持仓占比，如 \"6.2\" 表示 6.2%。" }, "devCreatedTokenCount": { "type": "string", "example": "3", "description": "Developer-created token count.", "x-description-cn": "开发者创建代币数量。" }, "devMigratedTokenCount": { "type": "string", "example": "1", "description": "Developer-migrated token count.", "x-description-cn": "开发者迁移代币数量。" }, "devMigratedTokenPercent": { "type": "string", "example": "33.3", "description": "Developer migrated token percentage. \"33.3\" means 33.3%.", "x-description-cn": "开发者迁移代币占比，如 \"33.3\" 表示 33.3%。" }, "tokenTags": { "type": "array", "description": "Token tags.", "x-description-cn": "代币标签数组。", "items": { "type": "string", "example": "Alpha", "enum": [ "alpha", "tge", "communityRecognized", "devSellAll", "devSell", "devBuy", "smartMoneyBuy", "smartMoneySell", "devRemoveLiquidity", "devAddLiquidity", "devBurnToken", "dexScreenerPaid", "volumeSurge", "volumePlunge", "lowLiquidity", "washTrading", "devWashTrading", "insiderWashTrading" ], "x-enum-descriptions": [ "Alpha", "TGE", "社区认可", "DEV清仓", "DEV减仓", "DEV加仓", "聪明钱加仓", "聪明钱减仓", "DEV减流动性", "DEV加流动性", "DEV烧币", "Dexscreener付费", "交易量骤增", "交易量骤减", "流动性低", "刷量交易", "DEV刷量交易", "内幕交易者刷量交易" ] } } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/token/holder": { "get": { "summary": "Get Holders Ranking", "x-summary-cn": "获取代币持有人排行", "description": "Return the holders ranking list for a token, including holding amount, holding percentage, native-token balance, average buy/sell price, realized PnL, and funding source. Up to 100 records. Pagination is not supported.", "x-description-cn": "返回代币的持币地址排行，包含持币数量、持币占比、主链币余额、买卖均价、已实现盈亏及资金来源信息。最多返回100条记录，不支持分页。", "tags": ["Market API"], "operationId": "getHoldersRanking", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-holders-ranking" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getHoldersRanking.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_holders_ranking.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetHoldersRankingExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933" }, "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, { "name": "tagFilter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 1, "enum": [1, 2, 3, 4, 5, 6] }, "description": "Address tag filter, single selection only. Returns all holder addresses (by holding amount descending) when omitted; returns addresses matching the specified tag when provided. Mapping: 1=KOL, 2=Developer, 3=Smart Money, 4=Insider, 5=Sniper, 6=Bundler.", "x-description-cn": "地址标签筛选，仅支持单选。不传时返回全部持仓地址（按持仓量降序）；传入特定标签时，返回对应标签的持仓地址，映射关系为：1=KOL，2=开发者，3=聪明钱，4=内部交易者，5=狙击手，6=捆绑者。" } ], "responses": { "200": { "description": "Holders ranking returned successfully.", "x-description-cn": "成功返回持有人排行。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Holder list.", "x-description-cn": "持仓地址列表。", "items": { "type": "object", "properties": { "holderWalletAddress": { "type": "string", "example": "0x28c6c06298d514db089934071355e5743bf21d60", "description": "Holder wallet address.", "x-description-cn": "持币地址。" }, "holdAmount": { "type": "string", "example": "18580000", "description": "Current holding amount.", "x-description-cn": "持币数量。" }, "holdingPercent": { "type": "string", "example": "5.23", "description": "Holding percentage. \"5.23\" means 5.23%.", "x-description-cn": "持仓占比，如 \"5.23\" 表示 5.23%。" }, "nativeTokenSymbol": { "type": "string", "example": "ETH", "description": "Native token symbol.", "x-description-cn": "主链币符号。" }, "nativeTokenBalance": { "type": "string", "example": "12.5", "description": "Native token balance of the address.", "x-description-cn": "该地址的主链币余额。" }, "boughtAmount": { "type": "string", "example": "18580000", "description": "Total buy amount.", "x-description-cn": "累计买入数量。" }, "avgBuyPrice": { "type": "string", "example": "0.000105", "description": "Average buy price, denominated in USD.", "x-description-cn": "平均买入价格，美元计价。" }, "soldAmount": { "type": "string", "example": "15000000", "description": "Cumulative sold amount (token units).", "x-description-cn": "累计卖出数量。" }, "avgSellPrice": { "type": "string", "example": "0.000195", "description": "Average sell price, denominated in USD.", "x-description-cn": "平均卖出价格，美元计价。" }, "maxHoldAmount": { "type": "string", "example": "30000000", "description": "Maximum historical holding amount.", "x-description-cn": "历史最大持有量。" }, "lastTradeTime": { "type": "integer", "format": "int64", "example": 1716892020000, "description": "Time of the holder's last trade of this token, Unix millisecond timestamp.", "x-description-cn": "对应地址最后交易该代币的时间，Unix 毫秒时间戳。" }, "realizedPnlUsd": { "type": "string", "example": "1277.84", "description": "Realized PnL, denominated in USD. Positive means profit, negative means loss.", "x-description-cn": "已实现盈亏，美元计价。正值为盈利，负值为亏损。" }, "fundingSource": { "type": "string", "nullable": true, "example": "0x28c6c06298d514db089934071355e5743bf21d60", "description": "Funding source address, i.e., the originator of the first inbound native-token transfer. Null when no inbound transfer is recorded.", "x-description-cn": "资金来源地址，即首笔主链币转入的来源地址，无转入记录时返回 null。" }, "fundingSourceLabel": { "type": "object", "nullable": true, "description": "Funding source label (e.g. exchange tag). Null when unknown.", "x-description-cn": "资金来源标签（如交易所标签），未知时返回 null。", "properties": { "tagName": { "type": "string", "example": "cex", "description": "Tag category name.", "x-description-cn": "标签类别名称。" }, "tagValue": { "type": "string", "example": "Binance", "description": "Tag value.", "x-description-cn": "标签值。" } } }, "fundingSourceHash": { "type": "string", "nullable": true, "example": "0x3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", "description": "Transaction hash of the first inbound native-token transfer.", "x-description-cn": "首笔主链币转入的交易哈希。" }, "fundingSourceTime": { "type": "integer", "format": "int64", "nullable": true, "example": 1714000000000, "description": "Time of the first native token inbound transfer, Unix millisecond timestamp.", "x-description-cn": "首笔主链币转入时间，Unix 毫秒时间戳。" }, "fundingSourceAmount": { "type": "string", "nullable": true, "example": "0.5", "description": "Amount of the first native token inbound transfer. e.g. 0.5 means 0.5 ETH.", "x-description-cn": "首笔主链币转入数量，如 0.5 表示 0.5 ETH。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/token/top-trader": { "get": { "summary": "Get Top Traders", "x-summary-cn": "获取代币盈利地址排行", "description": "Return the top profit-making addresses for a token, ranked by realized PnL descending. Includes holding amount, average buy/sell price, realized PnL, and funding source. Up to 100 records. Pagination is not supported.", "x-description-cn": "返回代币的头部盈利地址，按已实现收益从高到低排序。包含持仓、买卖均价、已实现盈亏及资金来源。最多返回100条记录，不支持分页。", "tags": ["Market API"], "operationId": "getTopTraders", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-top-traders" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getTopTraders.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_top_traders.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetTopTradersExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933" }, "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, { "name": "tagFilter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 1, "enum": [1, 2, 3, 4, 5, 6, 7] }, "description": "Address tag filter, single selection only. Returns all top profit addresses (by realized PnL descending) when omitted; returns addresses matching the specified tag when provided. Mapping: 1=KOL, 2=Developer, 3=Smart Money, 4=Insider, 5=Sniper, 6=Bundler, 7=Whale Holder.", "x-description-cn": "地址标签筛选，仅支持单选。不传时返回全部盈利地址（按已实现收益降序）；传入特定标签时，返回对应标签的头部盈利地址，映射关系为：1=KOL，2=开发者，3=聪明钱，4=内部交易者，5=狙击手，6=捆绑者，7=持币大户。" } ], "responses": { "200": { "description": "Top traders returned successfully.", "x-description-cn": "成功返回盈利地址排行。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Top profit-making address list.", "x-description-cn": "头部盈利地址列表。", "items": { "type": "object", "properties": { "holderWalletAddress": { "type": "string", "example": "0x28c6c06298d514db089934071355e5743bf21d60", "description": "Trader wallet address.", "x-description-cn": "钱包地址。" }, "holdAmount": { "type": "string", "example": "18580000", "description": "Current holding amount.", "x-description-cn": "持币数量。" }, "holdingPercent": { "type": "string", "example": "3.5", "description": "Current holding percentage. \"3.5\" means 3.5%.", "x-description-cn": "持仓占比，如 \"3.5\" 表示 3.5%。" }, "boughtAmount": { "type": "string", "example": "25000000", "description": "Total bought amount (token units).", "x-description-cn": "总买入数量。" }, "avgBuyPrice": { "type": "string", "example": "0.000105", "description": "Average buy price, denominated in USD.", "x-description-cn": "平均买入价格，美元计价。" }, "soldAmount": { "type": "string", "example": "20000000", "description": "Total sold amount (token units).", "x-description-cn": "总卖出数量。" }, "avgSellPrice": { "type": "string", "example": "0.000195", "description": "Average sell price, denominated in USD.", "x-description-cn": "平均卖出价格，美元计价。" }, "maxHoldAmount": { "type": "string", "example": "30000000", "description": "Maximum historical holding amount.", "x-description-cn": "历史最大持有量。" }, "lastTradeTime": { "type": "integer", "format": "int64", "example": 1716892020000, "description": "Time of the holder's last trade of this token, Unix millisecond timestamp.", "x-description-cn": "对应地址最后交易该代币的时间，Unix 毫秒时间戳。" }, "realizedPnlUsd": { "type": "string", "example": "1800.30", "description": "Realized PnL, denominated in USD. Positive means profit, negative means loss.", "x-description-cn": "已实现盈亏，美元计价。正值为盈利，负值为亏损。" }, "fundingSource": { "type": "string", "nullable": true, "example": "0x21a31ee1afc51d94c2efccaa2092ad1028285549", "description": "Funding source address, i.e., the originator of the first inbound native-token transfer. Null when no inbound transfer is recorded.", "x-description-cn": "资金来源地址，即首笔主链币转入的来源地址，无转入记录时返回 null。" }, "fundingSourceLabel": { "type": "object", "nullable": true, "description": "Funding source label (e.g. exchange tag). Null when unknown.", "x-description-cn": "资金来源标签（如交易所标签），未知时返回 null。", "properties": { "tagName": { "type": "string", "example": "cex", "description": "Tag category name.", "x-description-cn": "标签类别名称。" }, "tagValue": { "type": "string", "example": "Binance", "description": "Tag value.", "x-description-cn": "标签值。" } } }, "fundingSourceHash": { "type": "string", "nullable": true, "example": "0x3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", "description": "Transaction hash of the first inbound native-token transfer.", "x-description-cn": "首笔主链币转入的交易哈希。" }, "fundingSourceTime": { "type": "integer", "format": "int64", "nullable": true, "example": 1714000000000, "description": "Time of the first native token inbound transfer, Unix millisecond timestamp.", "x-description-cn": "首笔主链币转入时间，Unix 毫秒时间戳。" }, "fundingSourceAmount": { "type": "string", "nullable": true, "example": "0.5", "description": "Amount of the first native token inbound transfer. e.g. 0.5 means 0.5 ETH.", "x-description-cn": "首笔主链币转入数量，如 0.5 表示 0.5 ETH。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/token/top-liquidity": { "get": { "summary": "Get Top Liquidity Pools", "x-summary-cn": "获取代币流动性池信息", "description": "Return the top liquidity pools for a token, including pool name, protocol, liquidity in USD, pool address, and per-token composition.", "x-description-cn": "返回代币的主要流动性池信息，包含流动性池地址、名称、深度及代币组成。", "tags": ["Market API"], "operationId": "getTopLiquidityPools", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-top-liquidity-pools" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getTopLiquidityPools.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_top_liquidity_pools.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetTopLiquidityPoolsExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933" }, "description": "Token contract address.", "x-description-cn": "代币合约地址。" } ], "responses": { "200": { "description": "Top liquidity pools returned successfully.", "x-description-cn": "成功返回流动性池列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Liquidity pool list.", "x-description-cn": "流动性池列表。", "items": { "type": "object", "properties": { "pool": { "type": "string", "example": "PEPE/WETH", "description": "Pool name, e.g. \"PEPE/WETH\".", "x-description-cn": "资金池名称，如 \"PEPE/WETH\"。" }, "protocolName": { "type": "string", "nullable": true, "example": "Uniswap V3", "description": "DEX protocol name. Null when unknown.", "x-description-cn": "协议名称，未知时返回 null。" }, "protocolLogoUrl": { "type": "string", "nullable": true, "example": "https://static.onchainos.com/protocols/uniswap.png", "description": "Protocol logo link. Null when no logo.", "x-description-cn": "协议 Logo 链接，无 Logo 时返回 null。" }, "liquidityUsd": { "type": "string", "example": "680000.00", "description": "Pool liquidity, denominated in USD.", "x-description-cn": "池子流动性，美元计价。" }, "poolAddress": { "type": "string", "example": "0x11950d141ecb863f01007add7d1a342041227b58", "description": "Pool contract address.", "x-description-cn": "池子合约地址。" }, "liquidityAmount": { "type": "array", "description": "Detailed information for each token in the pool.", "x-description-cn": "流动性池中各代币的详细信息。", "items": { "type": "object", "properties": { "tokenAmount": { "type": "string", "example": "1500000000", "description": "Token amount in the pool.", "x-description-cn": "对应代币的数量。" }, "tokenSymbol": { "type": "string", "example": "PEPE", "description": "Token symbol.", "x-description-cn": "代币符号。" }, "tokenName": { "type": "string", "example": "Pepe", "description": "Token full name.", "x-description-cn": "代币名称。" }, "tokenContractAddress": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "tokenLogoUrl": { "type": "string", "nullable": true, "example": "https://static.onchainos.com/tokens/pepe.png", "description": "Token logo link. Null when no logo.", "x-description-cn": "代币 Logo 链接，无 Logo 时返回 null。" } } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/market/trades": { "get": { "summary": "Get Token Trades", "x-summary-cn": "获取代币交易历史", "description": "Return on-chain trade history for a token. Supports tag filtering and wallet address filtering.", "x-description-cn": "获取代币在链上的交易历史，支持标签与特定地址筛选。", "tags": ["Market API"], "operationId": "getTokenTrades", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/market-api#get-token-trades" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/MarketApi/getTokenTrades.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Market/get_token_trades.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/market/GetTokenTradesExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier.", "x-description-cn": "链唯一标识。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933" }, "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "example": "eyJ0aW1lIjoxNzQ4NjAwMDAwMDAwLCJpZCI6MTIzfQ==" }, "description": "Pagination cursor. Do not pass on the first request; pass the cursor value from the previous response to get the next page.", "x-description-cn": "分页游标。首次查询时不传，获取下一页时传入上次响应返回的 cursor 值。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 100, "default": 100, "minimum": 1, "maximum": 500 }, "description": "Number of results per page, maximum 500, defaults to 100.", "x-description-cn": "每页返回条数，最大 500，默认 100。" }, { "name": "tagFilter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 1, "enum": [1, 2, 3, 4, 5, 6, 7] }, "description": "Address tag filter, single selection only. Returns all trades with pagination when omitted; returns only the latest 100 trades for the specified tag's addresses when provided (cursor and limit are ignored). Mapping: 1=KOL, 2=Developer, 3=Smart Money, 4=Insider, 5=Sniper, 6=Bundler, 7=Whale Holder.", "x-description-cn": "地址标签筛选，仅支持单选。不传时返回全部地址的交易记录（支持分页）；传入特定标签时，仅返回该标签地址的最近 100 条交易记录（cursor 和 limit 不生效），映射关系为：1=KOL，2=开发者，3=聪明钱，4=内部交易者，5=狙击手，6=捆绑者，7=持币大户。" }, { "name": "walletAddressFilter", "in": "query", "required": false, "schema": { "type": "string", "example": "0x28c6c06298d514db089934071355e5743bf21d60" }, "description": "Filter by specific wallet addresses. Separate multiple addresses with commas. Up to 2 addresses.", "x-description-cn": "查询特定地址的交易历史，输入多个地址时，以逗号分隔，最多可输入两个地址。" } ], "responses": { "200": { "description": "Trade history returned successfully.", "x-description-cn": "成功返回交易历史。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "cursor": { "type": "string", "example": "eyJ0aW1lIjoxNzQ4NTk5MDAwMDAwLCJpZCI6Nzh9", "description": "Cursor for the next page. Empty string when no more data.", "x-description-cn": "下一页游标，无更多数据时为空字符串。" }, "trades": { "type": "array", "description": "Trades sorted by trade time (descending).", "x-description-cn": "交易列表，按交易时间倒序排列。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "txHash": { "type": "string", "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890", "description": "On-chain transaction hash.", "x-description-cn": "链上交易哈希。" }, "userAddress": { "type": "string", "example": "0x28c6c06298d514db089934071355e5743bf21d60", "description": "Trader wallet address.", "x-description-cn": "交易发起方钱包地址。" }, "dexName": { "type": "string", "example": "Uniswap V3", "description": "Name of the DEX protocol where the trade was executed.", "x-description-cn": "交易所在的 DEX 协议名称。" }, "type": { "type": "string", "example": "buy", "enum": ["buy", "sell"], "description": "Trade direction relative to the queried token. \"buy\" or \"sell\".", "x-description-cn": "交易方向，相对查询代币而言。\"buy\"=买入，\"sell\"=卖出。" }, "price": { "type": "string", "example": "0.00000702", "description": "Trade price, denominated in USD.", "x-description-cn": "成交价格，美元计价。" }, "volume": { "type": "string", "example": "1500.50", "description": "Trade amount, denominated in USD.", "x-description-cn": "成交金额，美元计价。" }, "time": { "type": "integer", "format": "int64", "example": 1748601600000, "description": "Trade time, Unix millisecond timestamp.", "x-description-cn": "交易时间，Unix 毫秒时间戳。" }, "changedTokenInfo": { "type": "array", "description": "Token details involved in this trade. [0] = queried token; [1] = paired token.", "x-description-cn": "交易涉及的代币信息。[0]=查询代币，[1]=配对代币。", "items": { "type": "object", "properties": { "amount": { "type": "string", "example": "1500000", "description": "Token amount traded.", "x-description-cn": "成交代币数量。" }, "tokenSymbol": { "type": "string", "example": "PEPE", "description": "Token symbol.", "x-description-cn": "代币符号。" }, "tokenContractAddress": { "type": "string", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933", "description": "Token contract address.", "x-description-cn": "代币合约地址。" } } } } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/aggregator/supported/chain": { "get": { "summary": "Get Aggregator Supported Chains", "x-summary-cn": "获取聚合器支持的链", "description": "Return blockchain networks supported by the DEX aggregator. The supported list is dynamically configured server-side and may change over time.\nPass `binanceChainId` to filter to a single chain; omit it to get the full list.", "x-description-cn": "返回 DEX 聚合服务当前支持的所有区块链信息。支持链列表由服务端动态配置，可能随时变更。\n传入 `binanceChainId` 仅返回该链信息；不传则返回全量列表。", "tags": ["Trading API"], "operationId": "getAggregatorSupportedChains", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/trading-api#get-aggregator-supported-chains" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TradingApi/getAggregatorSupportedChains.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Trading/get_aggregator_supported_chains.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/trading/GetAggregatorSupportedChainsExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": false, "schema": { "type": "string", "example": "56" }, "description": "Optional chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana). When set, only that chain is returned.", "x-description-cn": "链唯一标识（可选）。指定时仅返回对应链信息；不传则返回全量列表。" } ], "responses": { "200": { "description": "Supported chains returned successfully.", "x-description-cn": "成功返回支持的链列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0, "description": "Business status code. 0 indicates success; any non-zero value indicates a business error.", "x-description-cn": "业务状态码，0 表示成功，非 0 表示业务错误。" }, "msg": { "type": "string", "example": "success", "description": "Status description message.", "x-description-cn": "状态描述信息。" }, "data": { "type": "array", "description": "List of supported blockchain networks.", "x-description-cn": "支持的区块链网络列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "56", "description": "Unique chain identifier (follows EIP-155 chainId for EVM chains; e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识（EVM 链遵循 EIP-155 chainId）。" }, "name": { "type": "string", "example": "BNB Smart Chain", "description": "Full chain name.", "x-description-cn": "链全称。" }, "shortName": { "type": "string", "example": "BSC", "description": "Short chain name.", "x-description-cn": "链简称。" }, "logoUrl": { "type": "string", "example": "https://static.onchainos.com/chains/bsc.png", "description": "Chain logo image URL.", "x-description-cn": "链 Logo 图片 URL。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000, "description": "Server response timestamp in milliseconds.", "x-description-cn": "服务端响应时间戳（毫秒）。" }, "success": { "type": "boolean", "example": true, "description": "Convenience flag derived from `code == 0`.", "x-description-cn": "由 `code == 0` 派生的便捷布尔值。" } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/aggregator/approve-transaction": { "get": { "summary": "Get ERC-20 Approve Transaction", "x-summary-cn": "获取 ERC-20 代币授权交易数据", "description": "Build the on-chain transaction data needed to approve the DEX router to spend a user's ERC-20 token before a swap. Calldata is encoded per the ERC-20 ABI standard (`approve()` selector + spender + amount).", "x-description-cn": "在执行 DEX 兑换前，生成授权 DEX Router 操作用户 ERC-20 代币的链上交易数据。 Calldata 按 ERC-20 ABI 标准编码（approve 函数选择器 + spender + 授权数量）。", "tags": ["Trading API"], "operationId": "getErc20ApproveTransaction", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/trading-api#get-erc20-approve-transaction" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TradingApi/getErc20ApproveTransaction.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Trading/get_erc20_approve_transaction.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/trading/GetErc20ApproveTransactionExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC).", "x-description-cn": "链唯一标识（如 \"1\"=Ethereum，\"56\"=BSC）。" }, { "name": "tokenContractAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7" }, "description": "ERC-20 token contract address to approve (0x + 40 hex chars).", "x-description-cn": "待授权的 ERC-20 代币合约地址（0x + 40 位 hex）。" }, { "name": "approveAmount", "in": "query", "required": true, "schema": { "type": "string", "example": "1000000" }, "description": "Approval amount in the token's smallest unit (positive integer string). Example \"1000000\" = 1 USDT (decimals=6).", "x-description-cn": "授权数量，含精度的正整数字符串。如授权 1 USDT（精度 6）传 \"1000000\"。" }, { "name": "vendor", "in": "query", "required": false, "schema": { "type": "string", "example": "PcsXRfq" }, "description": "RFQ vendor name. **Required for equity / RWA tokens (Ondo, BStock)**; pass the `vendorName` from the `/quote` response (e.g. `InchFusion`, `CowSwap`, `PcsXRfq`). When provided, the backend returns approve calldata targeting the vendor-specific spender contract (e.g. 1inch Router, PcsX Permit2, CowSwap VaultRelayer) instead of the default DEX router.\n\nFor regular (non-RWA) tokens, this parameter is optional. If omitted, the backend uses the standard DEX router. If a valid RFQ vendor is passed, the backend resolves that vendor's spender — used when buying Ondo/BStock with a stablecoin, where the from-token (e.g. USDT) itself is not an RFQ token but must be approved to the RFQ vendor's router.", "x-description-cn": "RFQ vendor 名称。**权益 / RWA 代币（Ondo、BStock）时必填**，传入 `/quote` 响应中的 `vendorName` （如 `InchFusion`、`CowSwap`、`PcsXRfq`）。指定后，后端返回对应 vendor 合约地址（如 1inch Router、 PcsX Permit2、CowSwap VaultRelayer）的授权 calldata，而非默认 DEX Router。\n\n普通（非 RWA）代币可不传：省略时后端使用标准 DEX Router；若传入合法 RFQ vendor，后端会按该 vendor 解析 spender——用于「用稳定币买入 Ondo/BStock」场景，此时 fromToken（如 USDT）本身不是 RFQ 代币， 但需要 approve 给 RFQ vendor 的 router 才能继续走 RFQ swap 流程。" } ], "responses": { "200": { "description": "Approve transaction data returned successfully.", "x-description-cn": "成功返回授权交易数据。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Approve transaction(s) to submit before the swap.", "x-description-cn": "兑换前需提交的授权交易列表。", "items": { "type": "object", "properties": { "data": { "type": "string", "example": "0x095ea7b3000000000000000000000000c67879f4065d3b9fe1c09ee990b891aa8e3a4c2f0000000000000000000000000000000000000000000000000000000000f4240", "description": "ABI-encoded calldata for the ERC-20 `approve()` call. Selector + padded spender + padded amount.", "x-description-cn": "ABI 编码的 ERC-20 `approve()` calldata。函数选择器 + spender 地址 + 授权数量。" }, "dexContractAddress": { "type": "string", "example": "0xc67879F4065d3B9fe1C09EE990B891Aa8E3a4c2f", "description": "DEX router contract address (the spender in the `approve()` call). Configured per chain.", "x-description-cn": "DEX 合约地址，即 `approve()` 中的 spender。按链动态配置。" }, "gasLimit": { "type": "string", "example": "50000", "description": "Gas limit ceiling for the approve transaction (integer string, gas units).", "x-description-cn": "授权交易的 gas limit 上限（整数字符串，单位 gas）。" }, "gasPrice": { "type": "string", "example": "110000000", "description": "Gas price for the approve transaction (integer string, wei).", "x-description-cn": "授权交易的 gas price（整数字符串，单位 wei）。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/aggregator/quote": { "get": { "summary": "Get Aggregated Quote", "x-summary-cn": "获取聚合交易报价", "description": "Query multiple DEX vendors in parallel and return the priced routes sorted by `toTokenAmount` (descending). Each route carries an independent `quoteId` (TTL ~30s) that the swap endpoint consumes to construct calldata for the chosen route.", "x-description-cn": "向多个 vendor 并发询价，返回按 `toTokenAmount` 降序排列的路由列表。 每条路由携带独立的 `quoteId`（TTL 约 30 秒），swap 接口通过它定位要构造 calldata 的路由。", "tags": ["Trading API"], "operationId": "getAggregatedQuote", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/trading-api#get-aggregated-quote" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TradingApi/getAggregatedQuote.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Trading/get_aggregated_quote.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/trading/GetAggregatedQuoteExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "56" }, "description": "Unique chain identifier (e.g. \"56\"=BSC, \"1\"=Ethereum, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识（如 \"56\"=BSC，\"1\"=Ethereum，\"CT_501\"=Solana）。" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "example": "1000000" }, "description": "Sell-token amount in the token's smallest unit (positive integer string, no decimals). Example \"1000000\" = 1 USDT (decimals=6).", "x-description-cn": "卖出币种数量，含精度的正整数字符串（不允许小数）。如兑换 1 USDT（精度 6）传 \"1000000\"。" }, { "name": "fromTokenAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x55d398326f99059fF775485246999027B3197955" }, "description": "Sell-token contract address. EVM chains require 0x + 40 hex chars; non-EVM chains use the chain's native address format.", "x-description-cn": "卖出币种合约地址。EVM 链格式 `0x + 40 位 hex`；非 EVM 链使用对应链的地址格式。" }, { "name": "toTokenAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d" }, "description": "Buy-token contract address. Must differ from `fromTokenAddress`.", "x-description-cn": "买入币种合约地址，必须与 `fromTokenAddress` 不同。" }, { "name": "userWalletAddress", "in": "query", "required": false, "schema": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "description": "User wallet address. Required when quoting RFQ routes (equity / RWA tokens such as Ondo and BStock). This address is used as the receiver in the RFQ order and must match the wallet that signs `rfq.typedDataToSign` in the subsequent `/swap` call.", "x-description-cn": "用户钱包地址。询价 RFQ 路由（Ondo、BStock 等权益 / RWA 代币）时必填。 该地址将作为 RFQ 订单的接收方，须与后续 `/swap` 中签名 `rfq.typedDataToSign` 的钱包一致。" } ], "responses": { "200": { "description": "Quote routes returned successfully.", "x-description-cn": "成功返回询价路由。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "One route per vendor that returned a valid quote, sorted by `toTokenAmount` descending.", "x-description-cn": "每个返回有效报价的 vendor 对应一条路由，按 `toTokenAmount` 降序排列。", "items": { "type": "object", "properties": { "quoteId": { "type": "string", "example": "a1b2c3d4e5f64a8b9c0d1e2f3a4b5c6d", "description": "Per-route quote identifier (UUID, no dashes). Pass to the swap endpoint to lock in this route.", "x-description-cn": "单条路由的询价 ID（UUID，无连字符）。在 swap 接口中传入以锁定该路由。" }, "vendorName": { "type": "string", "example": "Lifi", "description": "Source vendor display name. Possible values include LiquidMesh, Lifi, 1inch, Pancake, Jupiter.", "x-description-cn": "询价来源 vendor 展示名，可能值：LiquidMesh、Lifi、1inch、Pancake、Jupiter。" }, "binanceChainId": { "type": "string", "example": "56", "description": "Chain identifier echoed from the request.", "x-description-cn": "链唯一标识，回显请求值。" }, "fromTokenAmount": { "type": "string", "example": "1000000", "description": "Sell amount echoed from the request (smallest unit, integer string).", "x-description-cn": "卖出币种数量（最小单位整数字符串）。" }, "toTokenAmount": { "type": "string", "example": "998500000000000000", "description": "Estimated buy-token amount returned by the vendor (smallest unit, integer string).", "x-description-cn": "估算的买入币种数量（最小单位整数字符串）。" }, "tradeFee": { "type": "string", "nullable": true, "example": "0.12", "description": "Estimated network fee for this route in USD. Null when the vendor does not return one.", "x-description-cn": "该路由预估的网络费用（USD 计价）。vendor 未返回时为 null。" }, "estimateGasFee": { "type": "string", "nullable": true, "example": "150000", "description": "Estimated gas in the chain's smallest unit (e.g. wei). May be null on Solana.", "x-description-cn": "预估消耗的 Gas（链最小单位，如 wei）。Solana 链可能为 null。" }, "priceImpactPercent": { "type": "string", "nullable": true, "example": "-0.01", "description": "Estimated price impact percentage. Null when the vendor does not return one.", "x-description-cn": "价格影响百分比。vendor 未返回时为 null。" }, "router": { "type": "string", "example": "0x55d3...--0xbb4C...--0x8AC7...", "description": "Routing path description, addresses joined with \"--\".", "x-description-cn": "兑换路径描述，地址间用 \"--\" 连接。" }, "fromToken": { "type": "object", "description": "Sell-token metadata.", "x-description-cn": "卖出币种信息。", "properties": { "tokenContractAddress": { "type": "string", "example": "0x55d398326f99059fF775485246999027B3197955", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "tokenSymbol": { "type": "string", "example": "USDT", "description": "Token ticker.", "x-description-cn": "代币简称（ticker）。" }, "tokenUnitPrice": { "type": "string", "example": "1.0002", "description": "Token USD price (decimal string).", "x-description-cn": "代币美元单价（十进制字符串）。" }, "decimal": { "type": "string", "example": "18", "description": "Token decimals.", "x-description-cn": "代币精度（小数位数）。" }, "isHoneyPot": { "type": "boolean", "example": false, "description": "Whether the token is a honeypot (buyable but not sellable).", "x-description-cn": "是否为貔貅币（只能买不能卖的蜜罐合约）。" }, "taxRate": { "type": "string", "example": "0", "description": "Token tax rate. Range 0–1; \"0.01\" means 1%.", "x-description-cn": "代币税率，取值范围 0–1，\"0.01\" 表示 1%。" } } }, "toToken": { "type": "object", "description": "Buy-token metadata. Same shape as `fromToken`.", "x-description-cn": "买入币种信息，结构同 `fromToken`。", "properties": { "tokenContractAddress": { "type": "string", "example": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "description": "Token contract address.", "x-description-cn": "代币合约地址。" }, "tokenSymbol": { "type": "string", "example": "BTCB", "description": "Token ticker.", "x-description-cn": "代币简称（ticker）。" }, "tokenUnitPrice": { "type": "string", "example": "67000.5", "description": "Token USD price (decimal string).", "x-description-cn": "代币美元单价。" }, "decimal": { "type": "string", "example": "18", "description": "Token decimals.", "x-description-cn": "代币精度。" }, "isHoneyPot": { "type": "boolean", "example": false, "description": "Whether the token is a honeypot.", "x-description-cn": "是否为貔貅币。" }, "taxRate": { "type": "string", "example": "0", "description": "Token tax rate.", "x-description-cn": "代币税率。" } } }, "dexRouterList": { "type": "array", "description": "Routing path segments. Each segment corresponds to one hop on one DEX protocol; multi-DEX hops are flattened.", "x-description-cn": "询价路径数据集合。每跳 × 每 DEX 展平为一条记录。", "items": { "type": "object", "properties": { "dexProtocol": { "type": "object", "description": "DEX protocol used for this segment.", "x-description-cn": "该路径段使用的 DEX 协议信息。", "properties": { "dexName": { "type": "string", "example": "Uniswap V3", "description": "DEX protocol name.", "x-description-cn": "DEX 协议名称。" }, "percent": { "type": "string", "example": "85.99", "description": "Share of total flow routed through this DEX (2-decimal percentage string).", "x-description-cn": "该 DEX 在整条路径中的流量百分比（2 位小数）。" } } }, "fromToken": { "type": "object", "description": "Segment's sell-token info. Same shape as the top-level `fromToken`.", "x-description-cn": "该路径段的卖出币种信息，结构同顶层 `fromToken`。", "properties": { "tokenContractAddress": { "type": "string", "example": "0x55d398326f99059fF775485246999027B3197955" }, "tokenSymbol": { "type": "string", "example": "USDT" } } }, "fromTokenIndex": { "type": "string", "example": "0", "description": "Sell-token index after global de-duplication (string form).", "x-description-cn": "卖出币种全局去重后的索引（字符串形式）。" }, "toToken": { "type": "object", "description": "Segment's buy-token info.", "x-description-cn": "该路径段的买入币种信息。", "properties": { "tokenContractAddress": { "type": "string", "example": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d" }, "tokenSymbol": { "type": "string", "example": "BTCB" } } }, "toTokenIndex": { "type": "string", "example": "1", "description": "Buy-token index after global de-duplication (string form).", "x-description-cn": "买入币种全局去重后的索引。" } } } }, "executionMode": { "type": "string", "example": "SWAP", "enum": ["SWAP", "RFQ"], "description": "Execution mode for this route. `SWAP` = standard on-chain swap (sign the `tx` object from `/swap` and broadcast). `RFQ` = signed order flow (sign `rfq.typedDataToSign` from `/swap` with EIP-712, submit via `POST /order/submit`, poll `GET /order/{orderId}`). Equity / RWA tokens always return `RFQ`.", "x-description-cn": "该路由的执行模式。`SWAP` = 标准链上兑换（签名 `/swap` 返回的 `tx` 对象后广播）。 `RFQ` = 签名订单流程（对 `/swap` 返回的 `rfq.typedDataToSign` 做 EIP-712 签名， 通过 `POST /order/submit` 提交，轮询 `GET /order/{orderId}`）。 权益 / RWA 代币始终返回 `RFQ`。" }, "approveTarget": { "type": "string", "nullable": true, "example": "0xc67879F4065d3B9fe1C09EE990B891Aa8E3a4c2f", "description": "The spender contract address the backend will encode into the approve calldata for this route. To obtain that calldata, call `/approve-transaction` with `vendor=` (the string name, e.g. `\"PcsXRfq\"`) — the backend resolves the spender address internally from the vendor name. This field is provided for informational purposes only (e.g. to call ERC-20 `approve()` directly without going through `/approve-transaction`). Null when no approval is needed (e.g. native-token swap or already approved).", "x-description-cn": "后端将为该路由编码进授权 calldata 的 spender 合约地址。 如需获取授权 calldata，请调用 `/approve-transaction` 并传入 `vendor=`（vendor 名字字符串，如 `\"PcsXRfq\"`）——后端会根据 vendor 名字 在内部解析出 spender 地址。本字段仅供参考（例如不经 `/approve-transaction` 直接调用 ERC-20 `approve()` 时使用）。无需授权时为 null（如原生代币兑换或已授权）。" }, "isBest": { "type": "boolean", "example": true, "description": "Whether this route has the highest `toTokenAmount` among all routes returned in this response. At most one route per response has `isBest=true`.", "x-description-cn": "该路由是否为本次响应所有路由中 `toTokenAmount` 最高的最优路由。 每次响应至多一条路由的 `isBest` 为 `true`。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/aggregator/swap": { "get": { "summary": "Build Swap Transaction", "x-summary-cn": "执行代币兑换（构造链上交易数据）", "description": "Build the on-chain swap calldata for a previously quoted route. The request is matched against the cached quote by `quoteId` (TTL ~30s); if the entry has expired, `QUOTE_EXPIRED` (40401) is returned, and if the request parameters disagree with the cached quote, `SWAP_QUOTE_MISMATCH` (40462) is returned.", "x-description-cn": "基于先前的询价路由构造链上 swap 交易的 calldata。请求按 `quoteId` 命中 Redis 缓存（TTL 约 30 秒）；缓存过期返回 `QUOTE_EXPIRED`（40401）， 参数与缓存不一致返回 `SWAP_QUOTE_MISMATCH`（40462）。", "tags": ["Trading API"], "operationId": "buildSwapTransaction", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/trading-api#build-swap-transaction" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TradingApi/buildSwapTransaction.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Trading/build_swap_transaction.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/trading/BuildSwapTransactionExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "56" }, "description": "Unique chain identifier (e.g. \"56\"=BSC, \"1\"=Ethereum, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识。" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "example": "1000000" }, "description": "Sell-token amount in the token's smallest unit (positive integer string, no decimals).", "x-description-cn": "卖出币种数量（含精度的正整数字符串）。" }, { "name": "fromTokenAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x55d398326f99059fF775485246999027B3197955" }, "description": "Sell-token contract address.", "x-description-cn": "卖出币种合约地址。" }, { "name": "toTokenAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d" }, "description": "Buy-token contract address.", "x-description-cn": "买入币种合约地址。" }, { "name": "slippagePercent", "in": "query", "required": false, "schema": { "type": "string", "example": "0.5" }, "description": "Maximum slippage tolerance as a percentage string. Required unless `autoSlippage=true`.\n\n**Range by chain:**\n- EVM chains (BSC, Ethereum, Base, etc.): `0` to `100` (inclusive)\n- Solana (`CT_501`): `0` to less than `100` (i.e. `< 100`)\n\n**Range by vendor:**\n- 1inch, PancakeSwap: `0` to `50` (values above 50 are rejected)\n- LiFi, LiquidMesh: `0` to `100` (EVM) or `0` to `< 100` (Solana)\n- Jupiter (Solana): `0` to less than `100`; the value is converted to basis points (`slippageBps = ceil(slippagePercent × 100)`) and applied to the on-chain swap\n\n`\"0.5\"` means 0.5% maximum slippage. When `autoSlippage=true` this field is overridden by the auto-computed value.", "x-description-cn": "最大滑点容忍度（百分比字符串）。`autoSlippage=true` 时可不传，否则必填。\n\n**按链区分范围：**\n- EVM 链（BSC、Ethereum、Base 等）：`0` 到 `100`（含边界）\n- Solana（`CT_501`）：`0` 到小于 `100`（即 `< 100`）\n\n**按 vendor 区分范围：**\n- 1inch、PancakeSwap：`0` 到 `50`（超过 50 会报参数错误）\n- LiFi、LiquidMesh：`0` 到 `100`（EVM）或 `0` 到小于 `100`（Solana）\n- Jupiter（Solana）：`0` 到小于 `100`；传入值会换算为 basis points（`slippageBps = ceil(slippagePercent × 100)`）并作用于链上 swap\n\n`\"0.5\"` 表示最大滑点 0.5%。`autoSlippage=true` 时，此字段会被自动计算的滑点值覆盖。" }, { "name": "userWalletAddress", "in": "query", "required": true, "schema": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "description": "User wallet address (transaction sender).", "x-description-cn": "用户钱包地址。" }, { "name": "quoteId", "in": "query", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f64a8b9c0d1e2f3a4b5c6d" }, "description": "quoteId returned from `/quote` for the route to execute. TTL ~30s; expired entries return `QUOTE_EXPIRED` (40401).", "x-description-cn": "`/quote` 返回的 quoteId，用于定位要执行的路由。TTL 约 30 秒，过期返回 `QUOTE_EXPIRED`（40401）。" }, { "name": "approveTransaction", "in": "query", "required": false, "schema": { "type": "string", "example": "false", "enum": ["true", "false"] }, "description": "When \"true\", `signatureData` includes the spender address and approve calldata so the client can submit it before the swap. Defaults to false.", "x-description-cn": "为 \"true\" 时在 `signatureData` 内返回授权地址及授权 calldata，便于客户端在 swap 前提交授权。默认 false。" }, { "name": "approveAmount", "in": "query", "required": false, "schema": { "type": "string", "example": "1000000" }, "description": "Override approve amount (smallest unit, positive integer string). Defaults to the swap amount.", "x-description-cn": "授权数量（含精度的正整数字符串）。默认与本次交易数量相同。" }, { "name": "gasLimit", "in": "query", "required": false, "schema": { "type": "string", "example": "200000" }, "description": "Gas limit override (positive integer string). EVM only.", "x-description-cn": "Gas limit 上限（正整数字符串）。仅 EVM 链生效。" }, { "name": "gasLevel", "in": "query", "required": false, "schema": { "type": "string", "example": "average", "enum": ["slow", "average", "fast"] }, "description": "Gas price tier. Defaults to \"average\".", "x-description-cn": "Gas 价格档位，默认 \"average\"。" }, { "name": "priceImpactProtectionPercent", "in": "query", "required": false, "schema": { "type": "string", "example": "90" }, "description": "Maximum allowed price impact percentage (0–100). Defaults to 90; set to 100 to disable.", "x-description-cn": "允许的价格影响百分比（0–100）。默认 90，设为 100 时禁用此功能。" }, { "name": "autoSlippage", "in": "query", "required": false, "schema": { "type": "string", "example": "false", "enum": ["true", "false"] }, "description": "When `\"true\"`, slippage is auto-derived from market data and overrides `slippagePercent`. Either `slippagePercent` or `autoSlippage=true` must be provided — omitting both returns a parameter error. Defaults to `\"false\"`.", "x-description-cn": "为 `\"true\"` 时，基于市场数据自动计算滑点并覆盖 `slippagePercent`。 `slippagePercent` 与 `autoSlippage=true` 二选一必填，两者均不传时返回参数错误。 默认 `\"false\"`。" }, { "name": "maxAutoSlippagePercent", "in": "query", "required": false, "schema": { "type": "string", "example": "3" }, "description": "Cap on auto-derived slippage (only applies when `autoSlippage=true`).", "x-description-cn": "自动滑点上限，仅在 `autoSlippage=true` 时生效。" }, { "name": "computeUnitLimit", "in": "query", "required": false, "schema": { "type": "string", "example": "1400000" }, "description": "Solana only — maximum compute units the transaction may consume (analogous to EVM gasLimit). Applies only when `binanceChainId=CT_501`.", "x-description-cn": "Solana 专用 — 限制本次交易最大可消耗的 Compute Units，类比 EVM 的 gasLimit。仅 `binanceChainId=CT_501` 时生效。" }, { "name": "computeUnitPrice", "in": "query", "required": false, "schema": { "type": "string", "example": "1000" }, "description": "Solana only — priority fee per compute unit (micro-lamports), analogous to EVM gasPrice. When omitted, the platform computes a value dynamically. Applies only when `binanceChainId=CT_501`.", "x-description-cn": "Solana 专用 — 每个 Compute Unit 的优先费（micro-lamports），类比 EVM 的 gasPrice。未传入时由平台动态计算。仅 `binanceChainId=CT_501` 时生效。" }, { "name": "tips", "in": "query", "required": false, "schema": { "type": "string", "example": "0.001" }, "description": "Solana only — Jito tips in SOL for MEV protection. Valid range [0.000000001, 2] (minimum 1 lamport). When specified, it is recommended to set `computeUnitPrice=0`. Applies only when `binanceChainId=CT_501`.", "x-description-cn": "Solana 专用 — Jito tips 小费（单位 SOL），用于 MEV 保护。有效范围 [0.000000001, 2]（最小 1 lamport）。指定后建议将 `computeUnitPrice` 设为 0。仅 `binanceChainId=CT_501` 时生效。" } ], "responses": { "200": { "description": "Swap transaction data returned successfully.", "x-description-cn": "成功返回兑换交易数据。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "routerResult": { "type": "object", "description": "Routing result for the chosen vendor.", "x-description-cn": "路由结果，包含本次 swap 使用的 vendor 及报价信息。", "properties": { "binanceChainId": { "type": "string", "example": "56", "description": "Chain identifier echoed from the request.", "x-description-cn": "链唯一标识。" }, "vendorName": { "type": "string", "example": "Lifi", "description": "Vendor that supplied the executed quote (e.g. LiquidMesh, Lifi, 1inch, Pancake, Jupiter).", "x-description-cn": "提供本次 swap 报价的 vendor。" }, "fromTokenAmount": { "type": "string", "example": "1000000", "description": "Sell-token amount (smallest unit, integer string).", "x-description-cn": "卖出币种数量（最小单位整数字符串）。" }, "toTokenAmount": { "type": "string", "example": "998500000000000000", "description": "Estimated buy-token amount (smallest unit, integer string).", "x-description-cn": "估算的买入币种数量。" }, "tradeFee": { "type": "string", "nullable": true, "example": "0.12", "description": "Estimated network fee in USD.", "x-description-cn": "询价路径预估消耗的网络费用（USD 计价）。" }, "estimateGasFee": { "type": "string", "nullable": true, "example": "150000", "description": "Estimated gas in the chain's smallest unit (e.g. wei).", "x-description-cn": "预估消耗的 Gas（链最小单位）。" }, "router": { "type": "string", "example": "0x55d3...--0xbb4C...--0x8AC7...", "description": "Routing path description, addresses joined with \"--\".", "x-description-cn": "兑换路径描述。" }, "priceImpactPercent": { "type": "string", "example": "-0.01", "description": "Price impact percentage. Formula (received_value − sent_value) / sent_value.", "x-description-cn": "价格影响百分比。计算公式：（接收价值 - 支付价值）/ 支付价值。" }, "dexRouterList": { "type": "array", "description": "Routing path segments. Same shape as the `dexRouterList` returned by `/quote`.", "x-description-cn": "询价路径数据集合，结构同 `/quote` 接口的 `dexRouterList`。", "items": { "type": "object", "properties": { "dexProtocol": { "type": "object", "properties": { "dexName": { "type": "string", "example": "Uniswap V3" }, "percent": { "type": "string", "example": "85.99" } } }, "fromToken": { "type": "object", "properties": { "tokenContractAddress": { "type": "string", "example": "0x55d398326f99059fF775485246999027B3197955" }, "tokenSymbol": { "type": "string", "example": "USDT" } } }, "fromTokenIndex": { "type": "string", "example": "0" }, "toToken": { "type": "object", "properties": { "tokenContractAddress": { "type": "string", "example": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d" }, "tokenSymbol": { "type": "string", "example": "BTCB" } } }, "toTokenIndex": { "type": "string", "example": "1" } } } }, "fromToken": { "type": "object", "description": "Sell-token metadata.", "x-description-cn": "卖出币种信息。", "properties": { "tokenContractAddress": { "type": "string", "example": "0x55d398326f99059fF775485246999027B3197955" }, "tokenSymbol": { "type": "string", "example": "USDT" }, "tokenUnitPrice": { "type": "string", "example": "1.0002" }, "decimal": { "type": "string", "example": "18" }, "isHoneyPot": { "type": "boolean", "example": false }, "taxRate": { "type": "string", "example": "0" } } }, "toToken": { "type": "object", "description": "Buy-token metadata.", "x-description-cn": "买入币种信息。", "properties": { "tokenContractAddress": { "type": "string", "example": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d" }, "tokenSymbol": { "type": "string", "example": "BTCB" }, "tokenUnitPrice": { "type": "string", "example": "67000.5" }, "decimal": { "type": "string", "example": "18" }, "isHoneyPot": { "type": "boolean", "example": false }, "taxRate": { "type": "string", "example": "0" } } } } }, "tx": { "type": "object", "description": "On-chain transaction payload to sign and submit.", "x-description-cn": "待签名并提交的链上交易数据。", "properties": { "from": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "User wallet address (transaction sender).", "x-description-cn": "用户钱包地址（交易发起方）。" }, "to": { "type": "string", "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "DEX router contract address (the transaction's `to` field).", "x-description-cn": "DEX Router 合约地址（链上交易的 `to` 字段）。" }, "data": { "type": "string", "example": "0x12aa3caf...", "description": "ABI-encoded calldata.", "x-description-cn": "交易 calldata（ABI 编码的合约调用数据）。" }, "value": { "type": "string", "example": "0", "description": "Native-token amount sent with the transaction (wei). \"0\" for ERC-20 swaps.", "x-description-cn": "交易携带的原生代币数量（wei）。ERC-20 兑换时为 \"0\"。" }, "gas": { "type": "string", "example": "200000", "description": "Gas limit estimate.", "x-description-cn": "Gas Limit 估算值。" }, "gasPrice": { "type": "string", "example": "5000000000", "description": "Gas price (wei).", "x-description-cn": "Gas Price（wei）。" }, "maxPriorityFeePerGas": { "type": "string", "example": "1000000000", "description": "EIP-1559 max priority fee per gas (wei).", "x-description-cn": "EIP-1559 优先费（wei）。" }, "minReceiveAmount": { "type": "string", "example": "993507500000000000", "description": "Minimum buy-token amount the user accepts at the slippage limit (smallest unit, integer string).", "x-description-cn": "目标币种最小收到数量（达到滑点限制时的最小到账数量）。" }, "slippagePercent": { "type": "string", "example": "0.5", "description": "Slippage value applied to this transaction (percentage string).", "x-description-cn": "当前交易使用的滑点值（百分比字符串）。" }, "signatureData": { "type": "array", "description": "Auxiliary signature data. When `approveTransaction=true` was passed, this contains the spender address and approve calldata.", "x-description-cn": "额外签名数据。开启 `approveTransaction` 时，内含授权地址及授权 calldata。", "items": { "type": "string", "example": "0xc67879F4065d3B9fe1C09EE990B891Aa8E3a4c2f" } }, "computeUnitPrice": { "type": "string", "nullable": true, "example": "1000", "description": "Solana priority fee per compute unit (micro-lamports). Echoed when supplied; computed by the platform otherwise. Null on EVM chains.", "x-description-cn": "Solana 优先费（micro-lamports per Compute Unit）。用户传入时回显；未传入时由平台动态计算。EVM 链此字段为 null。" }, "computeUnitLimit": { "type": "string", "nullable": true, "example": "1400000", "description": "Solana compute-unit ceiling. Echoed when supplied; not returned otherwise. Null on EVM chains.", "x-description-cn": "Solana 最大可消耗的 Compute Units。用户传入时回显；未传入时不返回。EVM 链此字段为 null。" } } }, "executionMode": { "type": "string", "example": "SWAP", "enum": ["SWAP", "RFQ"], "description": "Execution mode for this swap. `SWAP` = sign the `tx` object and broadcast to the chain. `RFQ` = sign `rfq.typedDataToSign` with EIP-712 (`eth_signTypedData_v4`), then submit via `POST /order/submit` and poll `GET /order/{orderId}` for settlement status. Equity / RWA tokens always return `RFQ`.", "x-description-cn": "本次 swap 的执行模式。`SWAP` = 签名 `tx` 对象后广播到链上。 `RFQ` = 对 `rfq.typedDataToSign` 做 EIP-712 签名（`eth_signTypedData_v4`）， 通过 `POST /order/submit` 提交，轮询 `GET /order/{orderId}` 获取结算状态。 权益 / RWA 代币始终返回 `RFQ`。" }, "rfq": { "type": "object", "nullable": true, "description": "RFQ order payload. Present only when `executionMode=RFQ`. Contains the EIP-712 typed data to sign, the target vendor, the signing scheme, and (when requested) the approve transaction data.", "x-description-cn": "RFQ 订单载荷，仅 `executionMode=RFQ` 时存在。包含用户须签名的 EIP-712 typed data、 目标 vendor、签名方案，以及（按需返回的）授权交易数据。", "properties": { "vendor": { "type": "string", "example": "PcsXRfq", "enum": ["InchFusion", "CowSwap", "PcsXRfq"], "description": "RFQ vendor that will settle this order on-chain. Pass this as the `vendor` field in `POST /order/submit`.", "x-description-cn": "负责链上撮合的 RFQ vendor，在 `POST /order/submit` 的 `vendor` 字段中传入。" }, "txType": { "type": "string", "example": "EIP712", "enum": ["EIP712", "RAW_TX"], "description": "Transaction type for this RFQ order. Currently always `EIP712` (all three RFQ vendors use EIP-712 typed-data signing); reserved for future signing schemes.", "x-description-cn": "RFQ 交易类型。当前固定为 `EIP712`（三个 RFQ vendor 均走 typed-data 签名）； 保留字段以备未来扩展。" }, "typedDataToSign": { "type": "string", "example": "0x1901...", "description": "EIP-712 typed data payload for `eth_signTypedData_v4`, serialized as a hex string (or JSON-encoded string). Sign with the wallet that matches `userWalletAddress` from `/quote`. Pass the resulting signature as `userSignature` in `POST /order/submit`.", "x-description-cn": "用于 `eth_signTypedData_v4` 的 EIP-712 typed data（hex 字符串或 JSON 字符串）。 使用 `/quote` 时传入的 `userWalletAddress` 对应钱包签名，签名结果通过 `POST /order/submit` 的 `userSignature` 字段提交。" }, "signingScheme": { "type": "string", "example": "EIP712", "description": "Signing scheme required by this vendor. Pass this as `signingScheme` in `POST /order/submit`.", "x-description-cn": "该 vendor 要求的签名方案，在 `POST /order/submit` 的 `signingScheme` 字段中传入。" }, "signatureData": { "type": "array", "example": [ "{\"approveContract\":\"0xc67879F4065d3B9fe1C09EE990B891Aa8E3a4c2f\",\"approveTxCalldata\":\"0x095ea7b3...\"}" ], "description": "Approve transaction data, present only when `approveTransaction=true` was passed and the from-token is an EVM ERC-20. Each element is a JSON string containing `approveContract` (the spender address, resolved per vendor: InchFusion→router, PcsXRfq→Permit2, CowSwap→VaultRelayer) and `approveTxCalldata` (the ERC-20 `approve()` calldata). Empty list otherwise.", "x-description-cn": "授权交易数据（仅 `approveTransaction=true` 且 from 为 EVM ERC-20 时返回；否则为空列表）。 元素为 JSON 字符串，含 `approveContract`（按 vendor 解析的 spender 地址）与 `approveTxCalldata`（ERC-20 `approve()` calldata）。" } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/aggregator/history": { "get": { "summary": "Get Transaction Status", "x-summary-cn": "查询交易状态", "description": "Look up the on-chain status of a DEX swap by `binanceChainId` + `txHash`.\nResponse semantics:\n- Transaction not found: `data` is `null` (not HTTP 404).\n- Transaction failed: `status=failed` with `errorMsg`; aggregator\n business fields (`txType`, `dexRouter`, `fromTokenDetails`,\n `toTokenDetails`) are `null`.\n\n- Transaction succeeded: `status=success` with full token details\n when an aggregator event is present.", "x-description-cn": "根据 `binanceChainId` + `txHash` 查询链上 DEX 兑换交易的详细状态。\n响应说明：\n- 交易不存在：`data` 为 `null`（非 HTTP 404）。\n- 交易失败：`status=failed`，含 `errorMsg`；聚合业务字段（`txType`、`dexRouter`、\n `fromTokenDetails`、`toTokenDetails`）为 `null`。\n\n- 交易成功：`status=success`，有聚合事件时包含完整 token 详情。", "tags": ["Trading API"], "operationId": "getTransactionStatus", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/trading-api#get-transaction-status" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TradingApi/getTransactionStatus.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Trading/get_transaction_status.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/trading/GetTransactionStatusExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "56" }, "description": "Unique chain identifier (e.g. \"56\"=BSC, \"1\"=Ethereum, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识。" }, { "name": "txHash", "in": "query", "required": true, "schema": { "type": "string", "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890" }, "description": "On-chain transaction hash.", "x-description-cn": "链上交易 Hash。" } ], "responses": { "200": { "description": "Transaction details. `data` is null when no record is found.", "x-description-cn": "交易详情。未找到记录时 `data` 为 null。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "nullable": true, "description": "Transaction details. Null when the transaction is not found in any source table.", "x-description-cn": "交易详情。两表均无记录时为 null。", "properties": { "binanceChainId": { "type": "string", "example": "56", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "txHash": { "type": "string", "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890", "description": "Transaction hash.", "x-description-cn": "交易 Hash。" }, "height": { "type": "string", "example": "39812345", "description": "Block height the transaction was included in (decimal string).", "x-description-cn": "交易所在的区块高度（十进制字符串）。" }, "txTime": { "type": "string", "example": "1748601600000", "description": "Transaction timestamp (Unix epoch milliseconds, string form).", "x-description-cn": "交易时间，Unix 时间戳毫秒（字符串形式）。" }, "status": { "type": "string", "example": "success", "description": "Transaction status. Typical values \"success\" or \"failed\".", "x-description-cn": "交易状态，典型值 \"success\" / \"failed\"。" }, "fromAddress": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender address.", "x-description-cn": "发送地址。" }, "toAddress": { "type": "string", "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "Recipient address (typically the DEX router).", "x-description-cn": "接收地址（通常为 DEX Router 合约地址）。" }, "errorMsg": { "type": "string", "nullable": true, "example": "execution reverted: insufficient liquidity", "description": "Error message when `status=failed`; null otherwise.", "x-description-cn": "错误信息，`status=failed` 时有值，否则为 null。" }, "gasLimit": { "type": "string", "nullable": true, "example": "200000", "description": "Gas limit (decimal string). Null on Solana.", "x-description-cn": "Gas 限额（十进制字符串）。Solana 链为 null。" }, "gasUsed": { "type": "string", "nullable": true, "example": "150000", "description": "Gas actually consumed (decimal string, wei). Null on Solana.", "x-description-cn": "Gas 实际消耗量（十进制字符串，单位 wei）。Solana 链为 null。" }, "gasPrice": { "type": "string", "nullable": true, "example": "5000000000", "description": "Gas price (decimal string, wei). Null on Solana.", "x-description-cn": "Gas Price（十进制字符串，单位 wei）。Solana 链为 null。" }, "txFee": { "type": "string", "nullable": true, "example": "750000000000000", "description": "Transaction fee in the chain's native unit. Null on Solana.", "x-description-cn": "手续费（原生代币最小单位）。Solana 链为 null。" }, "priorityFee": { "type": "string", "nullable": true, "example": "1000000000", "description": "EIP-1559 priority fee (wei) on EVM, prioritization fee (lamports) on Solana, null on legacy EVM transactions.", "x-description-cn": "EIP-1559 优先费（wei）；Solana 为 prioritization fee（lamports）；Legacy EVM 交易为 null。" }, "txType": { "type": "string", "nullable": true, "example": "Swap", "description": "Transaction action; currently fixed to \"Swap\" when an aggregator event is present. Null otherwise.", "x-description-cn": "交易行为，有聚合事件时固定 \"Swap\"，否则为 null。" }, "dexRouter": { "type": "string", "nullable": true, "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "DEX router contract address (mirrors `toAddress`). Null when no aggregator event is present.", "x-description-cn": "交互的 DEX Router 合约地址（同 `toAddress`）。无聚合事件时为 null。" }, "fromTokenDetails": { "type": "array", "nullable": true, "description": "Sell-token details. Populated when an aggregator event is present; null otherwise.", "x-description-cn": "输入 token 详情列表。有聚合事件时有值，否则为 null。", "items": { "type": "object", "properties": { "symbol": { "type": "string", "nullable": true, "example": "USDT", "description": "Token ticker. Null when metadata cannot be resolved.", "x-description-cn": "币种简称。元数据查不到时为 null。" }, "amount": { "type": "string", "example": "1500000", "description": "Token amount in the smallest unit (integer string). \"1500000\" = 1.5 USDT (decimals=6).", "x-description-cn": "币种兑换数量（最小单位整数字符串）。" }, "tokenAddress": { "type": "string", "example": "0x55d398326f99059fF775485246999027B3197955", "description": "Token contract address.", "x-description-cn": "币种合约地址。" } } } }, "toTokenDetails": { "type": "array", "nullable": true, "description": "Buy-token details. Populated when an aggregator event is present; null otherwise.", "x-description-cn": "输出 token 详情列表。有聚合事件时有值，否则为 null。", "items": { "type": "object", "properties": { "symbol": { "type": "string", "nullable": true, "example": "BTCB" }, "amount": { "type": "string", "example": "22500000000000", "description": "Token amount in the smallest unit (integer string).", "x-description-cn": "币种兑换数量（最小单位整数字符串）。" }, "tokenAddress": { "type": "string", "example": "0x7130d2A12B9BCbFAe4f2634d864A1Ee1Ce3Ead9c", "description": "Token contract address.", "x-description-cn": "币种合约地址。" } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/aggregator/order/submit": { "post": { "summary": "Submit RFQ Order", "x-summary-cn": "提交 RFQ 订单", "description": "Submit a signed RFQ order to the backend for on-chain settlement via the corresponding vendor relayer. Only used when `executionMode=RFQ` (equity / RWA tokens such as Ondo and BStock).\n\n**Flow**: `GET /quote` → pick an RFQ route → `GET /swap` → sign `rfq.typedDataToSign` with EIP-712 (`eth_signTypedData_v4`) → call this endpoint → poll `GET /order/{orderId}` until `FILLED` or `FAILED`.\n\n**Idempotency**: Submitting with the same `requestId` within 30 minutes returns the original result without re-calling the vendor. Use a new UUID for each distinct order; reuse the same UUID when retrying.", "x-description-cn": "将已签名的 RFQ 订单提交至后端，由后端转发给对应 vendor relayer 完成链上撮合。 仅当 `executionMode=RFQ`（Ondo、BStock 等权益 / RWA 代币）时使用。\n\n**流程**：`GET /quote` → 选择 RFQ 路由 → `GET /swap` → 对 `rfq.typedDataToSign` 做 EIP-712 签名（`eth_signTypedData_v4`）→ 调用本接口 → 轮询 `GET /order/{orderId}` 直到 `FILLED` 或 `FAILED`。\n\n**幂等性**：30 分钟内相同 `requestId` 重复提交直接返回首次结果，不重复调 vendor。 每次新提交生成新 UUID；重试时复用同一 UUID。", "tags": ["Trading API"], "operationId": "submitRfqOrder", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/trading-api#submit-rfq-order" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TradingApi/submitRfqOrder.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Trading/submit_rfq_order.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/trading/SubmitRfqOrderExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["requestId", "userSignature", "vendor", "quoteId"], "properties": { "requestId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000", "description": "Idempotency key (UUID v4). Within 30 minutes, re-submitting with the same `requestId` returns the original result without re-calling the vendor. Generate a new UUID for each new order; reuse the same UUID when retrying the same attempt.", "x-description-cn": "幂等键（UUID v4）。30 分钟内相同 `requestId` 重复提交直接返回首次结果，不重复调 vendor。 每次新提交生成新 UUID；重试同一次提交时复用同一 UUID。" }, "userSignature": { "type": "string", "example": "0x1234abcd...5678ef", "description": "EIP-712 signature of `rfq.typedDataToSign` from the `/swap` response. Must be a hex string with `0x` prefix (132 chars = `0x` + 65 bytes). The signing wallet must match `userWalletAddress` used in `/quote`. The backend automatically corrects Ethereum `v` values `00`/`01` to `1b`/`1c`.", "x-description-cn": "对 `/swap` 响应中 `rfq.typedDataToSign` 做 EIP-712 签名的结果。须为 `0x` 前缀的 hex 字符串 （132 字符 = `0x` + 65 字节）。签名钱包须与 `/quote` 时的 `userWalletAddress` 一致。 后端自动修正 Ethereum `v` 值 `00`/`01` → `1b`/`1c`。" }, "vendor": { "type": "string", "example": "PcsXRfq", "enum": ["InchFusion", "CowSwap", "PcsXRfq"], "description": "RFQ vendor name — must match `rfq.vendor` from the `/swap` response. The backend validates this against `quoteId` to prevent misrouted submissions.", "x-description-cn": "RFQ vendor 名称，须与 `/swap` 响应中 `rfq.vendor` 一致。后端结合 `quoteId` 做强校验，防止错误路由。" }, "quoteId": { "type": "string", "example": "a1b2c3d4e5f64a8b9c0d1e2f3a4b5c6d", "description": "`rfq.orderId` from the `/swap` response. The backend uses this to look up the vendor and chain context required to forward the signed order.", "x-description-cn": "`/swap` 响应中 `rfq.orderId` 的值。后端据此反查 vendor 及链上下文后转发签名订单。" }, "signingScheme": { "type": "string", "example": "EIP712", "description": "Signing scheme from `rfq.signingScheme` in the `/swap` response. Optional — when omitted the backend infers the default per vendor.", "x-description-cn": "`/swap` 响应中 `rfq.signingScheme` 的值。可选，省略时后端按 vendor 推断默认值。" } } } } } }, "responses": { "200": { "description": "RFQ order submitted successfully.", "x-description-cn": "RFQ 订单提交成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Submitted order details.", "x-description-cn": "提交订单结果。", "properties": { "orderId": { "type": "string", "example": "oc-o-abc123def456", "description": "Platform-generated order ID. Use this to poll `GET /order/{orderId}` for the final settlement status.", "x-description-cn": "平台生成的订单 ID，用于轮询 `GET /order/{orderId}` 获取最终结算状态。" }, "status": { "type": "string", "example": "PENDING_VENDOR", "description": "Initial order status after submission. Typical value: `PENDING_VENDOR` (forwarded to vendor, awaiting settlement).", "x-description-cn": "提交后的初始订单状态，通常为 `PENDING_VENDOR`（已转发至 vendor，等待结算）。" }, "createdAt": { "type": "integer", "format": "int64", "example": 1748601600000, "description": "Order creation timestamp (Unix epoch milliseconds).", "x-description-cn": "订单创建时间（Unix 时间戳毫秒）。" } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/aggregator/order/{orderId}": { "get": { "summary": "Get RFQ Order Status", "x-summary-cn": "查询 RFQ 订单状态", "description": "Query the settlement status of an RFQ order by its platform `orderId` (returned by `POST /order/submit`). Poll this endpoint until `status` reaches a terminal state: `FILLED` (settled on-chain) or `FAILED` (settlement failed).", "x-description-cn": "按平台 `orderId`（由 `POST /order/submit` 返回）查询 RFQ 订单的结算状态。 持续轮询直到 `status` 到达终态：`FILLED`（链上已结算）或 `FAILED`（结算失败）。", "tags": ["Trading API"], "operationId": "getRfqOrderStatus", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/trading-api#get-rfq-order-status" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TradingApi/getRfqOrderStatus.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Trading/get_rfq_order_status.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/trading/GetRfqOrderStatusExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "example": "oc-o-abc123def456" }, "description": "Platform order ID returned by `POST /order/submit`.", "x-description-cn": "`POST /order/submit` 返回的平台订单 ID。" } ], "responses": { "200": { "description": "Order status returned successfully.", "x-description-cn": "成功返回订单状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Order status details.", "x-description-cn": "订单状态详情。", "properties": { "orderId": { "type": "string", "example": "oc-o-abc123def456", "description": "Platform order ID.", "x-description-cn": "平台订单 ID。" }, "status": { "type": "string", "example": "FILLED", "description": "Current order status.\n- **Terminal**: `FILLED` (settled on-chain), `FAILED` (settlement failed),\n `EXPIRED` (vendor could not settle before the order deadline), `CANCELLED`\n (cancelled by the user or vendor).\n\n- **Intermediate**: `PENDING_VENDOR` (forwarded to vendor, awaiting settlement),\n `PENDING_ONCHAIN` (vendor has broadcast the on-chain transaction, awaiting\n block confirmation).", "x-description-cn": "当前订单状态。\n\n- **终态**：`FILLED`（链上已结算）、`FAILED`（结算失败）、`EXPIRED`（vendor 在订单截止前未撮合成功）、`CANCELLED`（用户或 vendor 主动取消）。\n- **中间状态**：`PENDING_VENDOR`（已转发给 vendor，等待撮合）、`PENDING_ONCHAIN`（vendor 已发出链上交易，等待区块确认）。" }, "txHash": { "type": "string", "nullable": true, "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890", "description": "On-chain transaction hash. Present only when `status=FILLED`.", "x-description-cn": "链上交易 Hash，仅 `status=FILLED` 时有值。" }, "fromAmount": { "type": "string", "nullable": true, "example": "1000000", "description": "Actual sell-token amount settled (smallest unit, integer string). Present when filled.", "x-description-cn": "实际结算的卖出币种数量（最小单位整数字符串），成交后有值。" }, "toAmount": { "type": "string", "nullable": true, "example": "998500000000000000", "description": "Actual buy-token amount received (smallest unit, integer string). Present when filled.", "x-description-cn": "实际收到的买入币种数量（最小单位整数字符串），成交后有值。" }, "filledAt": { "type": "integer", "format": "int64", "nullable": true, "example": 1748601700000, "description": "Settlement timestamp (Unix epoch milliseconds). Present when filled.", "x-description-cn": "成交时间（Unix 时间戳毫秒），成交后有值。" }, "createdAt": { "type": "integer", "format": "int64", "example": 1748601600000, "description": "Order creation timestamp (Unix epoch milliseconds).", "x-description-cn": "订单创建时间（Unix 时间戳毫秒）。" } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/pre-transaction/supported/chain": { "get": { "summary": "Get Transaction Supported Chains", "x-summary-cn": "获取链上交易支持的链", "description": "Return the blockchain networks supported by the Transaction service for gas estimation, simulation, and broadcasting. The list is dynamically configured server-side and may change over time.", "x-description-cn": "返回 Transaction 服务当前支持的区块链列表（用于 Gas 估算、模拟和广播）。 支持链由服务端动态配置，可能随时变更。", "tags": ["Transaction API"], "operationId": "getTransactionSupportedChains", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/transaction-api#get-transaction-supported-chains" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TransactionApi/getTransactionSupportedChains.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Transaction/get_transaction_supported_chains.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/transaction/GetTransactionSupportedChainsExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "responses": { "200": { "description": "Supported chains returned successfully.", "x-description-cn": "成功返回支持的链列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0, "description": "Business status code. 0 indicates success; any non-zero value indicates a business error.", "x-description-cn": "业务状态码，0 表示成功，非 0 表示业务错误。" }, "msg": { "type": "string", "example": "success", "description": "Status description message.", "x-description-cn": "状态描述信息。" }, "data": { "type": "array", "description": "List of supported blockchain networks.", "x-description-cn": "支持的区块链网络列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier (follows EIP-155 chainId for EVM chains; e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识（EVM 链遵循 EIP-155 chainId；如 \"1\"=Ethereum，\"56\"=BSC，\"CT_501\"=Solana）。" }, "name": { "type": "string", "example": "Ethereum", "description": "Full chain name.", "x-description-cn": "链全称。" }, "shortName": { "type": "string", "example": "ETH", "description": "Short chain name / ticker.", "x-description-cn": "链简称。" }, "logoUrl": { "type": "string", "example": "https://onchainos.bnbstatic.com/image/admin_mgs_image_upload/20250228/b549e557-76ca-4873-88ef-3a107cf2c9fe.png", "description": "Chain logo image URL.", "x-description-cn": "链 Logo 图片 URL。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000, "description": "Server response timestamp in milliseconds.", "x-description-cn": "服务端响应时间戳（毫秒）。" }, "success": { "type": "boolean", "example": true, "description": "Convenience flag derived from `code == 0`.", "x-description-cn": "由 `code == 0` 派生的便捷布尔值。" } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/pre-transaction/gas-price": { "get": { "summary": "Get Gas Price", "x-summary-cn": "获取 Gas 价格", "description": "Query the current network gas price for the specified chain. The response shape varies by chain family:\n- EVM chains return both `evmLegacyGasPrice` (legacy gasPrice) and\n `eip1559GasPrice` (baseFee + priority/max fees) when EIP-1559 is supported.\n- Solana returns `solanaGasPrice` (compute-unit prices and Jito tips).\nFields not applicable to the chain family are returned as `null`.", "x-description-cn": "查询指定链当前的网络 Gas 价格。返回结构因链族而异：\n- EVM 链：同时返回 `evmLegacyGasPrice`（传统 gasPrice）和 `eip1559GasPrice`（baseFee + priority/max fee，链支持 EIP-1559 时）。 - Solana 链：返回 `solanaGasPrice`（compute-unit 价格和 Jito 小费）。\n与当前链族无关的字段为 `null`。", "tags": ["Transaction API"], "operationId": "getGasPrice", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/transaction-api#get-gas-price" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TransactionApi/getGasPrice.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Transaction/get_gas_price.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/transaction/GetGasPriceExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识（如 \"1\"=Ethereum，\"56\"=BSC，\"CT_501\"=Solana）。" } ], "responses": { "200": { "description": "Current gas price for the specified chain.", "x-description-cn": "指定链当前的 Gas 价格。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0, "description": "Business status code. 0 indicates success.", "x-description-cn": "业务状态码，0 表示成功。" }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Gas price details. Populated fields depend on chain family.", "x-description-cn": "Gas 价格详情，填充字段取决于链族。", "properties": { "evmLegacyGasPrice": { "type": "object", "nullable": true, "description": "Legacy EVM gas price tiers (wei, integer string). Null on non-EVM chains.", "x-description-cn": "EVM 传统 gasPrice 三档（wei，整数字符串）。非 EVM 链为 null。", "properties": { "lowGasPrice": { "type": "string", "example": "1000000000", "description": "Slow tier gas price in wei.", "x-description-cn": "慢速档位 gas price（wei）。" }, "mediumGasPrice": { "type": "string", "example": "2000000000", "description": "Average tier gas price in wei.", "x-description-cn": "平均档位 gas price（wei）。" }, "highGasPrice": { "type": "string", "example": "5000000000", "description": "Fast tier gas price in wei.", "x-description-cn": "快速档位 gas price（wei）。" } } }, "eip1559GasPrice": { "type": "object", "nullable": true, "description": "EIP-1559 fee structure (wei, integer strings). Null on chains that don't support EIP-1559 or non-EVM chains.", "x-description-cn": "EIP-1559 费用结构（wei，整数字符串）。不支持 EIP-1559 或非 EVM 链为 null。", "properties": { "baseFee": { "type": "string", "example": "1500000000", "description": "Current block base fee in wei.", "x-description-cn": "当前区块的基础费（wei）。" }, "lowPriorityFee": { "type": "string", "example": "100000000", "description": "Slow tier max priority fee per gas (wei).", "x-description-cn": "慢速档位 max priority fee（wei）。" }, "lowMaxFee": { "type": "string", "example": "1700000000", "description": "Slow tier max fee per gas (wei).", "x-description-cn": "慢速档位 max fee（wei）。" }, "mediumPriorityFee": { "type": "string", "example": "500000000", "description": "Average tier max priority fee per gas (wei).", "x-description-cn": "平均档位 max priority fee（wei）。" }, "mediumMaxFee": { "type": "string", "example": "2200000000", "description": "Average tier max fee per gas (wei).", "x-description-cn": "平均档位 max fee（wei）。" }, "highPriorityFee": { "type": "string", "example": "1000000000", "description": "Fast tier max priority fee per gas (wei).", "x-description-cn": "快速档位 max priority fee（wei）。" }, "highMaxFee": { "type": "string", "example": "3000000000", "description": "Fast tier max fee per gas (wei).", "x-description-cn": "快速档位 max fee（wei）。" } } }, "solanaGasPrice": { "type": "object", "nullable": true, "description": "Solana compute-unit prices and Jito tips. Null on non-Solana chains.", "x-description-cn": "Solana 链 compute-unit 价格与 Jito 小费。非 Solana 链为 null。", "properties": { "lowComputeUnitPrice": { "type": "string", "example": "500", "description": "Slow tier compute-unit price (micro-lamports per compute unit).", "x-description-cn": "慢速档位 compute-unit price（micro-lamports per CU）。" }, "lowJitoTip": { "type": "string", "example": "10000", "description": "Slow tier Jito tip in lamports.", "x-description-cn": "慢速档位 Jito 小费（lamports）。" }, "mediumComputeUnitPrice": { "type": "string", "example": "1000" }, "mediumJitoTip": { "type": "string", "example": "50000" }, "highComputeUnitPrice": { "type": "string", "example": "5000" }, "highJitoTip": { "type": "string", "example": "200000" } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/pre-transaction/gas-limit": { "post": { "summary": "Get Gas Limit", "x-summary-cn": "估算 Gas Limit", "description": "Estimate the gas limit (or compute-unit ceiling on Solana) for an unsigned transaction.\nProvide either `evmTx` for EVM chains or `solTx` for Solana, matching the value of `binanceChainId`.", "x-description-cn": "为未签名交易估算 Gas Limit（Solana 链则为 compute-unit 上限）。 根据 `binanceChainId` 提供 `evmTx`（EVM 链）或 `solTx`（Solana 链）。", "tags": ["Transaction API"], "operationId": "getGasLimit", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/transaction-api#get-gas-limit" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TransactionApi/getGasLimit.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Transaction/get_gas_limit.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/transaction/GetGasLimitExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["binanceChainId"], "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识（如 \"1\"=Ethereum，\"56\"=BSC，\"CT_501\"=Solana）。" }, "evmTx": { "type": "object", "description": "EVM transaction payload. Required when `binanceChainId` belongs to an EVM chain.", "x-description-cn": "EVM 交易体。`binanceChainId` 为 EVM 链时必填。", "required": ["from", "to", "value"], "properties": { "from": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender address.", "x-description-cn": "发起方地址。" }, "to": { "type": "string", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "description": "Destination address (contract or EOA).", "x-description-cn": "接收方地址（合约或外部账户）。" }, "value": { "type": "string", "example": "0", "description": "Native token amount in wei (integer string). Use \"0\" for ERC-20 transfers.", "x-description-cn": "原生代币转账金额（wei，整数字符串）。ERC-20 转账填 \"0\"。" }, "data": { "type": "string", "example": "0xa9059cbb000000000000000000000000d8dA6BF26964aF9D7eEd9e03E53415D37aA960450000000000000000000000000000000000000000000000000000000000f4240", "description": "ABI-encoded calldata (hex). Optional when no contract call is involved.", "x-description-cn": "ABI 编码的 calldata（十六进制）。无合约调用时可省略。" } } }, "solTx": { "type": "object", "description": "Solana transaction payload. Required when `binanceChainId=CT_501`.", "x-description-cn": "Solana 交易体。`binanceChainId=CT_501` 时必填。", "required": ["base64Tx"], "properties": { "base64Tx": { "type": "string", "example": "AQABAxIc...", "description": "Base64-encoded unsigned Solana transaction.", "x-description-cn": "Base64 编码的未签名 Solana 交易。" } } } } } } } }, "responses": { "200": { "description": "Estimated gas limit.", "x-description-cn": "估算的 Gas Limit。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "gasLimit": { "type": "string", "example": "21000", "description": "Estimated gas limit (EVM) or compute-unit ceiling (Solana), as an integer string.", "x-description-cn": "估算的 Gas Limit（EVM）或 compute-unit 上限（Solana），整数字符串。" } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/pre-transaction/simulate": { "post": { "summary": "Simulate Transactions", "x-summary-cn": "模拟交易", "description": "Simulate transaction execution off-chain to predict its outcome before broadcasting. The response includes the predicted execution status, balance changes per affected account/token, and ERC-20 allowance changes (EVM chains).\nProvide either `evmTx` (EVM chains) or `solTx` (Solana) matching `binanceChainId`.", "x-description-cn": "在广播前对交易进行链下模拟，预测执行结果。 响应包含预测的执行状态、各账户/代币余额变化以及 ERC-20 授权变化（EVM 链）。\n根据 `binanceChainId` 提供 `evmTx`（EVM 链）或 `solTx`（Solana 链）。", "tags": ["Transaction API"], "operationId": "simulateTransactions", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/transaction-api#simulate-transactions" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TransactionApi/simulateTransactions.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Transaction/simulate_transactions.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/transaction/SimulateTransactionsExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["binanceChainId"], "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识。" }, "evmTx": { "type": "object", "description": "EVM transaction payload. Required when `binanceChainId` belongs to an EVM chain.", "x-description-cn": "EVM 交易体。`binanceChainId` 为 EVM 链时必填。", "required": ["from", "to", "value"], "properties": { "from": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender address.", "x-description-cn": "发起方地址。" }, "to": { "type": "string", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "description": "Destination address (contract or EOA).", "x-description-cn": "接收方地址。" }, "value": { "type": "string", "example": "0", "description": "Native token amount in wei (integer string).", "x-description-cn": "原生代币转账金额（wei，整数字符串）。" }, "data": { "type": "string", "example": "0xa9059cbb...", "description": "ABI-encoded calldata (hex). Optional.", "x-description-cn": "ABI 编码的 calldata（十六进制），可选。" } } }, "solTx": { "type": "object", "description": "Solana transaction payload. Required when `binanceChainId=CT_501`.", "x-description-cn": "Solana 交易体。`binanceChainId=CT_501` 时必填。", "required": ["base64Tx", "address"], "properties": { "base64Tx": { "type": "string", "example": "AQABAxIc...", "description": "Base64-encoded unsigned Solana transaction.", "x-description-cn": "Base64 编码的未签名 Solana 交易。" }, "address": { "type": "string", "example": "9Wzo3FQbtaJWQ7AsxLNMy5rgPVVQVGcG2v8CpfrChZNd", "description": "Owner / fee-payer Solana address used to attribute balance changes.", "x-description-cn": "用于归属余额变化的 Solana 拥有者 / 付费方地址。" } } } } } } } }, "responses": { "200": { "description": "Simulation result.", "x-description-cn": "模拟结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "SUCCESS", "description": "Predicted execution status.", "x-description-cn": "预测的执行状态。" }, "failReason": { "type": "string", "nullable": true, "example": "execution reverted: ERC20InsufficientBalance", "description": "Failure reason when `status=FAILED`; otherwise null.", "x-description-cn": "当 `status=FAILED` 时返回失败原因，否则为 null。" }, "balanceChanges": { "type": "array", "description": "Predicted balance changes for the simulated transaction.", "x-description-cn": "模拟交易中预测的余额变化。", "items": { "type": "object", "properties": { "contractAddress": { "type": "string", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "description": "Token contract address. Empty / native marker for the chain's native asset.", "x-description-cn": "代币合约地址。原生代币使用空值或链定义的标识。" }, "tokenType": { "type": "string", "example": "ERC20", "description": "Token standard.", "x-description-cn": "代币标准。" }, "change": { "type": "string", "example": "-1000000", "description": "Signed balance delta in the smallest token unit (integer string). Negative for outflows, positive for inflows.", "x-description-cn": "以代币最小单位表示的有符号变化（整数字符串）。负值代表流出，正值代表流入。" }, "owner": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Address whose balance is changing.", "x-description-cn": "发生余额变化的地址。" } } } }, "allowanceChanges": { "type": "array", "description": "Predicted ERC-20 allowance changes (EVM chains only).", "x-description-cn": "预测的 ERC-20 授权变化（仅 EVM 链）。", "items": { "type": "object", "properties": { "tokenAddress": { "type": "string", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "description": "ERC-20 token contract address.", "x-description-cn": "ERC-20 代币合约地址。" }, "owner": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Token owner address.", "x-description-cn": "代币拥有者地址。" }, "spender": { "type": "string", "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "Spender address whose allowance is changing.", "x-description-cn": "授权额度发生变化的 spender 地址。" }, "preAmount": { "type": "string", "example": "0", "description": "Allowance before the transaction (smallest unit, integer string).", "x-description-cn": "交易前的授权额度（最小单位，整数字符串）。" }, "postAmount": { "type": "string", "example": "1000000", "description": "Allowance after the transaction (smallest unit, integer string).", "x-description-cn": "交易后的授权额度（最小单位，整数字符串）。" } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/pre-transaction/broadcast-transaction": { "post": { "summary": "Broadcast Transactions", "x-summary-cn": "广播交易", "description": "Broadcast a client-signed transaction to the chain via the Binance Web3 API relay. Returns the transaction hash and an internal `orderId` you can use to track on-chain status via the post-transaction service.\nOptional MEV protection (EVM chains only) routes the transaction through a private mempool to mitigate front-running and sandwich attacks.", "x-description-cn": "通过 Binance Web3 API 中继将客户端已签名的交易广播到链上。返回 `txHash` 以及内部 `orderId`， 可用于通过 post-transaction 服务跟踪链上状态。\n可选的 MEV 保护（仅 EVM 链）会通过私有 mempool 转发交易，缓解抢跑与三明治攻击。", "tags": ["Transaction API"], "operationId": "broadcastTransactions", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/transaction-api#broadcast-transactions" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TransactionApi/broadcastTransactions.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Transaction/broadcast_transactions.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/transaction/BroadcastTransactionsExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["binanceChainId", "signedTransaction", "address"], "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识。" }, "signedTransaction": { "type": "string", "example": "0xf86c808504a817c80082520894d8da6bf26964af9d7eed9e03e53415d37aa96045880de0b6b3a76400008025a0...", "description": "Client-signed raw transaction. EVM chains use a hex-encoded RLP transaction; Solana uses a base64-encoded signed transaction.", "x-description-cn": "客户端签名后的原始交易。EVM 链为十六进制 RLP 交易；Solana 为 base64 编码的已签名交易。" }, "address": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender wallet address. Used for status attribution and signature verification.", "x-description-cn": "发起方钱包地址，用于状态归属和签名校验。" }, "enableMevProtection": { "type": "boolean", "example": false, "description": "When true, route the transaction through a private mempool for MEV protection.", "x-description-cn": "为 true 时通过私有 mempool 转发以启用 MEV 保护。" } } } } } }, "responses": { "200": { "description": "Transaction submitted successfully.", "x-description-cn": "交易广播成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "orderId": { "type": "string", "example": "1812345678901234567", "description": "Internal order identifier. Use this to query on-chain status via the post-transaction service.", "x-description-cn": "内部订单 ID。可通过 post-transaction 服务查询链上状态。" }, "txHash": { "type": "string", "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890", "description": "On-chain transaction hash.", "x-description-cn": "链上交易哈希。" } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/post-transaction/orders": { "get": { "summary": "Get Broadcast Orders", "x-summary-cn": "查询广播订单", "description": "Look up broadcast orders previously submitted via `/pre-transaction/broadcast-transaction`. Filter by `txStatus` or `orderId`, paginate with `cursor`.", "x-description-cn": "查询通过 `/pre-transaction/broadcast-transaction` 提交的广播订单。 支持按 `txStatus` 或 `orderId` 过滤，并通过 `cursor` 分页。", "tags": ["Transaction API"], "operationId": "getBroadcastOrders", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/transaction-api#get-broadcast-orders" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/TransactionApi/getBroadcastOrders.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Transaction/get_broadcast_orders.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/transaction/GetBroadcastOrdersExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "description": "Sender wallet address whose orders to list.", "x-description-cn": "待查询的发起方钱包地址。" }, { "name": "binanceChainId", "in": "query", "required": true, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识。" }, { "name": "txStatus", "in": "query", "required": false, "schema": { "type": "string", "example": "success" }, "description": "Optional filter on transaction status (server-defined string, e.g. \"pending\", \"success\", \"fail\").", "x-description-cn": "可选的交易状态筛选（服务端定义字符串，如 \"pending\"、\"success\"、\"fail\"）。" }, { "name": "orderId", "in": "query", "required": false, "schema": { "type": "string", "example": "1812345678901234567" }, "description": "Optional filter to fetch a single order by its internal order ID.", "x-description-cn": "可选的内部订单 ID 筛选。" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "example": "eyJ0aW1lIjoxNzQ4NjAwMDAwMDAwLCJpZCI6MTIzfQ==" }, "description": "Pagination cursor returned by the previous page. Omit on the first request.", "x-description-cn": "上次响应返回的分页游标。首次请求不传。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 20, "default": 20 }, "description": "Page size. Defaults to 20.", "x-description-cn": "每页返回数量，默认 20。" } ], "responses": { "200": { "description": "Orders returned successfully.", "x-description-cn": "成功返回订单列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "cursor": { "type": "string", "example": "eyJ0aW1lIjoxNzQ4NTk5MDAwMDAwLCJpZCI6Nzh9", "description": "Cursor for the next page. Empty string when no more pages.", "x-description-cn": "下一页游标。无更多数据时为空字符串。" }, "orders": { "type": "array", "description": "Order list.", "x-description-cn": "订单列表。", "items": { "type": "object", "properties": { "orderId": { "type": "string", "example": "1812345678901234567", "description": "Internal order identifier.", "x-description-cn": "内部订单 ID。" }, "binanceChainId": { "type": "string", "example": "1", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "address": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender wallet address.", "x-description-cn": "发起方钱包地址。" }, "txHash": { "type": "string", "nullable": true, "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890", "description": "On-chain transaction hash. Null while the order is pending.", "x-description-cn": "链上交易 Hash。订单 pending 时可能为 null。" }, "txStatus": { "type": "string", "example": "success", "description": "Transaction status (server-defined string, e.g. \"pending\", \"success\", \"fail\").", "x-description-cn": "交易状态（服务端定义字符串）。" }, "failReason": { "type": "string", "nullable": true, "example": "execution reverted: insufficient liquidity", "description": "Failure reason. Populated when the transaction failed; null otherwise.", "x-description-cn": "失败原因。交易失败时有值，否则为 null。" } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/balance/supported/chain": { "get": { "summary": "Get Wallet Supported Chains", "x-summary-cn": "获取钱包支持的链", "description": "Return blockchain networks for which the Wallet service can return balances. The supported list is dynamically configured server-side and may change over time. Pass `binanceChainId` to filter to a single chain; omit to get the full list.", "x-description-cn": "返回 Wallet 服务能够查询余额的区块链列表。支持链由服务端动态配置，可能随时变更。 传入 `binanceChainId` 仅返回该链信息；不传则返回全量列表。", "tags": ["Wallet API"], "operationId": "getWalletSupportedChains", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/wallet-api#get-wallet-supported-chains" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/WalletApi/getWalletSupportedChains.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Wallet/get_wallet_supported_chains.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/wallet/GetWalletSupportedChainsExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": false, "schema": { "type": "string", "example": "1" }, "description": "Optional chain identifier. When set, only that chain is returned.", "x-description-cn": "可选的链唯一标识。指定时仅返回对应链；不传则返回全量列表。" } ], "responses": { "200": { "description": "Supported chains returned successfully.", "x-description-cn": "成功返回支持的链列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0, "description": "Business status code. 0 indicates success.", "x-description-cn": "业务状态码，0 表示成功。" }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "List of supported blockchain networks.", "x-description-cn": "支持的区块链网络列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier (follows EIP-155 chainId for EVM chains; e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识。" }, "name": { "type": "string", "example": "Ethereum", "description": "Full chain name.", "x-description-cn": "链全称。" }, "shortName": { "type": "string", "example": "ETH", "description": "Short chain name.", "x-description-cn": "链简称。" }, "logoUrl": { "type": "string", "example": "https://onchainos.bnbstatic.com/image/admin_mgs_image_upload/20250228/b549e557-76ca-4873-88ef-3a107cf2c9fe.png", "description": "Chain logo image URL.", "x-description-cn": "链 Logo 图片 URL。" } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/balance/all-token-balances-by-address": { "get": { "summary": "Get All Token Balances by Address", "x-summary-cn": "查询地址全部代币余额", "description": "Return all token balances held by an address across one or more chains, with pagination support. Set `excludeRiskToken=true` to filter out airdrop-risk and honeypot tokens (honeypot detection currently applies only to ETH / BSC / SOL / BASE).", "x-description-cn": "返回地址在一个或多个链上的全部代币余额，支持分页。 将 `excludeRiskToken=true` 可过滤空投风险币与蜜罐币（蜜罐检测当前仅支持 ETH / BSC / SOL / BASE）。", "tags": ["Wallet API"], "operationId": "getAllTokenBalancesByAddress", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/wallet-api#get-all-token-balances-by-address" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/WalletApi/getAllTokenBalancesByAddress.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Wallet/get_all_token_balances_by_address.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/wallet/GetAllTokenBalancesByAddressExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string", "example": "0xed0c6079229e2d407672a117c22b62064f4a4312" }, "description": "Wallet address to query.", "x-description-cn": "待查询的钱包地址。" }, { "name": "chains", "in": "query", "required": false, "schema": { "type": "string", "example": "1,56" }, "description": "Comma-separated list of chain identifiers.", "x-description-cn": "链 ID 列表，英文逗号分隔。" }, { "name": "excludeRiskToken", "in": "query", "required": false, "schema": { "type": "boolean", "example": true }, "description": "Whether to exclude risk-flagged tokens.", "x-description-cn": "是否排除风险代币。" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "example": 1, "default": 1 }, "description": "Page number. Defaults to 1.", "x-description-cn": "页码，默认 1。" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 20, "default": 20, "minimum": 1, "maximum": 100 }, "description": "Page size. Range 1–100. Defaults to 20.", "x-description-cn": "每页条数，范围 1–100，默认 20。" } ], "responses": { "200": { "description": "Token balances returned successfully.", "x-description-cn": "成功返回代币余额。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "One entry per requested chain, each containing a paginated list of token balances.", "x-description-cn": "每个查询链对应一条记录，包含该链上分页后的代币余额列表。", "items": { "type": "object", "properties": { "page": { "type": "integer", "format": "int64", "example": 1, "description": "Current page number.", "x-description-cn": "当前页码。" }, "pageSize": { "type": "integer", "format": "int32", "example": 20, "description": "Page size.", "x-description-cn": "每页条数。" }, "tokenAssets": { "type": "array", "description": "Token balance entries for this chain.", "x-description-cn": "该链上的代币余额列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "description": "Token contract address. Empty string for the chain's native asset.", "x-description-cn": "代币合约地址。原生币为空字符串。" }, "address": { "type": "string", "example": "0xed0c6079229e2d407672a117c22b62064f4a4312", "description": "Wallet address echoed from the request.", "x-description-cn": "钱包地址，回显请求值。" }, "symbol": { "type": "string", "example": "WBTC", "description": "Token ticker.", "x-description-cn": "代币简称（ticker）。" }, "balance": { "type": "string", "example": "329.10055205", "description": "Token amount scaled by decimals (decimal string).", "x-description-cn": "已按精度换算的代币数量。" }, "rawBalance": { "type": "string", "example": "32910055205", "description": "Raw token amount in the smallest unit (integer string). Empty string when the chain doesn't expose a raw value.", "x-description-cn": "未换算精度的原始数量。部分链不支持时返回空字符串。" }, "tokenPrice": { "type": "string", "example": "98847.8", "description": "Token USD price (decimal string).", "x-description-cn": "代币美元单价。" }, "isRiskToken": { "type": "boolean", "example": false, "description": "Whether the token is risk-flagged.", "x-description-cn": "是否为风险代币。" } } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/balance/token-balances-by-address": { "post": { "summary": "Get Token Balances by Address", "x-summary-cn": "查询地址特定代币余额", "description": "Return token balances for a specific list of (chain, contract) pairs. Up to 20 entries per request. Set `excludeRiskToken=\"0\"` to exclude risk-flagged tokens (default), or `\"1\"` to include them.", "x-description-cn": "查询指定 (链, 合约) 列表的代币余额，单次请求最多 20 条。 `excludeRiskToken=\"0\"` 过滤风险代币（默认），`\"1\"` 不过滤。", "tags": ["Wallet API"], "operationId": "getTokenBalancesByAddress", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/wallet-api#get-token-balances-by-address" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/WalletApi/getTokenBalancesByAddress.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Wallet/get_token_balances_by_address.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/wallet/GetTokenBalancesByAddressExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } } ], "requestBody": { "required": true, "description": "Token balance query payload.", "x-description-cn": "代币余额查询请求体。", "content": { "application/json": { "schema": { "type": "object", "required": ["address", "tokenContractAddresses"], "properties": { "address": { "type": "string", "example": "0x50c476a139aab23fdaf9bca12614cdd54a4244e3", "description": "Wallet address to query.", "x-description-cn": "钱包地址。" }, "tokenContractAddresses": { "type": "array", "maxItems": 20, "description": "Tokens to query, up to 20 entries.", "x-description-cn": "要查询的代币列表，最多 20 条。", "items": { "type": "object", "required": ["binanceChainId", "tokenContractAddress"], "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"8453\"=Base).", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "description": "Token contract address. Pass an empty string for the chain's native asset.", "x-description-cn": "代币合约地址。原生币传空字符串 \"\"。" } } } }, "excludeRiskToken": { "type": "string", "example": "0", "default": "0", "enum": ["0", "1"], "description": "Risk-token filter. \"0\"=exclude (default), \"1\"=include. Honeypot detection currently applies only to ETH / BSC / SOL / BASE.", "x-description-cn": "风险代币筛选。\"0\"=过滤（默认），\"1\"=不过滤。蜜罐检测当前仅支持 ETH / BSC / SOL / BASE。" } } } } } }, "responses": { "200": { "description": "Token balances returned successfully.", "x-description-cn": "成功返回代币余额。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "One entry per chain that appears in the request, each containing matched token balances.", "x-description-cn": "每条对应请求中出现过的一个链，包含匹配到的代币余额。", "items": { "type": "object", "properties": { "tokenAssets": { "type": "array", "description": "Matched token balances for this chain.", "x-description-cn": "该链上匹配到的代币余额列表。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "tokenContractAddress": { "type": "string", "example": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "description": "Token contract address. Empty string for the chain's native asset.", "x-description-cn": "代币合约地址。原生币为空字符串。" }, "address": { "type": "string", "example": "0x50c476a139aab23fdaf9bca12614cdd54a4244e3", "description": "Wallet address echoed from the request.", "x-description-cn": "钱包地址，回显请求值。" }, "symbol": { "type": "string", "example": "WBTC", "description": "Token ticker.", "x-description-cn": "代币简称（ticker）。" }, "balance": { "type": "string", "example": "329.10055205", "description": "Token amount scaled by decimals.", "x-description-cn": "已按精度换算的代币数量。" }, "rawBalance": { "type": "string", "example": "32910055205", "description": "Raw token amount in the smallest unit. Empty string when the chain doesn't expose a raw value.", "x-description-cn": "未换算精度的原始数量。部分链不支持时返回空字符串。" }, "tokenPrice": { "type": "string", "example": "98847.8", "description": "Token USD price.", "x-description-cn": "代币美元单价。" }, "isRiskToken": { "type": "boolean", "example": false, "description": "Whether the token is risk-flagged.", "x-description-cn": "是否为风险代币。" } } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "201": { "description": "Created.", "x-description-cn": "已创建。" }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/post-transaction/transactions-by-address": { "get": { "summary": "Get Transactions by Address", "x-summary-cn": "查询地址链上交易历史", "description": "Return on-chain transaction history for a wallet address across one or more chains. Results are limited to the most recent 6 months and sorted by time (descending). Supports cursor pagination, time-range filtering, and token-contract filtering.", "x-description-cn": "返回钱包地址在指定链上的交易历史。仅返回最近 6 个月的记录，按时间倒序排列。 支持游标分页、时间范围筛选和代币合约筛选。", "tags": ["Wallet API"], "operationId": "getTransactionsByAddress", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/wallet-api#get-transactions-by-address" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/WalletApi/getTransactionsByAddress.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Wallet/get_transactions_by_address.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/wallet/GetTransactionsByAddressExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "description": "Wallet address to query.", "x-description-cn": "待查询的钱包地址。" }, { "name": "chains", "in": "query", "required": true, "schema": { "type": "string", "example": "1,56" }, "description": "Comma-separated list of chain identifiers.", "x-description-cn": "链 ID 列表，英文逗号分隔。" }, { "name": "tokenContractAddress", "in": "query", "required": false, "schema": { "type": "string", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7" }, "description": "Optional token contract address filter.", "x-description-cn": "可选的代币合约地址筛选。" }, { "name": "begin", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "example": 1746000000000 }, "description": "Optional start timestamp (Unix milliseconds, inclusive).", "x-description-cn": "起始时间戳（Unix 毫秒，包含）。" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "example": 1748601600000 }, "description": "Optional end timestamp (Unix milliseconds, inclusive).", "x-description-cn": "截止时间戳（Unix 毫秒，包含）。" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "example": "eyJ0aW1lIjoxNzQ4NjAwMDAwMDAwLCJpZCI6MTIzfQ==" }, "description": "Pagination cursor returned by the previous page.", "x-description-cn": "上次响应返回的分页游标。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "example": 20, "default": 20, "minimum": 1, "maximum": 100 }, "description": "Page size. Range 1–100. Defaults to 20.", "x-description-cn": "每页返回数量，范围 1–100，默认 20。" } ], "responses": { "200": { "description": "Transaction history returned successfully.", "x-description-cn": "成功返回交易历史。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "One entry per queried chain. Each entry contains a transaction list and its own pagination cursor.", "x-description-cn": "每条对应一个链。每条包含该链的交易列表与独立分页游标。", "items": { "type": "object", "properties": { "cursor": { "type": "string", "example": "eyJ0aW1lIjoxNzQ4NTk5MDAwMDAwLCJpZCI6Nzh9", "description": "Cursor for the next page within this chain. Empty string when no more pages.", "x-description-cn": "该链下一页游标。无更多数据时为空字符串。" }, "transactionList": { "type": "array", "description": "Transaction history items, sorted by time (descending).", "x-description-cn": "交易历史列表，按时间倒序排列。", "items": { "type": "object", "properties": { "binanceChainId": { "type": "string", "example": "1", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "txHash": { "type": "string", "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890", "description": "On-chain transaction hash.", "x-description-cn": "交易 Hash。" }, "itype": { "type": "string", "example": "0", "enum": ["0", "1", "2"], "description": "Transaction layer type. \"0\"=outer native-token transfer, \"1\"=internal contract native-token transfer, \"2\"=token transfer.", "x-description-cn": "交易层级类型。\"0\"=外层原生币转账，\"1\"=内部合约原生币转账，\"2\"=Token 转账。" }, "methodId": { "type": "string", "nullable": true, "example": "0xa9059cbb", "description": "Contract method ID (function selector). Null for plain native-token transfers.", "x-description-cn": "合约调用函数方法 ID。原生币转账时为 null。" }, "nonce": { "type": "string", "example": "42", "description": "Sender's nonce for this transaction.", "x-description-cn": "发送方地址的 nonce。" }, "txTime": { "type": "string", "example": "1748601600000", "description": "Transaction time (Unix milliseconds, string form).", "x-description-cn": "交易时间（Unix 毫秒，字符串形式）。" }, "from": { "type": "array", "description": "Inputs (sender addresses and amounts).", "x-description-cn": "交易输入（发送方地址与金额）。", "items": { "type": "object", "properties": { "address": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender address. For multi-sig transactions, comma-separated.", "x-description-cn": "发送方地址；多签交易以英文逗号分隔。" }, "amount": { "type": "string", "example": "1500000", "description": "Input amount (smallest unit, decimal string).", "x-description-cn": "输入金额（最小单位，十进制字符串）。" } } } }, "to": { "type": "array", "description": "Outputs (receiver addresses and amounts).", "x-description-cn": "交易输出（接收方地址与金额）。", "items": { "type": "object", "properties": { "address": { "type": "string", "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "Receiver address. For multi-sig transactions, comma-separated.", "x-description-cn": "接收方地址；多签交易以英文逗号分隔。" }, "amount": { "type": "string", "example": "1500000", "description": "Output amount.", "x-description-cn": "输出金额。" } } } }, "tokenContractAddress": { "type": "string", "nullable": true, "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "description": "Token contract address. Null for native-token transfers.", "x-description-cn": "Token 合约地址。原生币转账时为 null。" }, "amount": { "type": "string", "example": "1500000", "description": "Transaction amount in the token's smallest unit.", "x-description-cn": "交易金额（最小单位）。" }, "symbol": { "type": "string", "example": "USDT", "description": "Symbol of the transferred asset.", "x-description-cn": "交易金额对应的币种符号。" }, "txFee": { "type": "string", "example": "0.000125", "description": "Transaction fee (native-token amount, decimal string).", "x-description-cn": "交易手续费（原生代币数量，十进制字符串）。" }, "txStatus": { "type": "string", "example": "success", "enum": ["success", "fail", "pending"], "description": "Transaction status.", "x-description-cn": "交易状态。" }, "hitBlacklist": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the transaction matches a blacklist rule.", "x-description-cn": "是否命中黑名单。" } } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }, "/api/v1/dex/post-transaction/transaction-detail-by-txhash": { "get": { "summary": "Get Transaction Detail by Hash", "x-summary-cn": "根据 Hash 查询交易详情", "description": "Look up the full on-chain transaction detail by `binanceChainId` + `txHash`. Returns one or more entries describing transaction inputs, outputs, internal calls, and token transfers.", "x-description-cn": "根据 `binanceChainId` 与 `txHash` 查询链上交易详情，返回交易的输入、输出、内部调用与代币转账明细。", "tags": ["Wallet API"], "operationId": "getTransactionDetailByHash", "externalDocs": { "url": "https://web3.binance.com/en/dev-docs/catalog/web3-wallet/api/rest-api/wallet-api#get-transaction-detail-by-hash" }, "x-connectors-examples": { "ts": "https://raw.githubusercontent.com/binance/binance-web3-connector-js/master/clients/web3-wallet/examples/rest-api/WalletApi/getTransactionDetailByHash.ts", "python": "https://raw.githubusercontent.com/binance/binance-web3-connector-python/master/clients/web3-wallet/examples/rest_api/Wallet/get_transaction_detail_by_hash.py", "java": "https://raw.githubusercontent.com/binance/binance-web3-connector-java/master/examples/web3-wallet/src/main/java/com/binance/connector/client/web3_wallet/rest/wallet/GetTransactionDetailByHashExample.java" }, "x-signed": true, "parameters": [ { "name": "X-OC-APIKEY", "in": "header", "required": true, "description": "API Key issued by Binance Web3 API for authentication.", "x-description-cn": "Binance Web3 API 颁发的用于鉴权的 API Key。", "schema": { "type": "string", "example": "your-api-key-here" } }, { "name": "X-OC-TIMESTAMP", "in": "header", "required": true, "description": "Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z.", "x-description-cn": "当前 UTC 时间，ISO 8601 格式，精确到毫秒，例如 2026-05-11T10:08:57.715Z。", "schema": { "type": "string", "example": "2026-05-11T10:08:57.715Z" } }, { "name": "X-OC-SIGN", "in": "header", "required": true, "description": "Request signature (Base64-encoded).", "x-description-cn": "请求签名（Base64 编码）。", "schema": { "type": "string", "example": "Base64EncodedSignature==" } }, { "name": "X-OC-RECV-WINDOW", "in": "header", "required": false, "description": "Allowed time deviation in milliseconds (default: 5000, max: 60000).", "x-description-cn": "允许的时间偏差（毫秒），默认值 5000，最大值 60000。", "schema": { "type": "integer", "format": "int64", "example": 5000 } }, { "name": "X-OC-NONCE", "in": "header", "required": false, "description": "Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted.", "x-description-cn": "唯一请求标识符，用于防重放攻击；省略时使用 X-OC-SIGN 代替。", "schema": { "type": "string", "example": "unique-nonce-string" } }, { "name": "binanceChainId", "in": "query", "required": false, "schema": { "type": "string", "example": "1" }, "description": "Unique chain identifier (e.g. \"1\"=Ethereum, \"56\"=BSC, \"CT_501\"=Solana).", "x-description-cn": "链唯一标识。" }, { "name": "txHash", "in": "query", "required": false, "schema": { "type": "string", "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890" }, "description": "On-chain transaction hash.", "x-description-cn": "链上交易 Hash。" }, { "name": "itype", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Transaction-type filter (UTXO chains). Reserved — currently has no effect. Values: \"0\"=outer native-token, \"1\"=internal contract native-token, \"2\"=token transfer.", "x-description-cn": "交易类型筛选（部分 UTXO 链）。保留参数，当前暂不生效。取值：\"0\"=外层原生币，\"1\"=内部合约原生币，\"2\"=Token 转账。" } ], "responses": { "200": { "description": "Transaction details returned successfully.", "x-description-cn": "成功返回交易详情。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "Transaction detail entries. May be empty when the transaction is not found.", "x-description-cn": "交易详情列表。未找到时为空列表。", "items": { "type": "object", "properties": { "chainIndex": { "type": "string", "example": "1", "description": "Chain identifier.", "x-description-cn": "链唯一标识。" }, "height": { "type": "string", "example": "39812345", "description": "Block height (decimal string).", "x-description-cn": "交易所在的区块高度。" }, "txTime": { "type": "string", "example": "1748601600000", "description": "Transaction time (Unix milliseconds, string form).", "x-description-cn": "交易时间（Unix 毫秒，字符串形式）。" }, "txhash": { "type": "string", "example": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890", "description": "On-chain transaction hash.", "x-description-cn": "交易 Hash。" }, "txStatus": { "type": "string", "example": "success", "enum": ["success", "fail", "pending"], "description": "Transaction status. One of: \"success\", \"fail\", \"pending\".", "x-description-cn": "交易状态，取值为 \"success\"、\"fail\"、\"pending\" 之一。" }, "gasLimit": { "type": "string", "nullable": true, "example": "200000", "description": "Gas limit (decimal string).", "x-description-cn": "Gas 上限（十进制字符串）。" }, "gasUsed": { "type": "string", "nullable": true, "example": "150000", "description": "Gas actually consumed.", "x-description-cn": "已消耗 Gas。" }, "gasPrice": { "type": "string", "nullable": true, "example": "5000000000", "description": "Gas price (wei, decimal string).", "x-description-cn": "Gas 价格（wei，十进制字符串）。" }, "txFee": { "type": "string", "example": "0.000750", "description": "Transaction fee in the chain's native token.", "x-description-cn": "交易手续费。" }, "nonce": { "type": "string", "example": "42", "description": "Sender nonce.", "x-description-cn": "Nonce。" }, "amount": { "type": "string", "example": "1500000", "description": "Transaction amount.", "x-description-cn": "交易金额。" }, "symbol": { "type": "string", "example": "USDT", "description": "Symbol of the transferred asset.", "x-description-cn": "交易金额对应的币种符号。" }, "methodId": { "type": "string", "nullable": true, "example": "0xa9059cbb", "description": "Contract method ID (function selector). Null for plain native-token transfers.", "x-description-cn": "合约调用函数方法 ID。原生币转账时为 null。" }, "l1OriginHash": { "type": "string", "nullable": true, "example": "0xdef456...", "description": "L1 origin transaction hash for rollup / L2 transactions; null otherwise.", "x-description-cn": "L1 执行交易哈希（Rollup / L2 场景）。其他情况下为 null。" }, "fromDetails": { "type": "array", "description": "Transaction inputs (sender details).", "x-description-cn": "交易输入详情。", "items": { "type": "object", "properties": { "address": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender / input address.", "x-description-cn": "发送方 / 输入地址。" }, "vinIndex": { "type": "string", "nullable": true, "example": "0", "description": "Current transaction input index (UTXO chains).", "x-description-cn": "当前交易输入索引（UTXO 链）。" }, "preVoutIndex": { "type": "string", "nullable": true, "example": "1", "description": "Linked previous output index (UTXO chains).", "x-description-cn": "关联的前一笔输出索引（UTXO 链）。" }, "txHash": { "type": "string", "nullable": true, "example": "0xpreabc...", "description": "Previous transaction hash (UTXO chains, locates the input UTXO together with `preVoutIndex`).", "x-description-cn": "前一笔交易哈希（UTXO 链与 `preVoutIndex` 共同定位输入 UTXO）。" }, "isContract": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the sender address is a contract.", "x-description-cn": "发送方地址是否为合约地址。" }, "amount": { "type": "string", "example": "1500000", "description": "Input amount.", "x-description-cn": "交易金额。" } } } }, "toDetails": { "type": "array", "description": "Transaction outputs (receiver details).", "x-description-cn": "交易输出详情。", "items": { "type": "object", "properties": { "address": { "type": "string", "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "Receiver / output address.", "x-description-cn": "接收方 / 输出地址。" }, "voutIndex": { "type": "string", "nullable": true, "example": "0", "description": "Output index (UTXO chains).", "x-description-cn": "输出索引（UTXO 链）。" }, "isContract": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the receiver address is a contract.", "x-description-cn": "接收方地址是否为合约地址。" }, "amount": { "type": "string", "example": "1500000", "description": "Output amount.", "x-description-cn": "交易金额。" } } } }, "internalTransactionDetails": { "type": "array", "description": "Internal transaction details.", "x-description-cn": "内部交易详情。", "items": { "type": "object", "properties": { "from": { "type": "string", "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "Sender address.", "x-description-cn": "发送方地址。" }, "to": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Receiver address.", "x-description-cn": "接收方地址。" }, "isFromContract": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the sender is a contract.", "x-description-cn": "发送方是否为合约地址。" }, "isToContract": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the receiver is a contract.", "x-description-cn": "接收方是否为合约地址。" }, "amount": { "type": "string", "example": "100000", "description": "Internal call amount.", "x-description-cn": "交易金额。" }, "txStatus": { "type": "string", "example": "success", "description": "Internal call status.", "x-description-cn": "内部调用状态。" } } } }, "tokenTransferDetails": { "type": "array", "description": "Token transfer details emitted by this transaction.", "x-description-cn": "Token 转账详情。", "items": { "type": "object", "properties": { "from": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "description": "Sender address.", "x-description-cn": "发送方地址。" }, "to": { "type": "string", "example": "0x1111111254EEB25477B68fb85Ed929f73A960582", "description": "Receiver address.", "x-description-cn": "接收方地址。" }, "isFromContract": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the sender is a contract.", "x-description-cn": "发送方是否为合约地址。" }, "isToContract": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the receiver is a contract.", "x-description-cn": "接收方是否为合约地址。" }, "tokenContractAddress": { "type": "string", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "description": "Token contract address.", "x-description-cn": "Token 合约地址。" }, "symbol": { "type": "string", "example": "USDT", "description": "Token ticker.", "x-description-cn": "Token 符号。" }, "amount": { "type": "string", "example": "1500000", "description": "Transfer amount (smallest unit, decimal string).", "x-description-cn": "转账金额（最小单位，十进制字符串）。" } } } } } } }, "timestamp": { "type": "integer", "format": "int64", "example": 1748601600000 }, "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "403": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "404": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } } }, "components": { "responses": { "Created": { "description": "Created.", "x-description-cn": "已创建。" }, "Unauthorized": { "description": "Unauthorized. The request is missing or contains an invalid API key.", "x-description-cn": "未授权。请求缺少 API Key 或包含无效的 API Key。" }, "Forbidden": { "description": "Forbidden. The API key does not have permission to access this endpoint.", "x-description-cn": "禁止访问。该 API Key 没有访问此接口的权限。" }, "NotFound": { "description": "Not Found. The requested resource or endpoint does not exist.", "x-description-cn": "未找到。请求的资源或接口不存在。" } } } }