Binance JavaScript SPOT 连接器

这是Binance SPOT API的客户端库,使开发者能够与Binance的SPOT交易平台进行程序互动. 该图书馆通过三个不同的终点提供检索市场数据、执行交易和管理订单的工具:

支持的特性

REST API 结束点 :
- /api/*
WebSocket Endpoints:实时数据流与请求响应通信.
包括测试案例和快速上船的例子.

安装

要使用此库, 请确保您的环境正在运行节点. js 版本 22.12.0 国家 或后会. 如果你在用的话 nvm (节点版本管理器),您可以设置正确的版本如下:

nvm install 22.12.0
nvm use 22.12.0

然后使用 npm数字 :

npm install @binance/spot

文档

关于详细情况,请参看 Binance API 文档。。。 .

REST APIs 软件

所有 REST API 端点都可通过 rest-api 模块。 REST API 允许您获取市场数据,管理交易和访问账户信息。注意一些端点需要使用您的 Binance API 证书进行认证 .

import { Spot, SpotRestAPI } from '@binance/spot';

const configurationRestAPI = {
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
};
const client = new Spot({ configurationRestAPI });

client.restAPI
    .exchangeInfo({ symbol: 'BNBUSDT' })
    .then((res) => res.data())
    .then((data: SpotRestAPI.ExchangeInfoResponse) => console.log(data))
    .catch((err) => console.error(err));

更多实例可见于 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:私人密钥的密码句,如果加密的话.
timeUnit:指定时间戳的时间单位(如毫秒或微秒).

超时

您可以为请求配置超时, 以毫秒计。如果请求超过指定的超时,将中止。见超时示例供详细使用.

代理服务器

REST API支持HTTP/HTTPS代理配置. 见代理实例供详细使用.

保留-生活

为持续连接启用 HTTP 保留状态。见保持生命实例供详细使用.

压缩

启用或禁用响应压缩。见压缩示例供详细使用.

检索

配置重试尝试和延迟的次数, 在失败请求的重试之间以毫秒计。见重试示例供详细使用.

HTTPS 代理服务器

自定义高级 TLS 配置的 HTTPS 代理。见 HTTPS (韩语) 代理实例供详细使用.

基于密钥对等认证

REST API支持基于密钥的对等认证,用于安全通信. 你用得着 RSA 或者说 ED25519 用于签名请求的密钥。见基于密钥对等认证示例供详细使用.

时间单位

REST API支持时间戳值的不同时间单位. 见时间单位示例更多细节.

证书剪接

为了增强安全性,您可以使用证书标记 httpsAgent 选项。这确保了客户端只使用特定证书与服务器进行通信. 见证书剪接示例供详细使用.

处理错误

REST API 提供了详细的出错类型来帮助您有效处理问题 :

ConnectorClientError: 一般客户端出错.
RequiredError: 缺少所需参数时抛出.
UnauthorizedError: 显示缺少或无效的认证证书.
ForbiddenError: 禁止获取所请求的资源.
TooManyRequestsError: 超过费率限额.
RateLimitBanError:IP地址被禁,因为超过费率限制.
ServerError: 内部服务器出错.
NetworkError: 网络连接问题.
NotFoundError: 资源未找到 .
BadRequestError: 无效的请求.

见处理错误实例供详细使用.

测试网

为了测试目的, /api/* 结束点可用于点点测试网更新 basePath 在配置中:

import { Spot, SpotRestAPI, SPOT_REST_API_TESTNET_URL } from '@binance/spot';

const configurationRestAPI = {
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    basePath: SPOT_REST_API_TESTNET_URL,
};
const client = new Spot({ configurationRestAPI });

若为 basePath 未提供,默认为 https://api.binance.com。。。 .

网络锁定 API

WebSocket API为市场数据和交易行动提供请求-响应通信. 使用 websocket-api 模块与这些端点交互.

import { Spot, SpotWebsocketAPI } from '@binance/spot';

const configurationWebsocketAPI = {
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
};
const client = new Spot({ configurationWebsocketAPI });

client.websocketAPI
    .connect()
    .then((connection: SpotWebsocketAPI.WebsocketAPIConnection) =>
        connection.exchangeInfo({ symbol: 'BNBUSDT' })
    )
    .then((res: SpotWebsocketAPI.ApiResponse<SpotWebsocketAPI.ExchangeInfoResponse>) =>
        console.log(res.data)
    )
    .catch((err) => console.error(err));

更多实例可见于 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:私人密钥的密码句,如果加密的话.
timeUnit:指定时间戳的时间单位(如毫秒或微秒).

超时

设置以毫秒计的 WebSocket API 请求的超时。见超时示例供详细使用.

重接延迟

指定WebSocket重联尝试之间的延迟, 以毫秒计。见重新连接延迟实例供详细使用.

压缩

启用或禁用 WebSocket 信件的压缩。见压缩示例供详细使用.

WebSocket 代理服务器

自定义高级配置的代理。见 WebSocket 代理实例供详细使用.

连接模式

选择 single 财务报告和审定财务报表 pool webSocket 连接的连接模式。这个 single 模式使用单一的 WebSocket 连接,而 pool 模式使用WebSocket连接的集合。见连接模式示例供详细使用.

基于密钥对等认证

使用RSA或ED25519私人密钥进行WebSocket API认证. 见密钥对等认证示例供详细使用.

证书剪接

为了增强安全性,您可以使用证书标记 agent 选项。这确保了客户端只使用特定证书与服务器进行通信. 见证书剪接示例供详细使用.

时间单位

指定 WebSocket API 时间戳的时间单位(例如毫秒或微秒). 见时间单位示例供详细使用.

您可以消费用户数据流,该数据流发送账户和订单更新等账户级事件. 首先做一个 logon 通过 WebSocket API 连接到websocket;然后:

import { Spot, SpotWebsocketAPI } from '@binance/spot';

const configurationWebsocketAPI = {
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
};
const client = new Spot({ configurationWebsocketAPI });

client.websocketAPI
    .connect()
    .then((connection) => connection.sessionLogon().then(() => connection))
    .then((connection) => connection.userDataStreamSubscribe())
    .then(({ stream }) => {
        stream.on('message', (data) => {
            switch (data.e) {
                case 'balanceUpdate':
                    console.log('balance update stream', data);
                    break;
                case 'outboundAccountPosition':
                    console.log('outbound account position stream', data);
                    break;
                // …handle other variants…
                default:
                    console.log('unknown stream', data);
                    break;
            }
        });
    })
    .catch((err) => console.error(err));

测试网

为测试目的,Websocket API也支持测试网环境. 更新 wsURL 在配置中:

import { Spot, SpotWebsocketAPI, SPOT_WS_API_TESTNET_URL } from '@binance/spot';

const configurationWebsocketAPI = {
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    wsURL: SPOT_WS_API_TESTNET_URL,
};
const client = new Spot({ configurationWebsocketAPI });

若为 wsURL 未提供,默认为 wss://ws-api.binance.com:443/ws-api/v3。。。 .

网页流

WebSocket Streams为市场交易,烛台等提供实时数据反馈. 使用网络锁流模块来订阅这些流.

import { Spot, SpotWebsocketStreams, SPOT_WS_STREAMS_PROD_URL } from '@binance/spot';

const configurationWebsocketStreams = {
    wsURL: SPOT_WS_STREAMS_PROD_URL,
};
const client = new Spot({ configurationWebsocketStreams });

client.websocketStreams
    .connect()
    .then((connection: SpotWebsocketStreams.WebsocketStreamsConnection) => {
        const stream = connection.aggTrade({ symbol: 'BNBUSDT' });
        stream.on('message', (data: SpotWebsocketStreams.AggTradeResponse) => console.info(data));
    })
    .catch((err) => console.error(err));

更多实例可见于 examples/websocket-streams 文件夹.

配置选项

WebSocket Streams API支持以下高级配置选项:

reconnectDelay: 指定重联尝试之间的延迟( 默认: 5000 ms) .
compression: 启用或禁用 WebSocket 信件的压缩(默认:为真).
agent: 自定义高级配置的 WebSocket代理.
mode: 选择 single 财务报告和审定财务报表 pool 连接模式.
- single:一个单一的WebSocket连接.
- pool:一个WebSocket连接的集合.
poolSize:在池模式下定义WebSocket连接数.
timeUnit:指定时间戳的时间单位(如毫秒或微秒).

重接延迟

指定WebSocket重联尝试对流的延迟, 以毫秒计。见重新连接延迟实例供详细使用.

压缩

启用或禁用 WebSocket Streams 信件的压缩。见压缩示例供详细使用.

WebSocket 代理服务器

自定义高级配置的代理。见 WebSocket 代理实例供详细使用.

连接模式

选择 single 财务报告和审定财务报表 pool webSocket Streams 的连接模式。这个 single 模式使用单一的 WebSocket 连接,而 pool 模式使用WebSocket连接的集合。见连接模式示例供详细使用.

证书剪接

为了增强安全性,您可以使用证书标记 agent 选项。这确保了客户端只使用特定证书与服务器进行通信. 见证书剪接示例供详细使用.

时间单位

指定 WebSocket Streams 时间戳(如毫秒或微秒)的时间单位。见时间单位示例供详细使用.

从流中取消订阅

您可以使用 : unsubscribe 方法。这对管理活动订阅而不关闭连接是有用的.

import { Spot, SpotWebsocketStreams, SPOT_WS_STREAMS_PROD_URL } from '@binance/spot';

const configurationWebsocketStreams = {
    wsURL: SPOT_WS_STREAMS_PROD_URL,
};
const client = new Spot({ configurationWebsocketStreams });

client.websocketStreams
    .connect()
    .then((connection: SpotWebsocketStreams.WebsocketStreamsConnection) => {
        const stream = connection.aggTrade({ symbol: 'BNBUSDT' });
        stream.on('message', (data: SpotWebsocketStreams.AggTradeResponse) => console.info(data));

        setTimeout(() => {
            stream.unsubscribe();
            console.log('Unsubscribed from BNBUSDT trade stream');
        }, 10000);
    })
    .catch((err) => console.error(err));

测试网

Websocket Streams还支持开发与测试的测试网环境. 更新 wsURL 在配置中:

import { Spot, SpotWebsocketStreams, SPOT_WS_STREAMS_TESTNET_URL } from '@binance/spot';

const configurationWebsocketStreams = {
    wsURL: SPOT_WS_STREAMS_TESTNET_URL,
};
const client = new Spot({ configurationWebsocketStreams });

若为 wsURL 未提供,默认为 wss://stream.binance.com:9443。。。 .

自动连接更新

WebSocket连接在 API 密钥到期24小时前自动更新,用于WebSocket API和WebSocket Streams连接. 这确保了持续的连通性.

测试

为了进行测试:

npm install

npm run test

测试封面: - REST API 端点 - WebSocket API和流 - 错误处理和边缘大小写

移徙指南

如果您正在升级到新的模块化结构,请参见移徙指南详细步骤.

捐款

欢迎捐款!

由于这个寄存器包含自动生成的代码,我们鼓励您首先打开一个GitHub问题来讨论您的想法或建议改进. 这有助于确保变化与项目目标和自动生成程序相一致.

协助:

打开一个 GitHub 问题描述您的建议或者您已经识别出的bug .
如果确定需要修改,维护者会将修改合并到主分支.

请保证所有测试都通过如果你有直接的贡献。仅在讨论和确认更改后提交拉动请求 .

谢谢你的贡献!

免责声明

此SDK由Binance在"如实"和"如实"的基础上提供,供您自己冒险使用. Binance没有就SDK的操作、其准确性、可靠性、完整性或适合任何特定目的作出任何说明或保证,无论是明示的还是暗示的.

在法律允许的最大限度内,Binance不承担由你使用或无法使用这种SDK引起的任何损失、损害或任何费用,包括但不限于由于SDK的错误、错误、中断或不准确造成的任何经济损失.

您使用此 SDK 访问 Binance 平台,须遵守 Binance API 关键名词和 Binance 使用名词,在与此免责声明相冲突时,该名词优先. 您只负责任何使用此 SDK 通过 Binance 平台执行的命令或交易 .

这一SDK并不打算构成投资建议或买卖或持有任何数字资产的建议。您在行动前应独立评估并核实所有信息.

许可证

这个项目根据麻省理工学院的许可证获得许可。见属性详细文件.

版本	发布日期	距今
`34.0.5`latest	2026/10/27	12 天前
`34.0.4`	2026/10/23	16 天前
`34.0.3`	2026/10/19	19 天前
`34.0.2`	2026/10/15	23 天前
`34.0.1`	2026/10/02	1 个月前
`34.0.0`	2026/10/02	1 个月前

@binance/spot

Binance JavaScript SPOT 连接器

目录

支持的特性

安装

文档

REST APIs 软件

配置选项

超时

代理服务器

保留-生活

压缩

检索

HTTPS 代理服务器

基于密钥对等认证

时间单位

证书剪接

处理错误

测试网

网络锁定 API

配置选项

超时

重接延迟

压缩

WebSocket 代理服务器

连接模式

基于密钥对等认证

证书剪接

时间单位

订阅到用户数据流

测试网

网页流

配置选项

重接延迟

压缩

WebSocket 代理服务器

连接模式

证书剪接

时间单位

从流中取消订阅

测试网

自动连接更新

测试

移徙指南

捐款

免责声明

许可证

版本与发布记录

关于 @binance/spot 的常见问题

@binance/spot 是什么？

如何安装 @binance/spot？

@binance/spot 支持 TypeScript 吗？

@binance/spot 支持 ESM 还是 CommonJS？

@binance/spot 可以商用吗？

@binance/spot 的下载量有多少？

@binance/spot 还在维护吗？