# go-binance: a Binance SDK split across several API surfaces

> go-binance is a Go SDK for the Binance API covering the spot REST endpoints, the websocket streams and the user data stream, plus separate packages for USDT-M futures, Coin-M delivery, options and portfolio margin. It is chain-style and dependency-light, and it is a v2 module whose import path does not match the repository name.

**ccxt/go-binance** — A Go SDK for Binance API

- Repository: https://github.com/ccxt/go-binance
- Stars: 1,905 · Forks: 781
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ccxt-go-binance

## The import path is not the repository name

The first practical detail is a naming mismatch that costs people an afternoon. The repository lives under ccxt/go-binance, but the module and the import path are github.com/adshao/go-binance/v2, and the documentation badges for the build, the GoDoc page and the coverage report all point at the adshao path. The v1 API is kept on a separate v1 branch with its own import path, so the module suffix is a genuine major version boundary rather than decoration. This matters in practice: your go.mod, your import lines and your vendored path all carry the adshao name, and if you are following a tutorial or an issue tracker keyed to the repository URL, the two will not match. The package layout is the second thing to understand. The root package covers spot and the interfaces described in the spot changelog, while futures, delivery and options are optional sub-packages that you import only if you need them.

## One client per market, one service per endpoint

The client construction is deliberately thin. You create a client for the API key and secret key from your Binance account, and separate constructors exist for the other surfaces:

```golang
var (
    apiKey = "your api key"
    secretKey = "your secret key"
)
client := binance.NewClient(apiKey, secretKey)
futuresClient := binance.NewFuturesClient(apiKey, secretKey)    // USDT-M Futures
deliveryClient := binance.NewDeliveryClient(apiKey, secretKey)  // Coin-M Futures
```

The architecture is one service type per REST endpoint. A service instance stands for a single endpoint and is created by a client.NewXXXService function, then configured with chain-style setters, and the chain ends with Do(), which is what sends the HTTP request. Nothing is sent until Do is called, so a service object is a request builder. The public data services take no credentials, which is why a market data consumer can use the same client with an empty key pair. The setters are strongly typed for the values that matter, with named constants for the enumerations, for example binance.SideTypeBuy, binance.OrderTypeLimit and binance.TimeInForceTypeGTC, which removes the stringly-typed argument that plagues hand-written clients.

## Order placement, and the Test() escape hatch

The order example shows the whole shape of the library in six lines. You pick the service, set the symbol, set the side, type, time in force, quantity and price, and then call Do with a context:

```golang
order, err := client.NewCreateOrderService().Symbol("BNBETH").
        Side(binance.SideTypeBuy).Type(binance.OrderTypeLimit).
        TimeInForce(binance.TimeInForceTypeGTC).Quantity("5").
        Price("0.0030000").Do(context.Background())
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(order)
```

The comment underneath is the detail worth internalising: use Test() instead of Do() for testing. A service therefore has a test path that does not place a live order, which is the difference between a unit test that talks to the exchange and one that does not. Every call takes a context.Context, so cancellation and deadlines are part of the API rather than something you bolt on, and the same pattern holds for reading. Getting an order uses NewGetOrderService with a symbol and an order id, cancelling uses NewCancelOrderService, and the list endpoints are NewListOpenOrdersService and NewListOrdersService. Quantities and prices are passed as strings, which is worth noting if you are used to typed numeric fields: the SDK does not do decimal arithmetic for you.

## Market data services and the websocket side

The read path covers the data you would expect from a spot market data feed. NewListPricesService returns the ticker prices, NewDepthService returns the order book for a symbol, NewKlinesService returns candlesticks with an Interval, and NewAggTradesService returns aggregate trades bounded by a StartTime and an EndTime in milliseconds, as the example with the timestamps 1508673256594 and 1508673256595 shows. Account state is reached with NewGetAccountService, and the user data stream is opened with NewStartUserStreamService. The websocket side is a separate mechanism and the documentation makes a point of it: you do not need a client for the websocket API. The repository's own example directory reflects the breadth, with separate files for order handling, order lists, ticker data, wallet access, OHLCV, a watcher, a futures watcher, and a directory for websocket user data signature handling. The README states that all the REST APIs listed in the Binance API document are implemented, as well as the websocket APIs, and the API list table marks each of the eight surfaces implemented, including margin, futures, delivery, options and portfolio margin.

## The module version is v2 and the older line lives on a branch

Installation is a single go get, and the major version is in the path:

```shell
go get github.com/adshao/go-binance/v2
```

For the v1 API the documentation says it has been moved to a v1 branch, and the corresponding command is:

