# @binance/derivatives-trading-usds-futures 中文文档 规范地址：https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/ 版本：39\.0\.2 npm 元数据更新时间：2026-10-23T08:07:57.258Z 中文译文更新时间：2026-11-08T02:59:38.326Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40binance/derivatives-trading-usds-futures 原文对照：https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：4.8 MB，10 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：4 个 - 首次发布：2025-03-24T04:59:36.365Z - 最新版本发布：2026-10-23T08:07:56.847Z - 近 30 天下载量：7757（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：74（近 12 个月 49 个） ## 中文简介 官方 Binance 衍生交易(COIN-M期货) Connector - 一个轻量级库,为 Binance 的 COINN-M期货 REST API, WebSocket API 和 WebSocket Streams 提供了方便的接口. ## 安装 ```sh npm install @binance/derivatives-trading-usds-futures ``` 也可以使用：`pnpm add @binance/derivatives-trading-usds-futures`、`yarn add @binance/derivatives-trading-usds-futures`、`bun add @binance/derivatives-trading-usds-futures` ## README # Binance JavaScript 衍生工具交易(USDS-M期货)连接器 [![Open Issues](https://img.shields.io/github/issues/binance/binance-connector-js)](https://github.com/binance/binance-connector-js/issues) [![Code Style: Prettier](https://img.shields.io/badge/code%20style-prettier-ff69b4)](https://prettier.io/) [![npm version](https://badge.fury.io/js/@binance%2Fderivatives-trading-usds-futures.svg)](https://badge.fury.io/js/@binance%2Fderivatives-trading-usds-futures) [![npm Downloads](https://img.shields.io/npm/dm/@binance/derivatives-trading-usds-futures.svg)](https://www.npmjs.com/package/@binance/derivatives-trading-usds-futures) ![Node.js Version](https://img.shields.io/badge/Node.js-%3E=22.12.0-brightgreen) [![Socket Badge](https://socket.dev/api/badge/npm/package/@binance/derivatives-trading-usds-futures)](https://socket.dev/npm/package/@binance/derivatives-trading-usds-futures) [![Docs](https://img.shields.io/badge/docs-online-blue?style=flat-square)](https://binance.github.io/binance-connector-js/modules/_binance_derivatives-trading-usds-futures.html) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 这是Binance Derivatives Trading USDS-M期货API的客户端库,使开发者能够与Binance的API在程序上互动,以适应他们的衍生交易需要,通过三个不同的端点: - [(原始内容存档于2013-10-12) (英语). REST API](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/src/rest-api/rest-api.ts) - [Websocket API 软件](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/src/websocket-api/websocket-api-connection.ts) - [网页串流](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/src/websocket-streams/websocket-streams-connection.ts) ## 目录 - [支持的特性](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-supported-features) - [安装](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-installation) - [文档](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-documentation) - [REST APIs 软件](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-rest-apis) - [网络锁定 API](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-websocket-apis) - [网页流](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-websocket-streams) - [测试](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-testing) - [移徙指南](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-migration-guide) - [捐款](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-contributing) - [许可证](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/#readme-licence) ## 支持的特性 - REST API 结束点 : - `/fapi/*` - WebSocket Endpoints:实时数据流与请求响应通信. - 包括测试案例和快速上船的例子. ## 安装 要使用此库, 请确保您的环境正在运行节点. js 版本 **22.12.0 国家** 或后会. 如果你在用的话 `nvm` (节点版本管理器),您可以设置正确的版本如下: ```bash nvm install 22.12.0 nvm use 22.12.0 ``` 然后使用 `npm`数字 : ```bash npm install @binance/derivatives-trading-usds-futures ``` ## 文档 关于详细情况,请参看 [Binance API 文档](https://developers.binance.com/docs/derivatives/usds-margined-futures/general-info)。 。 。 . ### REST APIs 软件 所有 REST API 端点都可通过 [`rest-api`](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/src/rest-api/rest-api.ts) 模块。 注意一些端点需要使用您的 Binance API 证书进行认证 . ```typescript import { DerivativesTradingUsdsFutures } from '@binance/derivatives-trading-usds-futures'; const configurationRestAPI = { apiKey: 'your-api-key', apiSecret: 'your-api-secret', }; const client = new DerivativesTradingUsdsFutures({ configurationRestAPI }); client.restAPI .exchangeInformation() .then((res) => res.data()) .then((data) => console.log(data)) .catch((err) => console.error(err)); ``` 更多实例可见于 [`examples/rest-api`](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/examples/rest-api/) 文件夹. #### 配置选项 REST API支持以下高级配置选项: - `timeout`: 请求超时以毫秒计( 默认: 1000 ms) . - `proxy`: 代理配置 : - `host`: 代理服务器主机名. - `port`: 代理服务器端口. - `protocol`: 代理协议(https或https). - `auth`: 代理认证证书: - `username`: 代理用户名. - `password`: 代理密码. - `keepAlive`: 启用 HTTP 保留状态( 默认: 真) . - `compression`: 启用响应压缩( 默认: true). - `retries`: 对失败的请求进行重试的次数( 默认: 3) . - `backoff`: 重试之间以毫秒计的延迟( 默认值: 1000 ms) . - `httpsAgent`:用于高级TLS配置的自定义HTTPS代理. - `privateKey`:RSA或ED25519 用于认证的私人密钥. - `privateKeyPassphrase`:私人密钥的密码句,如果加密的话. ##### 超时 您可以为请求配置超时, 以毫秒计 。 如果请求超过指定的超时,将中止。 见 [超时示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/timeout.md) 供详细使用. ##### 代理服务器 REST API支持HTTP/HTTPS代理配置. 见 [代理实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/proxy.md) 供详细使用. ##### 保留-生活 为持续连接启用 HTTP 保留状态 。 见 [保持生命实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/keepAlive.md) 供详细使用. ##### 压缩 启用或禁用响应压缩 。 见 [压缩示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/compression.md) 供详细使用. ##### 检索 配置重试尝试和延迟的次数, 在失败请求的重试之间以毫秒计 。 见 [重试示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/retries.md) 供详细使用. ##### HTTPS 代理服务器 自定义高级 TLS 配置的 HTTPS 代理 。 见 [HTTPS (韩语) 代理实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/httpsAgent.md) 供详细使用. ##### 基于密钥对等认证 REST API支持基于密钥的对等认证,用于安全通信. 你用得着 `RSA` 或者说 `ED25519` 用于签名请求的密钥。 见 [基于密钥对等认证示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/key-pair-authentication.md) 供详细使用. ##### 证书剪接 为了增强安全性,您可以使用证书标记 `httpsAgent` 选项。 这确保了客户端只使用特定证书与服务器进行通信. 见 [证书剪接示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/certificate-pinning.md) 供详细使用. #### 处理错误 REST API 提供了详细的出错类型来帮助您有效处理问题 : - `ConnectorClientError`: 一般客户端出错. - `RequiredError`: 缺少所需参数时抛出. - `UnauthorizedError`: 显示缺少或无效的认证证书. - `ForbiddenError`: 禁止获取所请求的资源. - `TooManyRequestsError`: 超过费率限额. - `RateLimitBanError`:IP地址被禁,因为超过费率限制. - `ServerError`: 内部服务器出错. - `NetworkError`: 网络连接问题. - `NotFoundError`: 资源未找到 . - `BadRequestError`: 无效的请求. 见 [处理错误实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/rest-api/error-handling.md) 供详细使用. #### 测试网 为了测试目的, `/fapi/*` 结束点可用于 [期货测试网](https://testnet.binancefuture.com/)更新 `basePath` 在配置中: ```typescript import { DerivativesTradingUsdsFutures, DERIVATIVES_TRADING_USDS_FUTURES_REST_API_TESTNET_URL } from '@binance/derivatives-trading-usds-futures'; const configurationRestAPI = { apiKey: 'your-api-key', apiSecret: 'your-api-secret', basePath: DERIVATIVES_TRADING_USDS_FUTURES_REST_API_TESTNET_URL, }; const client = new DerivativesTradingUsdsFutures({ configurationRestAPI }); ``` 若为 `basePath` 未提供,默认为 `https://fapi.binance.com`。 。 。 . ### 网络锁定 API WebSocket API为市场数据和交易行动提供请求-响应通信. 使用 [`websocket-api`](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/src/websocket-api/websocket-api.ts) 模块与这些端点交互. ```typescript import { DerivativesTradingUsdsFutures } from '@binance/derivatives-trading-usds-futures'; const configurationWebsocketAPI = { apiKey: 'your-api-key', apiSecret: 'your-api-secret', }; const client = new DerivativesTradingUsdsFutures({ configurationWebsocketAPI }); client.websocketAPI .connect() .then((connection) => connection.positionInformation()) .then((res) => console.log(res.data)) .catch((err) => console.error(err)); ``` 更多实例可见于 [`examples/websocket-api`](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/examples/websocket-api/) 文件夹. #### 配置选项 WebSocket API支持以下高级配置选项: - `timeout`: 设置 WebSocket 请求的超时( 默认为 5000 ms) . - `reconnectDelay`: 指定重联尝试之间的延迟( 默认: 5000 ms) . - `compression`: 启用或禁用 WebSocket 信件的压缩(默认:为真). - `agent`: 自定义高级配置的 WebSocket代理. - `mode`: 选择 `single` 财务报告和审定财务报表 `pool` 连接模式. - `single`:一个单一的WebSocket连接. - `pool`:一个WebSocket连接的集合. - `poolSize`:在池模式下定义WebSocket连接数. - `privateKey`:RSA或ED25519 用于认证的私人密钥. - `privateKeyPassphrase`:私人密钥的密码句,如果加密的话. ##### 超时 设置以毫秒计的 WebSocket API 请求的超时 。 见 [超时示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-api/timeout.md) 供详细使用. ##### 重接延迟 指定WebSocket重联尝试之间的延迟, 以毫秒计 。 见 [重新连接延迟实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-api/reconnect-delay.md) 供详细使用. ##### 压缩 启用或禁用 WebSocket 信件的压缩 。 见 [压缩示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-api/compression.md) 供详细使用. ##### WebSocket 代理服务器 自定义高级配置的代理 。 见 [WebSocket 代理实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-api/agent.md) 供详细使用. ##### 连接模式 选择 `single` 财务报告和审定财务报表 `pool` webSocket 连接的连接模式 。 这个 `single` 模式使用单一的 WebSocket 连接,而 `pool` 模式使用WebSocket连接的集合。 见 [连接模式示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-api/connection-mode.md) 供详细使用. ##### 基于密钥对等认证 使用RSA或ED25519私人密钥进行WebSocket API认证. 见 [密钥对等认证示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-api/key-pair-authentication.md) 供详细使用. ##### 证书剪接 为了增强安全性,您可以使用证书标记 `agent` 选项。 这确保了客户端只使用特定证书与服务器进行通信. 见 [证书剪接示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-api/certificate-pinning.md) 供详细使用. #### 测试网 为测试目的,Websocket API也支持测试网环境. 更新 `wsURL` 在配置中: ```typescript import { DerivativesTradingUsdsFutures, DERIVATIVES_TRADING_USDS_FUTURES_WS_API_TESTNET_URL } from '@binance/derivatives-trading-usds-futures'; const configurationWebsocketAPI = { apiKey: 'your-api-key', apiSecret: 'your-api-secret', wsURL: DERIVATIVES_TRADING_USDS_FUTURES_WS_API_TESTNET_URL, }; const client = new DerivativesTradingUsdsFutures({ configurationWebsocketAPI }); ``` 若为 `wsURL` 未提供,默认为 `wss://ws-fapi.binance.com/ws-fapi/v1`。 。 。 . ### 网页流 WebSocket Streams为市场交易,烛台等提供实时数据反馈. 使用 [网络锁流](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/src/websocket-streams/websocket-streams.ts) 模块来订阅这些流. ```typescript import { DerivativesTradingUsdsFutures, DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_PROD_URL } from '@binance/derivatives-trading-usds-futures'; const configurationWebsocketStreams = { wsURL: DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_PROD_URL, }; const client = new DerivativesTradingUsdsFutures({ configurationWebsocketStreams }); client.websocketStreams .connect() .then((connection) => { const stream = connection.allBookTickersStream(); stream.on('message', (data) => console.info(data)); }) .catch((err) => console.error(err)); ``` 更多实例可见于 [`examples/websocket-streams`](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/examples/websocket-streams/) 文件夹. #### 配置选项 WebSocket Streams API支持以下高级配置选项: - `reconnectDelay`: 指定重联尝试之间的延迟( 默认: 5000 ms) . - `compression`: 启用或禁用 WebSocket 信件的压缩(默认:为真). - `agent`: 自定义高级配置的 WebSocket代理. - `mode`: 选择 `single` 财务报告和审定财务报表 `pool` 连接模式. - `single`:一个单一的WebSocket连接. - `pool`:一个WebSocket连接的集合. - `poolSize`:在池模式下定义WebSocket连接数. ##### 重接延迟 指定WebSocket重联尝试对流的延迟, 以毫秒计 。 见 [重新连接延迟实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-streams/reconnect-delay.md) 供详细使用. ##### 压缩 启用或禁用 WebSocket Streams 信件的压缩 。 见 [压缩示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-streams/compression.md) 供详细使用. ##### WebSocket 代理服务器 自定义高级配置的代理 。 见 [WebSocket 代理实例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-streams/agent.md) 供详细使用. ##### 连接模式 选择 `single` 财务报告和审定财务报表 `pool` webSocket Streams 的连接模式。 这个 `single` 模式使用单一的 WebSocket 连接,而 `pool` 模式使用WebSocket连接的集合。 见 [连接模式示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-streams/connection-mode.md) 供详细使用. ##### 证书剪接 为了增强安全性,您可以使用证书标记 `agent` 选项。 这确保了客户端只使用特定证书与服务器进行通信. 见 [证书剪接示例](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/docs/websocket-streams/certificate-pinning.md) 供详细使用. #### 订阅到用户数据流 您可以消费用户数据流,该数据流发送账户和订单更新等账户级事件. 首先通过 REST 或 WebSocket API 创建一个收听键;然后: ```typescript import { DerivativesTradingUsdsFutures, DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_PROD_URL } from '@binance/derivatives-trading-usds-futures'; const configurationWebsocketStreams = { wsURL: DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_PROD_URL, }; const client = new DerivativesTradingUsdsFutures({ configurationWebsocketStreams }); client.websocketStreams .connect() .then((connection) => { const stream = connection.userData('listenKey'); stream.on('message', (data) => { switch (data.e) { case 'ACCOUNT_CONFIG_UPDATE': console.log('account config update stream', data); break; case 'ORDER_TRADE_UPDATE': console.log('order trade update stream', data); break; // …handle other variants… default: console.log('unknown stream', data); break; } }); }) .catch((err) => console.error(err)); ``` #### 从流中取消订阅 您可以使用 : `unsubscribe` 方法。 这对管理活动订阅而不关闭连接是有用的. ```typescript import { DerivativesTradingUsdsFutures, DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_PROD_URL } from '@binance/derivatives-trading-usds-futures'; const configurationWebsocketStreams = { wsURL: DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_PROD_URL, }; const client = new DerivativesTradingUsdsFutures({ configurationWebsocketStreams }); client.websocketStreams .connect() .then((connection) => { const stream = connection.allBookTickersStream(); stream.on('message', (data) => console.info(data)); setTimeout(() => { stream.unsubscribe(); console.log('Unsubscribed from allBookTickersStream stream'); }, 10000); }) .catch((err) => console.error(err)); ``` #### 测试网 Websocket Streams还支持开发与测试的测试网环境. 更新 `wsURL` 在配置中: ```typescript import { DerivativesTradingUsdsFutures, DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_TESTNET_URL } from '@binance/derivatives-trading-usds-futures'; const configurationWebsocketStreams = { wsURL: DERIVATIVES_TRADING_USDS_FUTURES_WS_STREAMS_TESTNET_URL, }; const client = new DerivativesTradingUsdsFutures({ configurationWebsocketStreams }); ``` 若为 `wsURL` 未提供,默认为 `wss://fstream.binance.com`。 。 。 . ### 自动连接更新 WebSocket连接在 API 密钥到期24小时前自动更新,用于WebSocket API和WebSocket Streams连接. 这确保了持续的连通性. ## 测试 为了进行测试: ```bash npm install npm run test ``` 测试包括: - REST API 终点 - WebSocket API 和流 - 处理错误和边缘大小写 ## 移徙指南 如果您正在升级到新的模块化结构,请参见 [移徙指南](https://npmcn.com/package/MIGRATION.md) 详细步骤. ## 捐款 欢迎捐款! 由于这个寄存器包含自动生成的代码,我们鼓励您首先打开一个GitHub问题来讨论您的想法或建议改进. 这有助于确保变化与项目目标和自动生成程序相一致. 协助: 1. 打开一个 GitHub 问题 描述您的建议 或者您已经识别出的bug . 2. 如果确定需要修改,维护者会将修改合并到主分支. 请保证所有测试都通过 如果你有直接的贡献。 仅在讨论和确认更改后提交拉动请求 . 谢谢你的贡献! ## 免责声明 此SDK由Binance在"如实"和"如实"的基础上提供,供您自己冒险使用. Binance没有就SDK的操作、其准确性、可靠性、完整性或适合任何特定目的作出任何说明或保证,无论是明示的还是暗示的. 在法律允许的最大限度内,Binance不承担由你使用或无法使用这种SDK引起的任何损失、损害或任何费用,包括但不限于由于SDK的错误、错误、中断或不准确造成的任何经济损失. 您使用此 SDK 访问 Binance 平台,须遵守 Binance API 关键名词和 Binance 使用名词,在与此免责声明相冲突时,该名词优先. 您只负责任何使用此 SDK 通过 Binance 平台执行的命令或交易 . 这一SDK并不打算构成投资建议或买卖或持有任何数字资产的建议。 您在行动前应独立评估并核实所有信息. - [使用条件](https://www.binance.com/en/terms) - [Binance API 关键词](https://www.binance.com/en/about-legal/terms-binance-api) ## 许可证 这个项目根据麻省理工学院的许可证获得许可。 见 [属性](https://npmcn.com/package/%40binance/derivatives-trading-usds-futures/LICENCE) 详细文件. ## 常见问题 ### @binance/derivatives-trading-usds-futures 是什么？ 官方 Binance 衍生交易\(COIN-M期货\) Connector - 一个轻量级库,为 Binance 的 COINN-M期货 REST API, WebSocket API 和 WebSocket Streams 提供了方便的接口\. ### 如何安装 @binance/derivatives-trading-usds-futures？ 在项目目录运行 npm install @binance/derivatives-trading-usds-futures，或使用 pnpm add / yarn add / bun add。 ### @binance/derivatives-trading-usds-futures 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @binance/derivatives-trading-usds-futures 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @binance/derivatives-trading-usds-futures 可以商用吗？ @binance/derivatives-trading-usds-futures 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @binance/derivatives-trading-usds-futures 的下载量有多少？ 根据 npm 官方下载统计，@binance/derivatives-trading-usds-futures 在 2026/10/08 – 2026/11/06 这 30 天内被下载 7,757 次，日均约 259 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @binance/derivatives-trading-usds-futures 还在维护吗？ 最新版本 39\.0\.2 发布于 2026/10/23（16 天前）；至今共发布 74 个版本，其中过去 12 个月发布了 49 个；首次发布于 2025/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。