binance-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Binance Auth Skill

Authentication skill for Binance cryptocurrency exchange API. Built on top of auth-provider for secure API key storage and management. Supports both Binance production and testnet environments.

面向Binance加密货币交易所API的认证技能工具。基于auth-provider构建，实现安全的API密钥存储与管理，同时支持Binance生产环境与测试网环境。

Features

功能特性

Secure API Key Storage: Encrypted storage of API keys and secrets
Environment Toggle: Switch between production and testnet seamlessly
Permission Validation: Verify API key permissions (spot, margin, futures)
Health Checks: Validate API connectivity and key status
Multi-Profile: Support multiple Binance accounts
Balance Queries: Check account balances as part of health validation

安全API密钥存储：对API密钥和机密进行加密存储
环境切换：无缝切换生产环境与测试网
权限验证：验证API密钥的权限（现货、杠杆、期货）
健康检查：验证API连通性与密钥状态
多配置文件：支持多个Binance账户
余额查询：在健康验证中包含账户余额检查

Installation

安装步骤

bash

npm install
npm run build

bash

npm install
npm run build

Environment Variables

环境变量

No environment variables required - API keys are configured per-profile via CLI.

无需环境变量 - API密钥通过CLI按配置文件进行配置。

CLI Usage

CLI使用说明

View Status

查看状态

bash

node dist/cli.js status

bash

node dist/cli.js status

Connect API Key

关联API密钥

bash

undefined

bash

undefined

Production environment

生产环境

node dist/cli.js connect prod
--key YOUR_API_KEY
--secret YOUR_API_SECRET
--env production

Testnet environment

测试网环境

node dist/cli.js connect test
--key YOUR_API_KEY
--secret YOUR_API_SECRET
--env testnet

undefined

node dist/cli.js connect test
--key YOUR_API_KEY
--secret YOUR_API_SECRET
--env testnet

undefined

Health Check

健康检查

bash

undefined

bash

undefined

Check specific profile

检查指定配置文件

node dist/cli.js health prod

Check all profiles

检查所有配置文件

node dist/cli.js health

undefined

node dist/cli.js health

undefined

List Profiles

列出配置文件

bash

node dist/cli.js list

bash

node dist/cli.js list

Get Balance

获取余额

bash

node dist/cli.js balance prod

bash

node dist/cli.js balance prod

Validate Permissions

验证权限

bash

node dist/cli.js validate prod

bash

node dist/cli.js validate prod

Disconnect

解除关联

bash

node dist/cli.js disconnect prod

bash

node dist/cli.js disconnect prod

JavaScript/TypeScript API

Initialize Client

初始化客户端

typescript

import { BinanceAuthClient, getBinanceAuth } from '@openclaw/binance-auth';

// Create client for specific profile
const binance = new BinanceAuthClient('prod');

// Or use singleton
const binance = getBinanceAuth('prod');

typescript

import { BinanceAuthClient, getBinanceAuth } from '@openclaw/binance-auth';

// 为指定配置文件创建客户端
const binance = new BinanceAuthClient('prod');

// 或使用单例模式
const binance = getBinanceAuth('prod');

Connect API Key

关联API密钥

typescript

const result = await binance.connect({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  environment: 'production', // or 'testnet'
});

if (result.success) {
  console.log('Connected! Permissions:', result.permissions);
}

typescript

const result = await binance.connect({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  environment: 'production', // 或 'testnet'
});

if (result.success) {
  console.log('关联成功！权限：', result.permissions);
}

Check Connection

检查连接状态

typescript

const isConnected = await binance.isConnected();
console.log('Connected:', isConnected);

typescript

const isConnected = await binance.isConnected();
console.log('已关联：', isConnected);

Get API Credentials

获取API凭证

typescript

const credentials = await binance.getCredentials();
if (credentials) {
  console.log('API Key:', credentials.apiKey);
  console.log('Environment:', credentials.environment);
}

typescript

const credentials = await binance.getCredentials();
if (credentials) {
  console.log('API密钥：', credentials.apiKey);
  console.log('环境：', credentials.environment);
}

Health Check

健康检查

typescript

const health = await binance.healthCheck();
console.log('Status:', health.status); // 'healthy' | 'unhealthy'
console.log('Message:', health.message);

typescript

const health = await binance.healthCheck();
console.log('状态：', health.status); // 'healthy' | 'unhealthy'
console.log('消息：', health.message);

Get Account Balance

获取账户余额

typescript

const balance = await binance.getBalance();
if (balance) {
  console.log('Total BTC:', balance.totalBTC);
  console.log('Balances:', balance.balances);
  console.log('Permissions:', balance.permissions);
}

typescript

const balance = await binance.getBalance();
if (balance) {
  console.log('总BTC余额：', balance.totalBTC);
  console.log('各资产余额：', balance.balances);
  console.log('权限：', balance.permissions);
}

Validate Permissions

验证权限

typescript

