Skip to content

Latest commit

 

History

History
151 lines (118 loc) · 10 KB

README.md

File metadata and controls

151 lines (118 loc) · 10 KB

Binance Proxy

A fast and simple Websocket Proxy for the Binance API written in GoLang. Mimics the behavior of API endpoints to avoid rate limiting imposed on IP's when using REST queries. Intended Usage for multiple instances of applications querying the Binance API at a rate that might lead to banning or blocking, like for example the Freqtrade Trading Bot, or any other similar application.

latest version go version  github issues license

⚡ Quick Start

You can download the pre-compiled binary for the architecture of your choice from the relaseses page on GitHub.

Unzip the package to a folder of choice, preferably one that's in $PATH

tar -xf binance-proxy_1.2.4_Linux_x86_64.tar.gz -C /usr/local/bin 

Starting the proxy:

binance-proxy

That's all you need to know to start! 🎉

🐳 Docker-way to quick start

If you don't want to install or compile the binance-proxy to your system, feel free using the prebuild Docker images and run it from an isolated container:

docker run --rm -d nightshift2k/binance-proxy:latest

ℹ️ Please pay attention to configuring network access, per default the ports 8090 and 8091 are exposed, if you specify different ports via parameters, you will need to re-configure your docker setup. Please refer to the docker network documentation, how to adjust this inside a container.

⚒️ Installing from source

First of all, download and install Go. Version 1.17 or higher is required.

Installation is done by using the go install command and rename installed binary in $GOPATH/bin:

go install github.com/nightshift2k/binance-proxy/cmd/binance-proxy

📖 Basic Usage

The proxy listens automatically on port 8090 for Spot markets, and port 8091 for Futures markets. Available options for parametrizations are available via -h

Usage:
  binance-proxy [OPTIONS]

Application Options:
  -v, --verbose                Verbose output (increase with -vv) [$BPX_VERBOSE]
  -p, --port-spot=             Port to which to bind for SPOT markets (default: 8090) [$BPX_PORT_SPOT]
  -t, --port-futures=          Port to which to bind for FUTURES markets (default: 8091) [$BPX_PORT_FUTURES]
  -c, --disable-fake-candles   Disable generation of fake candles (ohlcv) when sockets have not delivered data yet [$BPX_DISABLE_FAKE_CANDLES]
  -s, --disable-spot           Disable proxying spot markets [$BPX_DISABLE_SPOT]
  -f, --disable-futures        Disable proxying futures markets [$BPX_DISABLE_FUTURES]
  -a, --always-show-forwards   Always show requests forwarded via REST even if verbose is disabled [$BPX_ALWAYS_SHOW_FORWARDS]

Help Options:
  -h, --help                   Show this help message

🪙 Example Usage with Freqtrade

Freqtrade needs to be aware, that the API endpoint for querying the exchange is not the public endpoint, which is usually https://api.binance.com but instead queries are being proxied. To achieve that, the appropriate config.json needs to be adjusted in the { exchange: { urls: { api: public: "..."} } } section.

{
    "exchange": {
        "name": "binance",
        "key": "",
        "secret": "",
        "ccxt_config": {
            "enableRateLimit": false,
            "urls": {
                "api": {
                    "public": "http://127.0.0.1:8090/api/v3"
                }
            }
        },
        "ccxt_async_config": {
            "enableRateLimit": false
        }
    }
}

This example assumes, that binance-proxy is running on the same host as the consuming application, thus localhost or 127.0.0.1 is used as the target address. Should binance-proxy run in a separate 🐳 Docker container, a separate instance or a k8s pod, the target address has to be replaced respectively, and it needs to be ensured that the required ports (8090/8091 per default) are opened for requests.

➡️ Supported API endpoints for caching

Endpoint Market Purpose Socket Update Interval Comments
/api/v3/klines
/fapi/v1/klines
spot/futures Kline/candlestick bars for a symbol ~ 2s Websocket is closed if there is no following request after 2 * interval_time (for example: A websocket for a symbol on 5m timeframe is closed after 10 minutes.

Following requests for klines can not be delivered from the websocket cache:
  • limit parameter is > 1000
  • startTime or endTime have been specified
  • /api/v3/depth
    /fapi/v1/depth
    spot/futures Order Book (Depth) 100ms Websocket is closed if there is no following request after 2 minutes.

    The depth endpoint serves only a maximum depth of 20.
    /api/v3/ticker/24hr spot 24hr ticker price change statistics 2s/100ms (see comments) Websocket is closed if there is no following request after 2 minutes.

    For faster updates the values for
  • lastPrice
  • bidPrice
  • askPrice
    are taken from the bookTicker which is updated in an interval of 100ms.
  • /api/v3/exchangeInfo
    /fapi/v1/exchangeInfo
    spot/futures Current exchange trading rules and symbol information 60s (see comments) exchangeInfo is fetched periodically via REST every 60 seconds. It is not a websocket endpoint but just being cached during runtime.

    🚨 Every other REST query to an endpoint is being forwarded 1:1 to the API at https://api.binance.com !

    ⚙️ Commands & Options

    The following parameters are available to control the behavior of binance-proxy:

    binance-proxy [OPTION]
    Option Environment Variable Description Type Default Required?
    -v $BPX_VERBOSE Sets the verbosity to debug level. bool false No
    -vv $BPX_VERBOSE Sets the verbosity to trace level. bool false No
    -p $BPX_PORT_SPOT Specifies the listen port for SPOT market proxy. int 8090 No
    -t $BPX_PORT_FUTURES Specifies the listen port for FUTURES market proxy. int 8091 No
    -c $BPX_DISABLE_FAKE_CANDLES Disables the generation of fake candles, when not yet recieved through websockets. bool false No
    -s $BPX_DISABLE_SPOT Disables proxy for SPOT markets. bool false No
    -f $BPX_DISABLE_FUTURES Disables proxy for FUTURES markets. bool false No
    -a $BPX_ALWAYS_SHOW_FORWARDS Always show requests forwarded via REST even if verbose is disabled bool false No

    Instead of using command line switches environment variables can be used, there are several ways how those can be implemented. For example .env files could be used in combination with docker-compose.

    Passing variables to a docker container can also be achieved in different ways, please see the documentation for all available options here.

    🐞 Bug / Feature Request

    If you find a bug (the proxy couldn't handle the query and / or gave undesired results), kindly open an issue here by including a logfile and a meaningful description of the problem.

    If you'd like to request a new function, feel free to do so by opening an issue here.

    💻 Development

    Want to contribute? Great!🥳

    To fix a bug or enhance an existing module, follow these steps:

    • Fork the repo
    • Create a new branch (git checkout -b improve-feature)
    • Make the appropriate changes in the files
    • Add changes to reflect the changes made
    • Commit your changes (git commit -am 'Improve feature')
    • Push to the branch (git push origin improve-feature)
    • Create a Pull Request

    🙏 Credits

    ⚠️ License

    binance-proxy is free and open-source software licensed under the MIT License.

    By submitting a pull request to this project, you agree to license your contribution under the MIT license to this project.

    🧬 Third-party library licenses