```shell
go get github.com/adshao/go-binance/v1
```

The import block shows which packages you actually pull in, with the optional ones commented as optional:

```golang
import (
    // for spot and other interfaces contained in https://binance-docs.github.io/apidocs/spot/en/#change-log
    "github.com/adshao/go-binance/v2"

    "github.com/adshao/go-binance/v2/futures" // optional package
    "github.com/adshao/go-binance/v2/delivery" // optional package
    "github.com/adshao/go-binance/v2/options" // optional package
)
```

Two constraints follow from that. First, importing the root package is enough for spot and the endpoints in the spot changelog, and the futures, delivery and options packages are optional sub-packages that a spot-only project can simply omit. Second, the README asks that you read the Binance API document before continuing, and the library's own documentation advises referring to the specific version of the code for specific reference definitions, which is an implicit admission that the surface is large. The examples directory has its own go.mod and go.sum, so the examples are a separate module rather than part of the SDK.

## Where the SDK leaves you on your own

The library is a thin layer over HTTP, and the thinness is the risk. The SDK does not manage your API key lifecycle, and there is no mention of retry, backoff or rate limit handling in the documented usage, so a service that hits a weight limit or a 429 will surface that as an error and the retry policy is yours to write. Order placement has the same character. There is no documented mechanism for reconciling local order state with the exchange after a timeout, which is the classic failure: you send a create order, the response is lost, and now you do not know whether the order exists. Nothing in the documented API resolves that ambiguity for you, so an idempotency or reconciliation layer belongs in your service, not in the SDK. Two smaller limits are worth knowing. Quantities and prices are strings, so precision handling and validation are on you. And the SDK is a snapshot of the exchange API at a point in time: a Binance endpoint change will not be fixed by a library release if the maintainers have not pushed one, and the last push to the repository was on 2026-08-08.

## How this compares with a multi-exchange abstraction

The alternative is a cross-exchange SDK, where one interface covers many venues and you switch a market identifier. The difference in approach is concrete. A cross-exchange library spends its effort normalising: it maps a venue's order type, symbol format, fee structure and market data shape onto a common model, and it accepts that some venues fit the model less well than others. go-binance spends no effort on normalisation, because there is one venue. What you get in exchange is the full fidelity of the Binance API, including the surfaces that a normalised model tends to flatten, such as the portfolio margin endpoints, the Coin-M delivery API and the options API, each of which has its own optional package here. The price is portability. Code written against this library is tied to Binance endpoint shapes, and the symbol, quantity and price handling is venue specific, so moving to a second exchange is a rewrite rather than a configuration change. The practical split is that a single-venue product benefits from the depth, while anything that must support several exchanges from day one will not.

## Conclusion

Adopt go-binance if you are shipping Go code against Binance and want typed service structs for the endpoints you use rather than hand-rolled HTTP calls with your own signing, and if you are willing to keep the module pinned. Do not adopt it as a multi-exchange abstraction, because every service here is a Binance endpoint, and the v2 module path differs from the repository location, which matters when you write import statements and vendor the code. Before you build, confirm which of the eight API surfaces your product needs and import only the optional packages you use, and note that the last push was on 2026-08-08 with the newest tag at v2.8.12, so an exchange API change can break the build without a release to signal it.

## FAQ

### What is the correct import path for the go-binance SDK?

The module is github.com/adshao/go-binance/v2, installed with go get github.com/adshao/go-binance/v2, even though the repository is hosted under ccxt/go-binance. The v1 API lives on a v1 branch with its own import path.

### Does go-binance support futures, options and margin APIs?

Yes. The API list marks the margin, futures, delivery, options and portfolio margin surfaces as implemented, and futures, delivery and options are available as separate optional packages under the v2 module path.

### How do I place a test order with go-binance without hitting the exchange?

Each service exposes a Test() method in place of Do(). The documentation notes this in the create order example, so a test can exercise the service chain without placing a live order.

### What licence is go-binance released under?

The repository is licensed under the MIT licence, with the LICENSE file at the root of the tree. The project states compatibility with Go >= 1.8 and the last push was on 2026-08-08.

## Sources

- [ccxt/go-binance on GitHub](https://github.com/ccxt/go-binance)
- [Issues](https://github.com/ccxt/go-binance/issues)
- [License: MIT](https://github.com/ccxt/go-binance/blob/master/LICENSE)
- [README](https://github.com/ccxt/go-binance/blob/master/README.md)
- [Releases](https://github.com/ccxt/go-binance/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ccxt-go-binance