const validation = await binance.validatePermissions();
console.log('Valid:', validation.valid);
console.log('Can Trade:', validation.canTrade);
console.log('Can Withdraw:', validation.canWithdraw);
console.log('Permissions:', validation.permissions);

typescript

const validation = await binance.validatePermissions();
console.log('有效：', validation.valid);
console.log('可交易：', validation.canTrade);
console.log('可提现：', validation.canWithdraw);
console.log('权限：', validation.permissions);

Disconnect

解除关联

typescript

const disconnected = await binance.disconnect();
console.log('Disconnected:', disconnected);

typescript

const disconnected = await binance.disconnect();
console.log('已解除关联：', disconnected);

API Permissions

API权限

Binance API keys can have the following permissions:

```
SPOT
```
- Spot trading
```
MARGIN
```
- Margin trading
```
FUTURES
```
- Futures trading
```
DELIVERY
```
- Coin-margined futures
```
PERM
```
- Permanent API key
```
IP_RESTRICTED
```
- IP-restricted access

Binance API密钥可拥有以下权限：

```
SPOT
```
- 现货交易
```
MARGIN
```
- 杠杆交易
```
FUTURES
```
- 期货交易
```
DELIVERY
```
- 币本位期货
```
PERM
```
- 永久API密钥
```
IP_RESTRICTED
```
- IP限制访问

Environments

环境说明

Production

生产环境

API Base:
```
https://api.binance.com
```
Real trading with real funds
Requires verified Binance account

API基础地址：
```
https://api.binance.com
```
使用真实资金进行实盘交易
需要已验证的Binance账户

Testnet

测试网

API Base:
```
https://testnet.binance.vision
```
Paper trading with test funds
Free testnet registration at: https://testnet.binance.vision/

API基础地址：
```
https://testnet.binance.vision
```
使用测试资金进行模拟交易
免费测试网注册地址：https://testnet.binance.vision/

Storage Location

存储位置

Credentials are stored in the auth-provider database:

~/.openclaw/skills/auth-provider/credentials.db

API keys are encrypted with AES-256.

凭证存储在auth-provider数据库中：

~/.openclaw/skills/auth-provider/credentials.db

API密钥采用AES-256加密。

TypeScript Types

TypeScript类型定义

typescript

interface BinanceCredentials {
  apiKey: string;
  apiSecret: string;
  environment: 'production' | 'testnet';
  permissions?: string[];
}

interface BinanceConnectionResult {
  success: boolean;
  permissions?: string[];
  canTrade?: boolean;
  canWithdraw?: boolean;
  error?: string;
}

interface BinanceBalance {
  totalBTC: string;
  balances: Array<{
    asset: string;
    free: string;
    locked: string;
  }>;
  permissions: string[];
}

interface BinanceValidationResult {
  valid: boolean;
  permissions: string[];
  canTrade: boolean;
  canWithdraw: boolean;
}

typescript

interface BinanceCredentials {
  apiKey: string;
  apiSecret: string;
  environment: 'production' | 'testnet';
  permissions?: string[];
}

interface BinanceConnectionResult {
  success: boolean;
  permissions?: string[];
  canTrade?: boolean;
  canWithdraw?: boolean;
  error?: string;
}

interface BinanceBalance {
  totalBTC: string;
  balances: Array<{
    asset: string;
    free: string;
    locked: string;
  }>;
  permissions: string[];
}

interface BinanceValidationResult {
  valid: boolean;
  permissions: string[];
  canTrade: boolean;
  canWithdraw: boolean;
}

Error Handling

错误处理

typescript

try {
  await binance.connect({ apiKey, apiSecret, environment: 'production' });
} catch (error) {
  if (error.message.includes('Invalid API key')) {
    // API key format is invalid
  } else if (error.message.includes('API key validation failed')) {
    // Key rejected by Binance
  }
}

typescript

try {
  await binance.connect({ apiKey, apiSecret, environment: 'production' });
} catch (error) {
  if (error.message.includes('Invalid API key')) {
    // API密钥格式无效
  } else if (error.message.includes('API key validation failed')) {
    // 密钥被Binance拒绝
  }
}

Security Notes

安全注意事项

API secrets are never exposed after storage
All API calls use HMAC-SHA256 signatures
Database file has 0600 permissions (user read/write only)
Use IP restrictions on your Binance API keys for added security
Never commit API credentials to version control

API机密存储后绝不会被暴露
所有API调用均使用HMAC-SHA256签名
数据库文件权限为0600（仅用户可读/写）
建议为Binance API密钥设置IP限制以提升安全性
切勿将API凭证提交至版本控制系统

Testing

测试

bash

undefined

bash

undefined

Type checking

类型检查

npm run typecheck

Build

构建

npm run build

Run CLI

运行CLI

npm run cli -- status

undefined

npm run cli -- status

undefined

Dependencies

依赖项

```
@openclaw/auth-provider
```
- Secure credential storage
Uses crypto module for HMAC-SHA256 signatures

```
@openclaw/auth-provider
```
- 安全凭证存储
使用crypto模块生成HMAC-SHA256签名