KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

bingx-go

★ 20 Open GitHub ↗

Full-featured Golang SDK for BingX cryptocurrency exchange API. Supports USDT-M & Coin-M perpetual futures, spot trading, market data, WebSocket streams, account management, and copy trading. Type-safe, production-ready with HMAC-SHA256 security. Complete API coverage with idiomatic Go interfaces.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# BingX Go SDK

![BingX Golang SDK](https://i.postimg.cc/htbVV4yh/528052139-61babf48-746f-469e-aeed-5058a9337d86.jpg)

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat-square&logo=go)](https://golang.org/)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](https://raw.githubusercontent.com/tigusigalpa/bingx-go/main/LICENSE)
[![Go Report Card](https://goreportcard.com/badge/github.com/tigusigalpa/bingx-go/v2?style=flat-square)](https://goreportcard.com/report/github.com/tigusigalpa/bingx-go/v2)
[![GitHub Release](https://img.shields.io/github/v/release/tigusigalpa/bingx-go?style=flat-square)](https://github.com/tigusigalpa/bingx-go/releases)
[![GoDoc](https://img.shields.io/badge/godoc-reference-blue?style=flat-square&logo=go)](https://pkg.go.dev/github.com/tigusigalpa/bingx-go/v2)

</div>

Go client for the [BingX](https://bingx.com) cryptocurrency exchange API v3. Covers USDT-M and Coin-M perpetual futures,
TradFi (stocks, forex, commodities, indices), spot trading, copy trading, sub-accounts, and WebSocket streaming.
260+ API methods with full v3 support.

**Package:** [pkg.go.dev/github.com/tigusigalpa/bingx-go/v2](https://pkg.go.dev/github.com/tigusigalpa/bingx-go/v2)

> 📖 **[Full documentation available on Wiki](https://github.com/tigusigalpa/bingx-go/wiki)**

### 🚀 Quick Links

- **[API v3 Migration Guide](API_V3_MIGRATION.md)** - Complete guide for upgrading to v3
- **[v3 Update Summary](V3_UPDATE_SUMMARY.md)** - Technical details of all v3 changes
- **[Changelog](CHANGELOG.md)** - Version history and release notes
- **[Examples](examples/)** - Working code examples

## Table of Contents

- [Features](#features)
- [What's New in v3](#whats-new-in-v3) ⭐
- [Architecture](#architecture)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Examples](#usage-examples)
  - [Market Data](#market-service---market-data)
  - [Account Management](#account-service---account-management)
  - [Trading Operations](#trade-service---trading-operations)
  - [Advanced Trading (v3)](#advanced-trading-features-v3) ⭐
  - [Spot Trading](#spot-trading---spot-order-management) ⭐
  - [Coin-M Futures](#coin-m-perpetual-futures)
  - [TradFi (Traditional Finance)](#tradfi-traditional-finance)
  - [WebSocket Streaming](#websocket-streaming)
    - [Market Data](#market-service---market-data)
    - [Account Management](#account-service---account-management)
    - [Trading Operations](#trade-service---trading-operations)
    - [Wallet Management](#wallet-service---wallet-management)
    - [Coin-M Futures](#coin-m-perpetual-futures)
    - [TradFi](#tradfi-traditional-finance)
    - [Sub-Accounts](#sub-account-management)
    - [Copy Trading](#copy-trading-operations)
    - [WebSocket Streaming](#websocket-streaming)
- [Advanced Features](#advanced-features)
- [Configuration](#configuration)
- [Error Handling](#error-handling)
- [Best Practices](#best-practices)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

---

## Features

### Service coverage

#### USDT-M Perpetual Futures

- **Market Service** (45+ methods)
    - Real-time & historical prices
    - Market depth & order books
    - Candlestick data (K-lines)
    - 24hr tickers & statistics
    - Funding rates & premium index
    - Aggregate & recent trades
    - Long/short ratios
    - Basis data & sentiment analysis

- **Account Service** (25+ methods)
    - Balance & asset management
    - Position tracking & monitoring
    - Leverage configuration
    - Margin mode management
    - Trading fees & commissions
    - API permissions & rate limits
    - Balance history & deposits

- **Trade Service** (35+ methods)
    - Order creation & management (incl. TWAP orders)
    - Batch order operations
    - Order modification & cancellation
    - Position management & one-click reverse
    - Multi-assets mode support
    - Hedge mode auto margin addition
    - Trade history & analytics
    - Test orders (sandbox)
    - Commission calculations

- **Wallet Service** (6+ methods)
    - Deposit & withdrawal management
    - Address generation
    - Transaction history
    - Multi-coin support
    - Network selection

</td>
<td width="50%" valign="top">

#### **Advanced Features**

- **Spot Account Service** (8+ methods)
    - Spot balance management
    - Universal transfers
    - Internal transfers
    - Transfer history
    - Multi-account support

- **Sub-Account Service** (20+ methods)
    - Sub-account creation & management
    - API key management
    - Asset transfers
    - Deposit address management
    - Authorization controls

- **Copy Trading Service** (13+ methods)
    - Futures copy trading
    - Spot copy trading
    - Profit tracking
    - Commission management
    - Trading pair configuration

- **Contract Service** (3+ methods)
    - Standard contract positions
    - Order history
    - Balance queries

- **Listen Key Service** (3+ methods)
    - WebSocket authentication
    - Key generation & extension
    - Session management

#### **Coin-M Perpetual Futures**

- **Coin-M Market** (6+ methods)
    - Contract specifications
    - Ticker & price data
    - Market depth
    - K-line data
    - Open interest
    - Funding rates

- **Coin-M Trade** (17+ methods)
    - Order management
    - Position tracking
    - Leverage & margin
    - Balance queries
    - Trade history

#### **TradFi (Traditional Finance)** ⭐

- **TradFi Market** (15+ methods)
    - Stock tokens (TSLA, AAPL, NVDA)
    - Forex pairs (EUR-USD, GBP-USD)
    - Commodities (GOLD, SILVER, OIL)
    - Stock indices (SPX, DJI, NDX)
    - Real-time & historical prices
    - Market depth & order books
    - Candlestick data (K-lines)
    - Funding rates & open interest

- **TradFi Trade** (20+ methods)
    - Order management (same as crypto perpetuals)
    - TWAP orders for large trades
    - Position management & one-click reverse
    - Leverage & margin configuration
    - Trade history & analytics

- **TradFi Account** (15+ methods)
    - Balance & position tracking
    - Position risk monitoring
    - Income history (PNL, funding, commissions)
    - Hedge/One-way mode support
    - Multi-assets margin mode

</td>
</tr>
</table>

### Key capabilities

| Feature              | Description                                                |
|----------------------|------------------------------------------------------------|
| **Real-Time Data**   | WebSocket support for live market data and account updates |
| **Order Types**      | MARKET, LIMIT, STOP, STOP_MARKET, TAKE_PROFIT, TRIGGER_LIMIT, TRAILING_STOP_MARKET, TRAILING_TP_SL |
| **Position Modes**   | One-way and Hedge mode support                             |
| **Margin Types**     | ISOLATED and CROSSED margin modes                          |
| **Time in Force**    | GTC, IOC, FOK order execution options                      |
| **Risk Management**  | Stop-loss, take-profit, trailing stops                     |
| **Batch Operations** | Create, modify, and cancel multiple orders at once         |
| **Historical Data**  | Access to comprehensive historical trading data            |

---

## Architecture

```
bingx-go/
├── client.go              # Main client with service orchestration
├── coinm_client.go        # Coin-M futures client
├── tradfi_client.go       # TradFi (Traditional Finance) client
├── http/
│   └── client.go          # HTTP client with HMAC signing
├── errors/
│   └── errors.go          # Custom error types
├── services/
│   ├── market.go          # Market data service
│   ├── account.go         # Account management service
│   ├── trade.go           # Trading operations service
│   ├── wallet.go          # Wallet operations service
│   ├── spotaccount.go     # Spot account service
│   ├── subaccount.go      # Sub-account service
│   ├── copytrading.go     # Copy trading service
│   ├── contract.go        # Contract service
│   ├── listenkey.go       # WebSocket auth service
│   ├── coinm/             # Coin-M specific services
│   │   ├── market.go
│   │   ├── trade.go
│   │   └── listenkey.go
│   └── tradfi/            # TradFi specific services
│       ├── market.go      # Stocks, forex, commodities market data
│       ├── trade.go       # TradFi trading operations
│       ├── account.go     # TradFi account management
│       └── listenkey.go   # WebSocket auth for TradFi
└── examples/              # Usage examples
```

### Design Principles

- **Single Responsibility** - Each service handles a specific domain
- **Dependency Injection** - HTTP client injected for testability
- **Functional Options** - Flexible client configuration
- **Error Transparency** - Rich error types for debugging
- **Immutability** - Thread-safe by design

---

## Installation

- Go 1.21+
- BingX account with API keys (for authenticated endpoints)

```bash
go get github.com/tigusigalpa/bingx-go/v2
```

Only external dependency: `github.com/gorilla/websocket` (for WebSocket features)

---

## Quick Start

```go
package main

import (
    "fmt"
    "log"
    
    bingx "github.com/tigusigalpa/bingx-go/v2"
)

func main() {
    // Create client
    client := bingx.NewClient(
        "YOUR_API_KEY",
        "YOUR_API_SECRET",
        bingx.WithBaseURI("https://open-api.bingx.com"),
        bingx.WithSignatureEncoding("base64"),
    )
    
    // Get current price
    price, err := client.Market().GetLatestPrice("BTC-USDT")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("BTC price: %v\n", price)
    
    // Get account balance
    balance, err := client.Account().GetBalance()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Balance: %v\n", balance)
    
    // Create an order
    order, err := client.Trade().CreateOrder(map[string]interface{}{
        "symbol":       "BTC-USDT",
        "side":         "BUY",
        "type":         "LIMIT",
        "positionSide": "LONG",
        "price":        50000.0,
        "quantity":     0.001,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Order created: %v\n", order)
}
```

---

## Usage Examples

### Market Service - Market Data

```go
// Get futures symbols
symbols, err := client.Market().GetFuturesSymbols()

// Get spot symbols
spotSymbols, err := client.Market().GetSpotSymbols()

// Get all symbols
allSymbols, err := client.Market().GetAllSymbols()

// Get latest price
price, err := client.Market().GetLatestPrice("BTC-USDT")

// Get market depth
depth, err := client.Market().GetDepth("BTC-USDT", 20)

// Get K-lines
klines, err := client.Market().GetKlines("BTC-USDT", "1h", 100, nil, nil)

// Get spot K-lines with timezone (v2 endpoint)
// timeZone: 0=UTC (default), 8=UTC+8
timeZone := int64(8) // UTC+8
spotKlines, err := client.Market().GetSpotKlines("BTC-USDT", "1h", 100, nil, nil, &timeZone)

// Get 24hr ticker
ticker, err := client.Market().Get24hrTicker(nil) // nil for all symbols

// Get funding rate history
fundingRate, err := client.Market().GetFundingRateHistory("BTC-USDT", 100)

// Enhanced Market Data (v3)

// Open Interest
oi, err := client.Market().GetOpenInterest("BTC-USDT")

// Open Interest History
oiHistory, err := client.Market().GetOpenInterestHistory("BTC-USDT", "5m", 100, nil, nil)

// Funding Rate Info
fundingInfo, err := client.Market().GetFundingRateInfo("BTC-USDT")

// Book Ticker (Best Bid/Ask)
bookTicker, err := client.Market().GetBookTicker(&symbol)
spotBookTicker, err := client.Market().GetSpotBookTicker(&symbol)

// Index Price
indexPrice, err := client.Market().GetIndexPrice("BTC-USDT")

// Ticker Price
tickerPrice, err := client.Market().GetTickerPrice(&symbol)
```

### Account Service - Account Management

```go
// Get account balance
balance, err := client.Account().GetBalance()

// Get positions
positions, err := client.Account().GetPositions(nil) // nil for all positions

// Get positions for specific symbol
btcPositions, err := client.Account().GetPositions(&symbol)

// Get account info
accountInfo, err := client.Account().GetAccountInfo()

// Get/Set leverage
leverage, err := client.Account().GetLeverage("BTC-USDT", nil)
err = client.Account().SetLeverage("BTC-USDT", "BOTH", 20, nil)

// Get/Set margin mode
marginMode, err := client.Account().GetMarginMode("BTC-USDT")
err = client.Account().SetMarginMode("BTC-USDT", "ISOLATED")

// Advanced Account Features (v3)

// Position Risk Metrics
risk, err := client.Account().GetPositionRisk(&symbol, nil)
// Returns: liquidation price, leverage, margin ratio, unrealized PnL, etc.

// Income/PnL History
incomeType := "REALIZED_PNL" // REALIZED_PNL, FUNDING_FEE, COMMISSION, etc.
income, err := client.Account().GetIncomeHistory(&symbol, &incomeType, nil, nil, 100, nil)

// Commission History
commissions, err := client.Account().GetCommissionHistory("BTC-USDT", nil, nil, 100, nil)

// Liquidation/Force Orders
forceOrders, err := client.Account().GetForceOrders(&symbol, nil, nil, nil, 100, nil)

// Position Mode (Hedge vs One-Way)
mode, err := client.Account().GetPositionMode(nil)
err = client.Account().SetPositionMode(true, nil) // true = hedge mode, false = one-way
```

### Trade Service - Trading Operations

```go
import "github.com/tigusigalpa/bingx-go/v2/services"

// Create order with new v3 order types
order, err := client.Trade().CreateOrder(map[string]interface{}{
    "symbol":       "BTC-USDT",
    "side":         "BUY",
    "type":         services.OrderTypeTriggerLimit, // New v3 order type
    "positionSide": "LONG",
    "price":        50000.0,
    "stopPrice":    49500.0,
    "quantity":     0.001,
})

// Trailing stop market order (v3)
order, err = client.Trade().CreateOrder(map[string]interface{}{
    "symbol":           "ETH-USDT",
    "side":             "SELL",
    "type":             services.OrderTypeTrailingStopMarket,
    "positionSide":     "SHORT",
    "activationPrice":  3000.0,
    "callbackRate":     1.0, // 1% callback
    "quantity":         0.1,
})

// Cancel order
orderID := "123456789"
err = client.Trade().CancelOrder("BTC-USDT", &orderID, nil, nil, nil)

// Cancel all orders
err = client.Trade().CancelAllOrders(nil, &symbol, nil, nil)

// Get order details
order, err := client.Trade().GetOrder("BTC-USDT", "123456789")

// Get open orders
openOrders, err := client.Trade().GetOpenOrders(nil, 100)

// Get order history
history, err := client.Trade().GetOrderHistory(&symbol, 100, nil, nil)

// Get user trades
trades, err := client.Trade().GetUserTrades(&symbol, 100, nil, nil)
```

### Advanced Trading Features (v3)

```go
import "github.com/tigusigalpa/bingx-go/v2/services"

// TWAP Orders - Execute large orders with minimal market impact
twapOrder, err := client.Trade().PlaceTWAPOrder(map[string]interface{}{
    "symbol":       "BTC-USDT",
    "side":         "BUY",
    "positionSide": "LONG",
    "quantity":     10.0,
    "duration":     3600, // Execute over 1 hour
    "interval":     60,   // Split into 1-minute intervals
})

// Query TWAP order
twap, err := client.Trade().GetTWAPOrder("twap_order_id", nil)

// List TWAP orders
status := "WORKING"
twapOrders, err := client.Trade().GetTWAPOrders(&symbol, &status, nil, nil, 100, nil)

// Cancel TWAP order
err = client.Trade().CancelTWAPOrder("twap_order_id", nil)

// One-Click Position Reversal - Instantly reverse LONG↔SHORT
result, err := client.Trade().OneClickReversePosition("BTC-USDT", nil)

// Multi-Assets Mode - Portfolio margin across multiple positions
err = client.Trade().SwitchMultiAssetsMode(true, nil)
mode, err := client.Trade().GetMultiAssetsMode(nil)
rules, err := client.Trade().GetMultiAssetsRules(nil)
margin, err := client.Trade().GetMultiAssetsMargin(nil)

// Auto Add Margin (Hedge Mode)
err = client.Trade().SetAutoAddMargin("BTC-USDT", "LONG", true, nil)
```

### Wallet Service - Wallet Management

```go
// Get deposit history
deposits, err := client.Wallet().GetDepositHistory("USDT", nil, nil, nil, 100)

// Get deposit address
address, err := client.Wallet().GetDepositAddress("USDT", "TRC20")

// Get withdrawal history
withdrawals, err := client.Wallet().GetWithdrawalHistory("USDT", nil, nil, nil, 100)

// Create withdrawal
withdrawal, err := client.Wallet().Withdraw("USDT", "TXxx...xxx", 100.0, "TRC20", nil)

// Get all coin info
coins, err := client.Wallet().GetAllCoinInfo()
```

### Spot Account Service - Spot Account

```go
import "github.com/tigusigalpa/bingx-go/v2/services"

// Get spot balance
balance, err := client.SpotAccount().GetBalance()

// Get a combined overview of all wallet types.
// Use AccountType* constants to filter by a single wallet, or pass nil for all.
overview, err := client.SpotAccount().GetAccountOverview(nil)

// Query only the USDT-M perpetual wallet
usdtOverview, err := client.SpotAccount().GetAccountOverview(&services.AccountTypeUSDTMPerp)

// Internal transfer with wallet type constants
// Wallet types: WalletTypeFund=1, WalletTypeStandardFutures=2,
//               WalletTypePerpetualFutures=3, WalletTypeSpot=4
userAccountType := 1 // 1=UID, 2=Phone, 3=Email
userAccount := "123456"
transfer, err := client.SpotAccount().InternalTransfer(
    "USDT",                           // coin
    services.WalletTypeSpot,          // walletType (4 = Spot Account)
    100.0,                            // amount
    userAccountType,                  // userAccountType
    userAccount,                      // userAccount
    nil,                              // callingCode (required when userAccountType=2)
    nil,                              // transferClientID
    nil,                              // recvWindow
)

// Get all spot account balances
allBalances, err := client.SpotAccount().GetAllAccountBalances()

// Deprecated: GetFundBalance is retired and no longer calls the API.
// Use GetAccountOverview instead.
```

**Supported account types** for `GetAccountOverview`:

```go
services.AccountTypeSpotFund     // "sopt"
services.AccountTypeStdFutures   // "stdFutures"
services.AccountTypeCoinMPerp    // "coinMPerp"
services.AccountTypeUSDTMPerp    // "USDTMPerp"
services.AccountTypeCopyTrading  // "copyTrading"
services.AccountTypeGrid         // "grid"
services.AccountTypeWealth       // "eran"
services.AccountTypeC2C          // "c2c"
```

### Spot Trading - Spot Order Management

`SpotAccount()` only covers balances and transfers; `SpotTrade()` is the
dedicated service for placing, cancelling, and querying **spot** orders
(as opposed to `Trade()`, which is for **perpetual futures** orders). Spot
trading buys/sells the underlying asset directly with no leverage or
position side, so its parameters and endpoints differ from `Trade()`.

**Decimal safety:** `SpotOrderRequest.Quantity`, `Price`, and
`QuoteOrderQty` are all `string`, never `float64`. Passing decimals as
`float64` risks silent binary-precision rounding (e.g. `0.1 + 0.2 !=
0.3` in IEEE 754), which can cause rejected orders or subtly wrong fills.
Always format your decimal amounts as exact strings.

```go
import "github.com/tigusigalpa/bingx-go/v2/services"

// Create a limit buy order (typed, validated client-side)
price := "60000"
quantity := "0.001"

order, err := client.SpotTrade().CreateOrderRequest(services.SpotOrderRequest{
    Symbol:   "BTC-USDT",
    Side:     services.SpotSideBuy,
    Type:     services.SpotOrderTypeLimit,
    Quantity: quantity,
    Price:    &price,
})

// Create a market buy order using a quote amount (spend 100 USDT)
quoteOrderQty := "100"
marketOrder, err := client.SpotTrade().CreateOrderRequest(services.SpotOrderRequest{
    Symbol:        "BTC-USDT",
    Side:          services.SpotSideBuy,
    Type:          services.SpotOrderTypeMarket,
    QuoteOrderQty: &quoteOrderQty,
})

// Advanced order types (TAKE_STOP_LIMIT, TAKE_STOP_MARKET, TRIGGER_LIMIT,
// TRIGGER_MARKET) or exchange-specific parameters: use the raw CreateOrder.
order, err = client.SpotTrade().CreateOrder(map[string]interface{}{
    "symbol":     "BTC-USDT",
    "side":       "SELL",
    "type":       "TRIGGER_LIMIT",
    "quantity":   "0.001",
    "price":      "58000",
    "stopPrice":  "59000",
})

// Cancel an order by orderID or clientOrderID
orderID := "123456789"
_, err = client.SpotTrade().CancelOrder("BTC-USDT", &orderID, nil)

// Cancel all open orders for a symbol (nil = all symbols)
_, err = client.SpotTrade().CancelAllOrders(&symbol)

// Cancel a batch of orders
_, err = client.SpotTrade().CancelBatchOrders("BTC-USDT", []string{"111", "222"}, nil)

// Query a single order, current open orders, order history, and fills
order, err = client.SpotTrade().GetOrder("BTC-USDT", &orderID, nil)
openOrders, err := client.SpotTrade().GetOpenOrders(&symbol) // no limit param on this endpoint
history, err := client.SpotTrade().GetOrderHistory(&symbol, 50, nil, nil)
trades, err := client.SpotTrade().GetTrades(&symbol, 100, nil, nil) // symbol is required here
```

**Order amendment:** BingX Spot does not support true in-place order
modification the way Futures does (`Trade().ModifyOrder`, which only
changes an existing order's quantity via `/openApi/swap/v1/trade/amend`).
Instead, the Spot API exposes a native cancel-and-replace endpoint
(`POST /openApi/spot/v1/trade/order/cancelReplace`) that atomically cancels
one order and places a new one in a single signed request. This is exposed
as `AmendOrder`:

```go
// Amend (cancel + replace) an order atomically
newPrice := "61000"
_, err = client.SpotTrade().AmendOrder(
    "BTC-USDT",
    &orderID, nil, // identify the order to cancel: orderID or clientOrderID
    services.SpotCancelReplaceStopOnFailure, // abort if cancel fails; or SpotCancelReplaceAllowFailure
    services.SpotOrderRequest{
        Side:     services.SpotSideBuy,
        Type:     services.SpotOrderTypeLimit,
        Quantity: "0.001",
        Price:    &newPrice,
    },
)
```

If you'd rather do it manually (or need it split into two independent,
auditable calls), the safe workflow is `CancelOrder` followed by
`CreateOrder`/`CreateOrderRequest`, checking the cancel result before
placing the new order.

**Not implemented — spot test orders:** Unlike `Trade().CreateTestOrder`
(Futures `POST /openApi/swap/v2/trade/order/test`), the BingX Spot API does
not expose a dry-run order-validation endpoint. `SpotTradeService`
therefore has no `CreateTestOrder` method; validate orders client-side via
`CreateOrderRequest`'s built-in checks instead.

### Coin-M Perpetual Futures

```go
// Get Coin-M market data
ticker, err := client.CoinM().Market().GetTicker("BTC-USD")

// Get Coin-M contracts
contracts, err := client.CoinM().Market().GetContracts()

// Create Coin-M order (v2 endpoint)
order, err := client.CoinM().Trade().CreateOrder(map[string]interface{}{
    "symbol":       "BTC-USD",
    "side":         "BUY",
    "positionSide": "LONG",
    "type":         "MARKET",
    "quantity":     100,
})

// Get Coin-M positions
positions, err := client.CoinM().Trade().GetPositions(nil)

// Get Coin-M balance
balance, err := client.CoinM().Trade().GetBalance()

// Enhanced Coin-M Features (v3)

// Position Risk
risk, err := client.CoinM().Trade().GetPositionRisk(&symbol, nil)

// Income History
incomeType := "REALIZED_PNL"
income, err := client.CoinM().Trade().GetIncomeHistory(&symbol, &incomeType, nil, nil, 100, nil)

// Funding Rate History
fundingHistory, err := client.CoinM().Market().GetFundingRateHistory("BTC-USD", 100)

// Mark Price
markPrice, err := client.CoinM().Market().GetMarkPrice("BTC-USD")

// Index Price
indexPrice, err := client.CoinM().Market().GetIndexPrice("BTC-USD")

// Recent Trades
trades, err := client.CoinM().Market().GetRecentTrades("BTC-USD", 100)
```

### TradFi (Traditional Finance)

Access stock tokens, forex pairs, commodities, and stock indices traded as perpetual swaps.

```go
// Get TradFi client
tradfi := client.TradFi()

// Get stock symbols (TSLA, AAPL, NVDA, etc.)
stocks, err := tradfi.Market().GetStockSymbols()

// Get forex symbols (EUR-USD, GBP-USD, etc.)
forex, err := tradfi.Market().GetForexSymbols()

// Get commodity symbols (GOLD, SILVER, OIL, etc.)
commodities, err := tradfi.Market().GetCommoditySymbols()

// Get index symbols (SPX, DJI, NDX, etc.)
indices, err := tradfi.Market().GetIndexSymbols()

// Get 24h ticker for a stock
ticker, err := tradfi.Market().GetTicker("TSLA-USDT")

// Get latest price for forex
price, err := tradfi.Market().GetLatestPrice("EUR-USDT")

// Get order book depth
depth, err := tradfi.Market().GetDepth("GOLD-USDT", 20)

// Get klines (candlestick data)
klines, err := tradfi.Market().GetKlines("AAPL-USDT", "1h", 100, nil, nil)

// Get funding rate
funding, err := tradfi.Market().GetFundingRate("EUR-USDT")

// Get open interest
oi, err := tradfi.Market().GetOpenInterest("TSLA-USDT")

// Create a stock order
order, err := tradfi.Trade().CreateOrder(map[string]interface{}{
    "symbol":       "TSLA-USDT",
    "side":         "BUY",
    "type":         "LIMIT",
    "positionSide": "LONG",
    "price":        250.0,
    "quantity":     1.0,
    "timeInForce":  "GTC",
})

// Create a TWAP order (for large trades)
twap, err := tradfi.Trade().PlaceTWAPOrder(map[string]interface{}{
    "symbol":   "AAPL-USDT",
    "side":     "BUY",
    "quantity": 100.0,
    "duration": 3600,  // Total duration in seconds
    "interval": 60,    // Seconds between sub-orders
})

// Get positions
positions, err := tradfi.Account().GetPositions(nil)

// Get account balance
balance, err := tradfi.Account().GetBalance()

// Get position risk (includes liquidation price)
risk, err := tradfi.Account().GetPositionRisk(&symbol)

// Get income history (PNL, funding fees, commissions)
incomeType := "REALIZED_PNL"
income, err := tradfi.Account().GetIncomeHistory(&symbol, &incomeType, nil, nil, 100)

// Set hedge mode
mode, err := tradfi.Account().SetPositionMode(true)  // true = hedge mode

// Set leverage
leverage, err := tradfi.Trade().SetLeverage("TSLA-USDT", 10, nil)
```

#### TradFi Trading Notes

- **Stock Hours**: US stocks trade Mon–Fri ~09:30-16:00 ET
- **Forex Hours**: 24/5 trading (Sun 17:00 ET – Fri 17:00 ET)
- **Commodities**: Vary by instrument; GOLD/SILVER trade nearly 24h
- **Leverage**: Typically lower than crypto (5x-20x for stocks, 50x-100x for forex)
- **Funding Rates**: Applied every 8 hours (00:00, 08:00, 16:00 UTC)

### Sub-Account Management

```go
import "github.com/tigusigalpa/bingx-go/v2/services"

// Create sub-account
result, err := client.SubAccount().CreateSubAccount("sub_account_001")

// Get sub-account list
subAccounts, err := client.SubAccount().GetSubAccountList(nil, 1, 10)

// Create API key for sub-account
apiKey, err := client.SubAccount().CreateSubAccountAPIKey(
    "sub_account_001",
    "Trading Bot",
    map[string]bool{"spot": true, "futures": true},
    nil, // IP whitelist (optional)
)

// Sub-account internal transfer with wallet type constants
// Wallet types: SubAccountWalletTypeFund=1, SubAccountWalletTypeStandardFutures=2,
//               SubAccountWalletTypePerpetualFutures=3, SubAccountWalletTypeSpot=15
userAccountType := 1 // 1=UID, 2=Phone, 3=Email
userAccount := "12345678"
transfer, err := client.SubAccount().SubAccountInternalTransfer(
    "USDT",                                  // coin
    services.SubAccountWalletTypeSpot,       // walletType (15 = Spot Account)
    100.0,                                   // amount
    userAccountType,                         // userAccountType
    userAccount,                             // userAccount
    nil,                                     // callingCode
    nil,                                     // transferClientID
    nil,                                     // recvWindow
)

// Sub-Mother Account Asset Transfer (master account only)
fromUID := int64(123456)
toUID := int64(789012)
transfer, err = client.SubAccount().SubMotherAccountAssetTransfer(
    "USDT",                                  // assetName
    100.0,                                   // transferAmount
    fromUID,                                 // fromUID
    1,                                       // fromType (1=Parent, 2=Sub)
    1,                                       // fromAccountType (1=Funding, 2=Standard futures, 3=Perpetual, 15=Spot)
    toUID,                                   // toUID
    2,                                       // toType (1=Parent, 2=Sub)
    15,                                      // toAccountType (15=Spot)
    "Transfer to sub-account",               // remark
    nil,                                     // recvWindow
)

// Query transferable amount (master account only)
transferable, err := client.SubAccount().GetSubMotherAccountTransferableAmount(
    fromUID,                                 // fromUID
    1,                                       // fromAccountType
    toUID,                                   // toUID
    15,                                      // toAccountType (Spot)
    nil,                                     // recvWindow
)

// Query transfer history (master account only)
var pageID, pagingSize int
pageID = 1
pagingSize = 50
history, err := client.SubAccount().GetSubMotherAccountTransferHistory(
    fromUID,                                 // uid
    nil,                                     // transferType (optional)
    nil,                                     // tranID (optional)
    nil,                                     // startTime (optional)
    nil,                                     // endTime (optional)
    &pageID,                                 // pageID
    &pagingSize,                             // pagingSize
    nil,                                     // recvWindow
)

// Get sub-account assets
assets, err := client.SubAccount().GetSubAccountAssets("12345678")
```

### Copy Trading Operations

```go
// Get current track orders
orders, err := client.CopyTrading().GetCurrentTrackOrders("BTC-USDT")

// Close track order
result, err := client.CopyTrading().CloseTrackOrder("1252864099381234567")

// Set take profit and stop loss
stopLoss := 48000.0
takeProfit := 52000.0
err = client.CopyTrading().SetTPSL("1252864099381234567", &stopLoss, &takeProfit)

// Get profit summary
summary, err := client.CopyTrading().GetProfitSummary()

// Set commission rate
err = client.CopyTrading().SetCommission(5.0) // 5% commission
```

### WebSocket Streaming

#### Market Data Stream

```go
// Create market data stream
stream := client.NewMarketDataStream()

// Connect to WebSocket
if err := stream.Connect(); err != nil {
    log.Fatal(err)
}
defer stream.Disconnect()

// Register message handler
stream.OnMessage(func(data map[string]interface{}) {
    fmt.Printf("Received: %+v\n", data)
})

// Subscribe to various data types
stream.SubscribeTrade("BTC-USDT")
stream.SubscribeKline("BTC-USDT", "1m")
stream.SubscribeDepth("BTC-USDT", 20)
stream.SubscribeTicker("BTC-USDT")
stream.SubscribeBookTicker("BTC-USDT")

// Start listening (blocking)
stream.Listen()
```

#### Account Data Stream

```go
// Generate listen key
resp, err := client.ListenKey().Generate()
if err != nil {
    log.Fatal(err)
}
listenKey := resp["listenKey"].(string)

// Create account data stream
stream := client.NewAccountDataStream(listenKey)

if err := stream.Connect(); err != nil {
    log.Fatal(err)
}
defer stream.Disconnect()

// Listen for account updates
stream.OnAccountUpdate(func(eventType string, data map[string]interface{}) {
    fmt.Printf("Event [%s]: %+v\n", eventType, data)
})

// Listen for specific update types
stream.OnBalanceUpdate(func(balances interface{}) {
    fmt.Printf("Balance: %+v\n", balances)
})

stream.OnPositionUpdate(func(positions interface{}) {
    fmt.Printf("Positions: %+v\n", positions)
})

stream.OnOrderUpdate(func(order interface{}) {
    fmt.Printf("Order: %+v\n", order)
})

// Start listening
stream.Listen()
```

For detailed WebSocket documentation, see [websocket/README.md](websocket/README.md).

---

## Advanced Features

### Commission Calculation

```go
// Calculate futures commission
commission := client.Trade().CalculateFuturesCommission(100.0, 10, nil)
fmt.Printf("Commission: %.6f USDT\n", commission.Commission)
fmt.Printf("Net Position Value: %.2f USDT\n", commission.NetPositionValue)

// Quick commission amount
amount := client.Trade().GetCommissionAmount(100.0, 10)
fmt.Printf("Commission Amount: %.6f USDT\n", amount)
```

### Batch Operations

```go
// Create multiple orders at once
orders := []map[string]interface{}{
    {
        "symbol":       "BTC-USDT",
        "side":         "BUY",
        "type":         "LIMIT",
        "positionSide": "LONG",
        "price":        50000.0,
        "quantity":     0.001,
    },
    {
        "symbol":       "ETH-USDT",
        "side":         "BUY",
        "type":         "LIMIT",
        "positionSide": "LONG",
        "price":        3000.0,
        "quantity":     0.01,
    },
}

result, err := client.Trade().CreateBatchOrders(orders)

// Cancel multiple orders
orderIDs := []string{"123456789", "987654321"}
err = client.Trade().CancelBatchOrders("BTC-USDT", orderIDs, nil, nil, nil)
```

### Time-Based Queries

```go
import "time"

// Get trades from last 24 hours
startTime := time.Now().Add(-24 * time.Hour).UnixMilli()
endTime := time.Now().UnixMilli()

trades, err := client.Trade().GetUserTrades(
    &symbol,
    100,
    &startTime,
    &endTime,
)

// Get historical klines
klines, err := client.Market().GetKlines(
    "BTC-USDT",
    "1h",
    100,
    &startTime,
    &endTime,
)
```

---

## What's New in v3

### 🎯 Key Highlights

**BingX API v3** brings powerful new features for institutional-grade trading:

#### 1. TWAP Orders (Time-Weighted Average Price)
Execute large orders with minimal market impact by splitting them into smaller chunks over time.

```go
// Execute 10 BTC over 1 hour in 1-minute intervals
client.Trade().PlaceTWAPOrder(map[string]interface{}{
    "symbol":   "BTC-USDT",
    "quantity": 10.0,
    "duration": 3600,
    "interval": 60,
})
```

#### 2. Multi-Assets Margin Mode
Optimize margin usage across multiple positions with portfolio margin.

```go
// Enable multi-assets mode
client.Trade().SwitchMultiAssetsMode(true, nil)

// Query margin rules and usage
rules, _ := client.Trade().GetMultiAssetsRules(nil)
margin, _ := client.Trade().GetMultiAssetsMargin(nil)
```

#### 3. One-Click Position Reversal
Instantly reverse your position from LONG to SHORT or vice versa.

```go
// Reverse position with one call
client.Trade().OneClickReversePosition("BTC-USDT", nil)
// Before: LONG 1.0 BTC → After: SHORT 1.0 BTC
```

#### 4. Advanced Order Types
- **TRIGGER_LIMIT** - Trigger orders with limit execution
- **TRAILING_STOP_MARKET** - Dynamic stop-loss that follows price
- **TRAILING_TP_SL** - Trailing take-profit and stop-loss

```go
import "github.com/tigusigalpa/bingx-go/v2/services"

client.Trade().CreateOrder(map[string]interface{}{
    "type":             services.OrderTypeTrailingStopMarket,
    "activationPrice":  50000.0,
    "callbackRate":     1.0, // 1% trailing
})
```

#### 5. Enhanced Risk Management

**Position Risk Metrics**:
```go
risk, _ := client.Account().GetPositionRisk(&symbol, nil)
// Returns: liquidation price, leverage, margin ratio, unrealized PnL
```

**Income/PnL Tracking**:
```go
incomeType := "REALIZED_PNL"
income, _ := client.Account().GetIncomeHistory(&symbol, &incomeType, nil, nil, 100, nil)
```

**Commission Analysis**:
```go
commissions, _ := client.Account().GetCommissionHistory("BTC-USDT", nil, nil, 100, nil)
```

#### 6. Enhanced Market Data
- Open Interest & History
- Funding Rate Information
- Book Ticker (Best Bid/Ask)
- Index Price
- Mark Price

```go
// Real-time open interest
oi, _ := client.Market().GetOpenInterest("BTC-USDT")

// Historical open interest
oiHistory, _ := client.Market().GetOpenInterestHistory("BTC-USDT", "5m", 100, nil, nil)

// Best bid/ask prices
bookTicker, _ := client.Market().GetBookTicker(&symbol)
```

### 📊 v3 Statistics

- **50+ new methods** across all services (including TradFi)
- **260+ total API methods** (up from 220+)
- **3 new order types** for advanced strategies
- **100% backward compatible** - no breaking changes
- **Full Coin-M v2 support** with enhanced features
- **Full TradFi support** — Trade stocks, forex, commodities, and indices

### 🔄 Migration from Previous Versions

No code changes required! All existing code continues to work. New features are opt-in.

For detailed migration guide, see [API_V3_MIGRATION.md](API_V3_MIGRATION.md)

---

## Configuration

```go
client := bingx.NewClient(
    apiKey,
    apiSecret,
    // Set custom base URI (default: https://open-api.bingx.com)
    bingx.WithBaseURI("https://open-api.bingx.com"),
    
// Set source key for tracking (optional)
    bingx.WithSourceKey("my-trading-bot-v1"),
    
// Set signature encoding: "base64" or "hex" (default: base64)
    binHMACWithSignatureEncoding(hsx4"istBingX-compatible .
   // "" is still supported for backward compatibility only.
)hx
```

### Environment Variables

```bash
# Recommended: Store credentials in environment variables
export BINGX_API_KEY="your_api_key_here"
export BINGX_API_SECRET="your_api_secret_here"
export BINGX_SOURCE_KEY="optional_source_key"
```

```go
import "os"

client := bingx.NewClient(
    os.Getenv("BINGX_API_KEY"),
    os.Getenv("BINGX_API_SECRET"),
    bingx.WithSourceKey(os.Getenv("BINGX_SOURCE_KEY")),
)
```

### Demo Trading Configuration

For demo trading in the VST (Virtual Simulation Trading) environment:

```go
// Method 1: Use dedicated demo client constructor
demoClient := bingx.NewDemoClient(
    "YOUR_API_KEY",
    "YOUR_API_SECRET",
    bingx.WithSourceKey("demo-trading-bot"),
)

// Method 2: Use demo environment option
demoClient := bingx.NewClient(
    "YOUR_API_KEY",
    "YOUR_API_SECRET",
    bingx.WithDemoEnvironment(),
)

// Method 3: Manually set VST endpoint
demoClient := bingx.NewClient(
    "YOUR_API_KEY",
    "YOUR_API_SECRET",
    bingx.WithBaseURI("https://open-api-vst.bingx.com"),
)
```

**Check Environment:**
```go
fmt.Printf("Endpoint: %s\n", demoClient.GetEndpoint())
// Output: https://open-api-vst.bingx.com (demo) or https://open-api.bingx.com (live)
```

**VST Status Check:**
```go
// Get demo trading information
vstInfo, err := demoClient.Trade().GetVst(nil)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("VST Info: %+v\n", vstInfo)
```

### Timeout Configuration

```go
// The HTTP client uses default timeouts:
// - Connection timeout: 10 seconds
// - Request timeout: 30 seconds

// For custom timeout, modify the HTTP client in http/client.go
```

---

## API Reference

### Client Methods

| Method                                            | Description                       | Returns                |
|---------------------------------------------------|-----------------------------------|------------------------|
| `NewClient(apiKey, apiSecret string, options...)` | Create new BingX client           | `*Client`              |
| `NewDemoClient(apiKey, apiSecret string, options...)` | Create demo trading client (VST)  | `*Client`              |
| `client.Market()`                                 | Access market data service        | `*MarketService`       |
| `client.Account()`                                | Access account management service | `*AccountService`      |
| `client.Trade()`                                  | Access trading operations service | `*TradeService`        |
| `client.Contract()`                               | Access contract service           | `*ContractService`     |
| `client.ListenKey()`                              | Access WebSocket auth service     | `*ListenKeyService`    |
| `client.Wallet()`                                 | Access wallet operations service  | `*WalletService`       |
| `client.SpotAccount()`                            | Access spot account service       | `*SpotAccountService`  |
| `client.SubAccount()`                             | Access sub-account service        | `*SubAccountService`   |
| `client.CopyTrading()`                            | Access copy trading service       | `*CopyTradingService`  |
| `client.CoinM()`                                  | Access Coin-M futures client      | `*CoinMClient`         |
| `client.TradFi()`                                 | Access TradFi client (stocks, forex, commodities) | `*TradFiClient`        |
| `client.NewMarketDataStream()`                    | Create market data WebSocket      | `*MarketDataStream`    |
| `client.NewAccountDataStream(listenKey)`          | Create account data WebSocket     | `*AccountDataStream`   |
| `client.GetHTTPClient()`                          | Get underlying HTTP client        | `*http.BaseHTTPClient` |
| `client.GetEndpoint()`                            | Get API endpoint URL              | `string`               |
| `client.GetAPIKey()`                              | Get configured API key            | `string`               |

### Service Overview

<details>
<summary><b>Market Service Methods</b></summary>

- `GetFuturesSymbols()` - Get all futures trading symbols
- `GetSpotSymbols()` - Get all spot trading symbols
- `GetAllSymbols()` - Get both spot and futures symbols
- `GetLatestPrice(symbol)` - Get latest price for a symbol
- `GetSpotLatestPrice(symbol)` - Get latest spot price
- `GetDepth(symbol, limit)` - Get order book depth
- `GetSpotDepth(symbol, limit)` - Get spot order book
- `GetKlines(symbol, interval, limit, startTime, endTime)` - Get candlestick data
- `GetSpotKlines(...)` - Get spot candlestick data
- `Get24hrTicker(symbol)` - Get 24hr ticker statistics
- `GetSpot24hrTicker(symbol)` - Get spot 24hr ticker
- `GetFundingRateHistory(symbol, limit)` - Get funding rate history
- `GetMarkPrice(symbol)` - Get mark price
- `GetPremiumIndexKlines(...)` - Get premium index klines
- `GetAggregateTrades(...)` - Get aggregate trades
- `GetRecentTrades(symbol, limit)` - Get recent trades
- `GetServerTime()` - Get server time
- `GetContinuousKlines(...)` - Get continuous contract klines
- `GetIndexPriceKlines(...)` - Get index price klines
- `GetTopLongShortRatio(...)` - Get long/short ratio
- `GetHistoricalTopLongShortRatio(...)` - Get historical ratios
- `GetBasis(...)` - Get basis data

</details>

<details>
<summary><b>Account Service Methods</b></summary>

- `GetBalance()` - Get account balance
- `GetPositions(symbol)` - Get positions
- `GetAccountInfo()` - Get account information
- `GetTradingFees(symbol)` - Get trading fees
- `GetMarginMode(symbol)` - Get margin mode
- `SetMarginMode(symbol, mode)` - Set margin mode
- `GetLeverage(symbol, recvWindow)` - Get leverage
- `SetLeverage(symbol, side, leverage, recvWindow)` - Set leverage
- `GetPositionMargin(symbol)` - Get position margin
- `SetPositionMargin(symbol, positionSide, amount, type)` - Set position margin
- `GetBalanceHistory(coin, limit)` - Get balance history
- `GetAccountPermissions()` - Get API permissions
- `GetAPIKey()` - Get API key info
- `GetUserCommissionRates(symbol)` - Get commission rates
- `GetAPIRateLimits()` - Get rate limits
- `GetDepositHistory(coin, limit)` - Get deposit history
- `GetWithdrawHistory(coin, limit)` - Get withdrawal history
- `GetAssetDetails(asset)` - Get asset details
- `GetAllAssets()` - Get all assets
- `GetFundingWallet(asset)` - Get funding wallet
- `DustTransfer(assets)` - Convert dust to BNB

</details>

<details>
<summary><b>Trade Service Methods</b></summary>

- `CreateOrder(params)` - Create new order
- `ModifyOrder(...)` - Modify existing order
- `CreateTestOrder(params)` - Create test order (no execution)
- `CloseAllPositions(symbol, ...)` - Close all positions
- `GetMarginType(symbol, ...)` - Get margin type
- `ChangeMarginType(symbol, type, ...)` - Change margin type
- `GetLeverage(symbol, ...)` - Get leverage
- `SetLeverage(symbol, leverage, ...)` - Set leverage
- `CreateBatchOrders(orders)` - Create multiple orders
- `CancelOrder(symbol, orderID, ...)` - Cancel order
- `CancelAllOrders(...)` - Cancel all orders
- `CancelBatchOrders(...)` - Cancel multiple orders
- `GetOrder(symbol, orderID)` - Get order details
- `GetOpenOrders(symbol, limit)` - Get open orders
- `GetOrderHistory(...)` - Get order history
- `GetFilledOrders(...)` - Get filled orders
- `GetUserTrades(...)` - Get user trades
- `ChangeLeverage(symbol, side, leverage, ...)` - Change leverage
- `CalculateFuturesCommission(margin, leverage, rate)` - Calculate commission
- `GetCommissionAmount(margin, leverage)` - Get commission amount
- `GetVst(recvWindow)` - Get VST (Virtual Simulation Trading) information

</details>

### Response Format

All API methods return `(map[string]interface{}, error)`:

```go
response, err := client.Market().GetLatestPrice("BTC-USDT")
if err != nil {
    // Handle error
}

// Access response data
if data, ok := response["data"].(map[string]interface{}); ok {
    price := data["price"]
    fmt.Printf("Price: %v\n", price)
}
```

---

## Error Handling

```go
import "github.com/tigusigalpa/bingx-go/v2/errors"

// Handle errors
order, err := client.Trade().CreateOrder(params)
if err != nil {
    switch e := err.(type) {
    case *errors.AuthenticationException:
        log.Printf("Authentication error: %v", e)
    case *errors.RateLimitException:
        log.Printf("Rate limit exceeded: %v", e)
    case *errors.InsufficientBalanceException:
        log.Printf("Insufficient balance: %v", e)
    case *errors.APIException:
        log.Printf("API error [%s]: %v", e.APICode, e)
    default:
        log.Printf("Error: %v", err)
    }
    return
}
```

### Error Types

- `BingXException` - Base exception for all errors
- `APIException` - API-level errors with error codes
- `AuthenticationException` - Authentication failures
- `RateLimitException` - Rate limit exceeded
- `InsufficientBalanceException` - Insufficient balance errors

---

## Best Practices

### Security

```go
// DO: Use environment variables for credentials
apiKey := os.Getenv("BINGX_API_KEY")
apiSecret := os.Getenv("BINGX_API_SECRET")

// ❌ DON'T: Hardcode credentials
apiKey := "your_api_key_here" // Never do this!

// ✅ DO: Restrict API key permissions
// Only enable permissions you need (read-only for monitoring, etc.)

// ✅ DO: Use IP whitelist
// Configure IP restrictions in BingX API settings
```

### Error Handling

```go
// ✅ DO: Always check errors
result, err := client.Trade().CreateOrder(params)
if err != nil {
    // Handle specific error types
    switch e := err.(type) {
    case *errors.RateLimitException:
        // Implement exponential backoff
        time.Sleep(time.Second * 5)
    case *errors.InsufficientBalanceException:
        // Log and alert
        log.Error("Insufficient balance")
    default:
        // Generic error handling
        log.Error(err)
    }
    return
}

// ❌ DON'T: Ignore errors
result, _ := client.Trade().CreateOrder(params) // Bad practice
```

### Performance

```go
// ✅ DO: Reuse client instances
var globalClient *bingx.Client

func init() {
    globalClient = bingx.NewClient(apiKey, apiSecret)
}

// ❌ DON'T: Create new client for each request
func makeRequest() {
    client := bingx.NewClient(apiKey, apiSecret) // Wasteful
    client.Market().GetLatestPrice("BTC-USDT")
}

// ✅ DO: Use batch operations when possible
orders := []map[string]interface{}{...}
client.Trade().CreateBatchOrders(orders)

// ❌ DON'T: Make individual requests in loops
for _, order := range orders {
    client.Trade().CreateOrder(order) // Inefficient
}
```

### Concurrency

```go
// ✅ DO: Client is thread-safe
var wg sync.WaitGroup
for _, symbol := range symbols {
    wg.Add(1)
    go func(s string) {
        defer wg.Done()
        price, _ := client.Market().GetLatestPrice(s)
        // Process price
    }(symbol)
}
wg.Wait()
```

---

## Testing

The BingX Go library includes a comprehensive test suite covering all major components and functionality.

### Test Coverage

The test suite includes **14 test files** with **100+ test functions** covering:

- Client initialization and configuration
- HTTP client (signature generation, query building, error handling)
- All service methods (Market, Trade, Account, Wallet, etc.)
- WebSocket streams (market data, account data)
- Error handling and custom exceptions
- Parameter validation and edge cases
- Commission calculations
- Batch operations

### Quick Start

```bash
# Run all tests
go test ./...

# Run with verbose output
go test -v ./...

# Run with coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Test specific package
go test ./services -v
go test ./http -v
go test ./websocket -v
```

### Using Make

The library includes a `Makefile` for convenient test execution:

```bash
# Run all tests
make test

# Run with verbose output
make test-verbose

# Generate coverage report
make test-coverage

# Generate HTML coverage report
make coverage-html

# Test specific packages
make test-services    # Test services only
make test-http        # Test HTTP client only
make test-websocket   # Test WebSocket only

# Run specific test function
make test-func FUNC=TestNewClient

# Format code
make fmt

# Run all checks (format, lint, test)
make check
```

### Test Files

**Core Tests:**
- `client_test.go` - Client initialization, configuration, service accessors
- `http/client_test.go` - HTTP client, HMAC signatures, query building

**Service Tests:**
- `services/market_test.go` - Market data operations
- `services/trade_test.go` - Trading operations, commission calculations
- `services/account_test.go` - Account management
- `services/wallet_test.go` - Wallet operations
- `services/listenkey_test.go` - Listen key management
- `services/contract_test.go` - Contract services

**WebSocket Tests:**
- `websocket/market_data_stream_test.go` - Market data subscriptions
- `websocket/account_data_stream_test.go` - Account data callbacks

**Error Tests:**
- `errors/errors_test.go` - Custom exception handling

### Example Tests

#### Testing Client Initialization

```go
func TestNewClient(t *testing.T) {
    client := bingx.NewClient("test-key", "test-secret")
    
    if client == nil {
        t.Fatal("Expected client to be created")
    }
    
    if client.GetAPIKey() != "test-key" {
        t.Error("API key mismatch")
    }
}
```

#### Testing Commission Calculations

```go
func TestCommissionCalculation(t *testing.T) {
    client := bingx.NewClient("", "")
    
    result := client.Trade().CalculateFuturesCommission(100.0, 10, nil)
    
    if result.PositionValue != 1000.0 {
        t.Errorf("Expected position value 1000.0, got %f", result.PositionValue)
    }
    
    if result.Commission != 0.45 {
        t.Errorf("Expected commission 0.45, got %f", result.Commission)
    }
}
```

#### Testing Parameter Validation

```go
func TestSetLeverageValidation(t *testing.T) {
    client := bingx.NewClient("key", "secret")
    
    // Test invalid leverage (too high)
    _, err := client.Trade().SetLeverage("BTC-USDT", 126, nil, nil)
    if err == nil {
        t.Error("Expected error for leverage > 125")
    }
    
    // Test valid leverage
    _, err = client.Trade().SetLeverage("BTC-USDT", 50, nil, nil)
    // Will skip if no mock server, but validates parameters
}
```

### Integration Testing

Most tests are designed as unit tests that validate:
- Correct initialization
- Parameter validation
- Expected behavior of utility functions
- Error handling for invalid inputs

Integration tests that require actual API calls are marked to skip:

```go
func TestGetBalance(t *testing.T) {hx
    client := http.NewBaseHTTPClient("key", "secret", "https://api.test.com", "", "base64")
    service := NewAccountService(client)
    
    _, err := service.GetBalance()
    if err == nil {
        t.Skip("Skipping test - would require mock HTTP server")
    }
}
```

### Continuous Integration

The library includes a GitHub Actions workflow (`.github/workflows/test.yml`) that:

- Runs tests on every push and pull request
- Tests against multiple Go versions (1.21, 1.22)
- Generates coverage reports
- Runs linting checks
- Uploads coverage to Codecov

### Test Documentation

For detailed testing information, see:

- **[TESTING.md](TESTING.md)** - Comprehensive testing guide with examples
- **[TEST_SUMMARY.md](TEST_SUMMARY.md)** - Complete test coverage overview
- **[testdata/README.md](testdata/README.md)** - Test fixtures and mock data guide

### Writing Tests

When contributing, follow these patterns:

```go
// Table-driven tests for multiple scenarios
func TestBuildQuery(t *testing.T) {
    tests := []struct {
        name     string
        params   map[string]interface{}
        expected string
    }{
        {"Empty params", map[string]interface{}{}, ""},
        {"String param", map[string]interface{}{"symbol": "BTC-USDT"}, "symbol=BTC-USDT"},
        {"Multiple params", map[string]interface{}{"symbol": "BTC-USDT", "limit": 100}, "limit=100&symbol=BTC-USDT"},
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := buildQuery(tt.params)
            if result != tt.expected {
                t.Errorf("Expected %s, got %s", tt.expected, result)
            }
        })
    }
}
```

### Test Utilities

The test suite includes:

- **Makefile** - Quick test commands
- **test.sh** - Bash script with options for verbose output and coverage
- **GitHub Actions workflow** - Automated CI/CD testing
- **testdata/** - Directory for test fixtures and mock data

### Coverage Goals

Current test coverage focuses on:
- All public APIs and methods
- Parameter validation
- Error handling paths
- Edge cases and boundary conditions
- Commission calculations
- Signature generation

Future enhancements will include:
- Mock HTTP server for integration tests
- WebSocket mock server
- Performance benchmarks
- Concurrent request testing

---

## Performance

- **Request Latency**: < 50ms (network dependent)
- **Memory Usage**: ~2MB per client instance
- **Concurrent Requests**: Supports 1000+ concurrent goroutines
- **Signature Generation**: < 1ms per request

### Optimization Tips

1. **Connection Pooling**: HTTP client reuses connections automatically
2. **Batch Operations**: Use batch methods for multiple orders
3. **Caching**: Cache market data locally when appropriate
4. **Rate Limiting**: Implement client-side rate limiting to avoid API limits

```go
// Example: Rate-limited requests
import "golang.org/x/time/rate"

limiter := rate.NewLimiter(rate.Limit(10), 1) // 10 requests per second

func makeRequest() {
    limiter.Wait(context.Background())
    client.Market().GetLatestPrice("BTC-USDT")
}
```

---

## Roadmap

### Planned (v1.1.0)

- Order builder with fluent interface
- Rate limiter middleware
- Request/response logging
- Retry with exponential backoff

### Future (v2.0.0)

- Built-in technical indicators
- Strategy backtesting framework
- Portfolio management tools
- Event-driven architecture

---

## Creating API Keys

1. Login to your BingX account
2. Go to [API Management](https://bingx.com/en-US/accounts/api)
3. Create API key, configure permissions (Read, Trade)
4. Set IP whitelist (recommended)
5. Save your API Key and Secret Key — the secret is shown only once

---

## Contributing

### Development setup

```bash
# Clone the repository
git clone https://github.com/tigusigalpa/bingx-go.git
cd bingx-go

# Install dependencies
go mod download

# Run tests
go test ./...

# Run linter
golangci-lint run
```

### Pull Request Process

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

### Code style

- Follow [Effective Go](https://golang.org/doc/effective_go) guidelines
- Use `gofmt` for formatting
- Add comments for exported functions

---

## License

MIT License — see [LICENSE](LICENSE).

## Disclaimer

This SDK is provided "as-is". Cryptocurrency trading carries significant financial risk. Always test in a sandbox
environment before production use. The authors are not responsible for any financial losses.

## Links

- [GitHub Repository](https://github.com/tigusigalpa/bingx-go)
- [Issues](https://github.com/tigusigalpa/bingx-go/issues)
- [BingX API Documentation v3](https://bingx-api.github.io/docs-v3/)
- [GoDoc](https://pkg.go.dev/github.com/tigusigalpa/bingx-go/v2)

bingx-go

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README