roq-binance#

Supports#

Products

Spot

✓

Futures

Options

Combos
Market Data

Reference Data

✓

Market Status

✓

Top of Book

✓

Market by Price

✓

Market by Order

Trade Summary

✓

Statistics

✓
Order Management

Create

✓

Modify

Cancel

✓

Cancel All

✓

Auto-Cancel

(✓)
Account Management

Positions

Funds

✓

Note

  • Auto-Cancel only available with the REST API.

Installing#

$ mamba install \
      --channel https://roq-trading.com/conda/stable \
      roq-binance

$ mamba install \
      --channel https://roq-trading.com/conda/unstable \
      roq-binance

Using#

$ roq-binance \
      --name "binance" \
      --config_file $CONFIG_FILE_PATH \
      --client_listen_address $UNIX_SOCKET_PATH \
      --flagfile $ENVIRONMENT_FLAGFILE

Flags#

$ roq-binance --help
--exchange (binance)

Exchange identifier

--ws_api (true)

Use WebSocket API?

--rest_network_interfaces

Network interfaces

--rest_uri (https://testnet.binance.com)

Exchange end-point

--rest_host

Host (when URI is an IP address)

--rest_pm_uri (https://testnet.binance.com)

Exchange end-point

--rest_pm_host

Host (when URI is an IP address)

--rest_proxy

Proxy end-point

--rest_ping_freq (5s)

Ping frequency

--rest_ping_path (/api/v3/time)

Ping path

--rest_request_timeout (30s)

Request timeout

--rest_listen_key_refresh (1800s)

Listen key refresh period

--rest_order_recv_window (5000ms)

Receive window (please refer to exchange documentation)

--rest_cancel_on_disconnect (false)

Auto-cancel orders on disconnect?

--rest_terminate_on_403 (false)

(TEST) Trigger program termination after receiving a 403 response code?

--rest_back_off_delay (300s)

(TEST) Time to wait before retrying a rejected request

--ws_uri (wss://testnet.binance.com/realtime)

Exchange end-point

--ws_host

Host (when URI is an IP address)

--ws_pm_uri (wss://testnet.binance.com/realtime)

Exchange end-point

--ws_pm_host

Host (when URI is an IP address)

--ws_ping_freq (5s)

Ping frequency

--ws_max_subscriptions_per_stream (128)

Maximum number of symbols per connection

--ws_subscribe_depth_levels (1000)

Depth levels to subscribe

--ws_subscribe_depth_freq (100ms)

Depth update frequency

--ws_mbp_request_delay (10s)

Delay before requesting depth snapshot

--ws_mbp_request_max_retries (0)

Maximum number of retries before giving up

--ws_subscribe_trade_details (false)

Should trade summary reports include individual matches?

--ws_enable_secondary (false)

Create secondary market data connection?

--ws_api_network_interfaces

Network interfaces

--ws_api_uri (wss://ws-api.binance.com/ws-api/v3)

Exchange end-point

--ws_api_host

Host (when URI is an IP address)

--ws_api_ping_freq (5s)

Ping frequency

--download_trades_lookback (300s)

Lookback period when downloading trades (following a disconnect)

--download_trades_lookback_on_restart

Lookback period when downloading trades (initial download)

--download_trades_limit (1000)

Maximum number of trades per response (exchange limit)

--download_symbols

List of symbols to download

--mbp_max_depth

Maximum depth

--mbp_sequencer_timeout (120s)

Sequencer timeout

--mbp_allow_price_inversion (false)

Allow price inversion?

--cancel_replace_stop_on_failure (false)

If the cancel request fails, the replacement will not be attempted

--request_limit (8)

Maximum number of requests per interval

--request_limit_interval (5s)

Monitor interval

--decode_buffer_size (10485760)

Decode buffer size

--encode_buffer_size (1048576)

Encode buffer size

Environments#

$ $CONDA_PREFIX/share/roq-binance/flags/prod/flags.cfg

# flagfile for the roq-binance gateway
# exchange servers are located in AWS, Tokyo, Japan

--rest_uri=https://api.binance.com
--ws_uri=wss://stream.binance.com:9443/stream
--ws_api_uri=wss://ws-api.binance.com/ws-api/v3
--rest_pm_uri=https://papi.binance.com
--ws_pm_uri=wss://fstream.binance.com/pm/ws

$ $CONDA_PREFIX/share/roq-binance/flags/test/flags.cfg

# flagfile for the roq-binance gateway
# exchange servers are located in AWS, Tokyo, Japan

--rest_uri=https://testnet.binance.vision
--ws_uri=wss://testnet.binance.vision/stream
--ws_api_uri=wss://testnet.binance.vision/ws-api/v3

$ $CONDA_PREFIX/share/roq-binance/flags/prod-us/flags.cfg

# flagfile for the roq-binance gateway
# exchange servers are located in AWS, US

--rest_uri=https://api.binance.us
--ws_uri=wss://stream.binance.us:9443/stream

Configuration#

$ $CONDA_PREFIX/share/roq-binance/config.toml

Important

The template will be replaced when the software is upgraded. Make a copy and modify to your needs.

symbols = [
  "^BTCUSD[A-Z]?$",
  "^ETHUSD[A-Z]?$"
]

[accounts]

  [accounts.A1]
  master = true
  login = "YOUR_BINANCE_API_KEY_GOES_HERE"
  secret = "YOUR_BINANCE_SECRET_GOES_HERE"
  symbols = [ ".*" ]

[users]

  [users.test]
  password = "1234"
  symbols = ".*"

  [users.trader]
  password = "secret"
  accounts = [ "A1" ]
  symbols = [ ".*BTC.*", ".*ETH.*" ]

[rate_limits]

  [rate_limits.global]
    type = "ORDER_ACTION"
    aggregate = true
    request_limit = 100
    monitor_period = "10s"
    ban_period = "5m"

Market Data#

Event

Stream

Messages

Comments

roq::ReferenceData

Unavailable

roq::MarketStatus

Unavailable

roq::TopOfBook

MarketData

<symbol>@bookTicker

roq::MarketByPriceUpdate

MarketData

<symbol>@depth@<freq>

See Flags

roq::MarketByOrderUpdate

Unavailable

roq::TradeSummary

MarketData

<symbol>@trade, <symbol>@aggTrade

See Flags

roq::StatisticsUpdate

MarketData

<symbol>@miniTicker

Event

Stream

Messages

Comments

roq::ReferenceData

OrderEntry

GET /api/v3/exchangeInfo

roq::MarketStatus

OrderEntry

GET /api/v3/exchangeInfo

roq::TopOfBook

roq::MarketByPriceUpdate

OrderEntry

GET /api/v3/depth

See Flags

roq::MarketByOrderUpdate

roq::TradeSummary

roq::StatisticsUpdate

Statistics#

Type

Comments

HIGHEST_TRADED_PRICE

(miniTicker) high_price

LOWEST_TRADED_PRICE

(miniTicker) low_price

OPEN_PRICE

(miniTicker) open_price

CLOSE_PRICE

(miniTicker) close_price

Order Management#

Event

Stream

Messages

Comments

roq::OrderUpdate

DropCopy

executionReport

roq::TradeUpdate

DropCopy

executionReport

Event

Stream

Messages

Comments

roq::OrderUpdate

OrderEntry

GET /api/v3/openOrders

It is only possible to download open orders

roq::TradeUpdate

Event

Stream

Messages

Comments

roq::CreateOrder

OrderEntry

POST /api/v3/order

roq::ModifyOrder

Unavailable

roq::CancelOrder

OrderEntry

DELETE /api/v3/order

roq::CancelAllOrders

OrderEntry

DELETE /api/v3/openOrders

This request is per-symbol! Only executed for those symbols where the gateway has seen order actions or download.

Event

Stream

Messages

Comments

roq::OrderAck

OrderEntry

/api/v3/order

Order Types#

Type

Comments

MARKET

Mapped to 'MARKET' (JSON)

LIMIT

Mapped to 'LIMIT' (JSON)

Time in Force#

Type

Comments

GTC

Mapped to 'GTC' (JSON)

IOC

Mapped to 'IOC' (JSON)

FOK

Mapped to 'FOK' (JSON)

Position Effect#

Note

Not supported

Execution Instructions#

Type

Comments

PARTICIPATE_DO_NOT_INITIATE

Maps OrderType to 'LIMIT_MAKER' (JSON)

Templates#

create_order#

Field

Values

Comments

self_trade_prevention_mode

EXPIRE_TAKER, EXPIRE_MAKER, EXPIRE_BOTH

Exchange field is selfTradePreventionMode

cancel_order#

Field

Values

Comments

cancel_restrictions

ONLY_NEW, ONLY_PARTIALLY_FILLED

Exchange field is cancelRestrictions

cancel_replace_mode

STOP_ON_FAILURE, ALLOW_FAILURE

Exchange field is cancelReplaceMode

Account Management#

Event

Stream

Messages

Comments

roq::PositionUpdate

Unavailable

roq::FundsUpdate

DropCopy

outboundAccountInfo, outboundAccountPosition

Event

Stream

Messages

Comments

roq::PositionUpdate

Unavailable

roq::FundsUpdate

OrderEntry

GET /api/v3/account

Streams#

Type

Comments

REST

Primary purpose

  • support order management

Each connection

  • supports a single account

  • maintains a listen key (used by the DropCopy stream)

Type

Comments

WebSocket

Primary purpose

  • live account updates, including orders and fills

Each connection

  • supports a single account

Type

Comments

WebSocket

Primary purpose

  • live market data

Each connection

  • supports a slice of the symbols

Type

Comments

REST

Primary purpose

  • download reference data

One connection

Constraints#

  • It is only possible to download current order status for open orders. The implication is that backup procedures must be implemented to reoncile positions in the scenario where orders are completely filled during a disconnect.

  • The newClientOrderId field (used by CreateOrder) must conform to the ^[.A-Z:/a-z0-9_-]{1,36}$ regular expression (ECMAScript). This restricts length and character used when supplying the routing_id field.

  • The exchange will monitor rate-limit usage per IP address.

  • Rate-limit usage is quite strict when downloading full order books. Due to this constraint, it may take a very long time to initialize all symbols. It is therefore STRONGLY recommended to reduce the configured number of symbols, e.g. symbols=".*BTC.*", or even more specific by using lists.

Comments#

  • It is possible to see gateway warnings about dropped messages caused by order status reversal, e.g. seeing WORKING after COMPLETED. This is partly due to REST vs WebSocket and partly due to exchange publishing both NEW and FILLED order update messages for taker orders.

  • The online documentation has a note about rejected messages never ping pushed into the user data stream. This effectively means that there’s the risk that you will have to wait for the gateway to detect timeout if the REST connection is disconnected right after an order request has been sent.

  • The exchange API supports a cancel-replace order request. This is supported by first placing a cancel order with is_last=false followed immediately by a create order with is_last=true.

    Note

    The two orders must share the same symbol.

  • Multiple order entry connections (REST or WS) may be supported by specifying a list of local network interfaces to bind to. The implementation will then round-robin requests between connections already in the ready-state.

  • There are different end-points depending on the margin-mode.

    • If nothing is specified, the classic margin-mode is selected. The end-points are then taken from --rest_uri and --ws_uri.

    • The new end-points are selected if the toml config has margin_mode = "portfolio". The end-points are then taken from --rest_pm_uri and --ws_pm_uri.