JavaScript Multi-threading

JavaScript strategies can use the threading object to create threads that really run in parallel, and exchange data between them with messages, shared dictionaries, locks and similar objects. This page explains when to use threads and how to organize thread code; for the parameters and return values of each function see Threads in the syntax manual.

Pick the right tool first

When you only need a few concurrent requests, exchange.Go() is simpler and involves no data passing between threads. The threading object on this page is for JavaScript strategies only; Python and Rust strategies use exchange.Go().

These functions can be called in the backtesting system, but the threads actually run one after another there; this only keeps the code runnable in backtests.

Threads run in isolated environments

The function passed to threading.Thread() runs in a separate JavaScript environment. This is the most important thing to keep in mind when writing thread code:

• A thread function cannot reference outer variables or closures, nor call other functions defined in the strategy. Pass the data it needs as arguments: threading.Thread(func, arg1, arg2, ...).
• Plain objects and arrays passed as arguments are deep-copied: changing them inside the thread does not affect other threads. When several threads need to see the same data, use a dictionary created by threading.Dict().
• Functions can be passed as arguments too; threading.Thread() also accepts function source strings, which can be used to load external libraries in the thread.
• Platform API functions such as exchange.GetTicker() and Log() can be called directly in a thread.
• The return value of the thread function is retrieved with join(): t.join().ret.

Exchanging data between threads

A message received by a thread also raises an event, so the thread object's eventLoop can wait for messages and other events in one place.

Thread lifecycle

• t.join() waits for the thread to end and returns its result, with an optional timeout; t.terminate() ends a thread forcibly.
• When a thread has ended and is no longer referenced, its resources are reclaimed automatically; there is no need to call join() just to free them. An error is raised when more than 2000 threads are kept referenced and cannot be reclaimed.
• threading.pending() returns the number of running threads (main thread included).
• All threads end when the live trading stops. Waits in peekMessage(), join(), locks and events are interrupted by the stop.

Serving from inside the strategy

threading.Serve(address, handler, ...args) starts an HTTP (WebSocket included) or TCP service inside the strategy process. Each request or connection calls the handler in its own thread. It returns a Server object (addr() gives the actual listening address, close() shuts it down). Like thread functions, handlers run in isolated environments and receive what they need as arguments; a threading.Dict() is commonly used to share state with the main thread. For the address syntax and the methods of the ctx object see Serve.

The old global function __Serve() still works but only returns the listening address string; use threading.Serve() in new code.

Examples

Examples

• Several threads compute in parallel, the main thread collects the results

  Each thread fetches the K-lines of one symbol and computes a moving average; the result goes back to the main thread as the return value. Note that the symbol is passed as an argument and the thread function references no outer variables.

  
      javascript
      
      
  function main() {
      var symbols = ["BTC_USDT", "ETH_USDT", "SOL_USDT"]
      var threads = []
      for (var i = 0; i < symbols.length; i++) {
          threads.push(threading.Thread(function(symbol, period) {
              // runs in the thread: only arguments and platform APIs are available
              var records = exchange.GetRecords(symbol, period)
              if (!records || records.length < 20) {
                  return null
              }
              var ma = TA.MA(records, 20)
              return {symbol: symbol, close: records[records.length - 1].Close, ma20: ma[ma.length - 1]}
          }, symbols[i], PERIOD_H1))
      }
      for (var i = 0; i < threads.length; i++) {
          var r = threads[i].join().ret
          if (r) {
              Log(r.symbol, "close:", r.close, "MA20:", r.ma20)
          }
      }
  }
  

• A background thread collects prices, the main thread reads them and sends commands

  The background thread writes the latest price into a shared dictionary and reports errors to the main thread through messages; the main thread tells it to exit with a message.

  
      javascript
      
      
  function main() {
      var shared = threading.Dict()
      var worker = threading.Thread(function(dict, symbol) {
          while (true) {
              // read commands from the main thread; -1 means do not block
              var cmd = threading.currentThread().peekMessage(-1)
              if (cmd == "stop") {
                  break
              }
              var ticker = exchange.GetTicker(symbol)
              if (ticker) {
                  dict.set("last", ticker.Last)
                  dict.set("time", ticker.Time)
              } else {
                  threading.mainThread().postMessage("failed to get ticker: " + GetLastError())
              }
              Sleep(1000)
          }
          return "worker exited"
      }, shared, "BTC_USDT")
  
      for (var i = 0; i < 10; i++) {
          // wait at most 1 second for a message from the background thread
          var msg = threading.currentThread().peekMessage(1000)
          if (msg) {
              Log("background thread reports:", msg)
          }
          LogStatus("last:", shared.get("last"), "time:", _D(shared.get("time")))
      }
      worker.postMessage("stop")
      Log(worker.join().ret)
  }
  

• A status endpoint with threading.Serve

  The main thread writes the state into a shared dictionary; the HTTP handler gets the same dictionary as an argument and returns it as JSON.

  
      javascript
      
      
  function main() {
      var state = threading.Dict()
      var server = threading.Serve("http://127.0.0.1:8088", function(ctx, st) {
          if (ctx.path() == "/status") {
              ctx.setHeader("Content-Type", "application/json")
              ctx.write(JSON.stringify({last: st.get("last"), updated: st.get("updated")}))
          } else {
              ctx.setStatus(404)
          }
      }, state)
      Log("listening on:", server.addr())
  
      while (true) {
          var ticker = exchange.GetTicker("BTC_USDT")
          if (ticker) {
              state.set("last", ticker.Last)
              state.set("updated", _D())
          }
          Sleep(3000)
      }
  }
  

See Also

Communication Between Live Trading Strategies

Every live trading has a channel whose ID is the live trading ID. A live trading publishes data on its own channel with SetChannelData(), and other live tradings read it with GetChannelData(liveTradingId). The data is relayed by the platform server, so it can travel across dockers and servers.

A channel holds the latest state, not a message queue: each publish overwrites the previous data, and a subscriber always reads the current latest copy. If history is needed, the subscriber keeps it itself.

Typical uses:

• Master/follower: a master strategy analyzes the market and publishes signals; several follower strategies read them and trade on their own accounts.
• Status monitoring: each strategy publishes its running status; a monitoring live trading collects them for display or alerts.
• Data sharing: one live trading computes indicators and publishes the results; others use them directly instead of computing them again.

Key points

• The first read subscribes: the first GetChannelData() call for a channel subscribes to it and returns an empty value (null/None). From then on the server pushes the channel's updates to this live trading, and later calls return the latest data. A subscriber should start reading at startup and handle empty values.
• Subscription limit: a live trading can subscribe to at most 10 different channels (UUID channels below included). Beyond that, the call returns an empty value and logs the error channel subscriber exceed limit.
• **Data format**: in JavaScript and Python, SetChannelData() accepts any JSON-serializable data and the subscriber reads the parsed object. Unchanged data is not sent again. For the data size limit see SetChannelData.
• Rust: SetChannelData(string) only accepts a string, so build the JSON text yourself; GetChannelData() takes no channel argument and cannot choose the channel to read, so it cannot subscribe to other live tradings or UUID channels. Rust strategies are suited to publishing; write subscribers in JavaScript or Python.
• **Cross-platform push**: an external system (a TradingView alert, your own program, etc.) can push data to a given live trading on a channel identified by a 32-character UUID through the extended API's method=pub; the live trading reads it with GetChannelData(UUID). See SetChannelData and GetChannelData for details.
• Live trading feature: channels are meant for communication between live tradings; do not rely on them in backtests. The current live trading ID is available from _G().
• Do not pass keys or other sensitive information through channels.

Basic usage

Examples

• Publisher: publish a market summary

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      var robotId = _G()  // current live trading ID, which is also this live trading's channel ID
      var updateId = 0
  
      while (true) {
          var ticker = exchange.GetTicker("BTC_USDT")
          if (ticker) {
              // publish the latest state, overwriting the previous data
              SetChannelData({
                  robotId: robotId,
                  updateId: ++updateId,
                  timestamp: Date.now(),
                  symbol: "BTC_USDT",
                  lastPrice: ticker.Last
              })
              LogStatus("channel", robotId, "publish #", updateId, "last price:", ticker.Last)
          }
          Sleep(60000)  // publish once a minute
      }
  }
  

  
      python
      
      
  import time
  
  def main():
      robotId = _G()  # current live trading ID, which is also this live trading's channel ID
      updateId = 0
  
      while True:
          ticker = exchange.GetTicker("BTC_USDT")
          if ticker:
              updateId += 1
              # publish the latest state, overwriting the previous data
              SetChannelData({
                  "robotId": robotId,
                  "updateId": updateId,
                  "timestamp": int(time.time() * 1000),
                  "symbol": "BTC_USDT",
                  "lastPrice": ticker["Last"]
              })
              LogStatus("channel", robotId, "publish #", updateId, "last price:", ticker["Last"])
          Sleep(60000)  # publish once a minute
  

  
      rust
      
      
  fn main() {
      let robotId = _G!();  // current live trading ID, which is also this live trading's channel ID
      let mut updateId = 0;
  
      loop {
          if let Ok(ticker) = exchange.GetTicker("BTC_USDT") {
              updateId += 1;
              // Rust's SetChannelData only accepts a string; build the JSON text yourself
              let state = format!(
                  r#"{{"robotId": "{}", "updateId": {}, "timestamp": {}, "symbol": "BTC_USDT", "lastPrice": {}}}"#,
                  robotId, updateId, Unix() * 1000, ticker.Last
              );
              SetChannelData(&state);
              LogStatus!("channel", robotId, "publish #", updateId, "last price:", ticker.Last);
          }
          Sleep(60000);  // publish once a minute
      }
  }
  

• Subscriber: read two channels

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      // live trading IDs to subscribe to (change as needed)
      var channels = ["632799", "632800"]
  
      while (true) {
          var msg = ""
          for (var i = 0; i < channels.length; i++) {
              // the first call subscribes and returns null; later calls return the latest data
              var state = GetChannelData(channels[i])
              if (state) {
                  msg += "channel " + channels[i] + ": #" + state.updateId + " " + _D(state.timestamp) + " last " + state.lastPrice + "\n"
              } else {
                  msg += "channel " + channels[i] + ": waiting for data\n"
              }
          }
          LogStatus(msg)
          Sleep(5000)
      }
  }
  

  
      python
      
      
  def main():
      # live trading IDs to subscribe to (change as needed)
      channels = ["632799", "632800"]
  
      while True:
          msg = ""
          for ch in channels:
              # the first call subscribes and returns None; later calls return the latest data
              state = GetChannelData(ch)
              if state:
                  msg += "channel {}: #{} {} last {}\n".format(ch, state["updateId"], _D(state["timestamp"]), state["lastPrice"])
              else:
                  msg += "channel {}: waiting for data\n".format(ch)
          LogStatus(msg)
          Sleep(5000)
  

  
      rust
      
      
  // Rust's GetChannelData() takes no channel argument and cannot subscribe to other live tradings' channels
  

• Scenario: master/follower strategies

  The master strategy computes a moving-average crossover signal and publishes it; the follower reads the signal and places an order when it changes.

  Master strategy (publishes signals)

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      while (true) {
          var records = exchange.GetRecords("BTC_USDT")
          if (records && records.length >= 21) {
              var ma5 = TA.MA(records, 5)
              var ma20 = TA.MA(records, 20)
              var n = records.length
              var signal = "HOLD"
              if (ma5[n - 1] > ma20[n - 1] && ma5[n - 2] <= ma20[n - 2]) {
                  signal = "BUY"
              } else if (ma5[n - 1] < ma20[n - 1] && ma5[n - 2] >= ma20[n - 2]) {
                  signal = "SELL"
              }
              SetChannelData({
                  timestamp: Date.now(),
                  symbol: "BTC_USDT",
                  signal: signal,
                  price: records[n - 1].Close
              })
              LogStatus("current signal:", signal, "price:", records[n - 1].Close)
          }
          Sleep(60000)
      }
  }
  

  
      python
      
      
  import time
  
  def main():
      while True:
          records = exchange.GetRecords("BTC_USDT")
          if records and len(records) >= 21:
              ma5 = TA.MA(records, 5)
              ma20 = TA.MA(records, 20)
              signal = "HOLD"
              if ma5[-1] > ma20[-1] and ma5[-2] <= ma20[-2]:
                  signal = "BUY"
              elif ma5[-1] < ma20[-1] and ma5[-2] >= ma20[-2]:
                  signal = "SELL"
              SetChannelData({
                  "timestamp": int(time.time() * 1000),
                  "symbol": "BTC_USDT",
                  "signal": signal,
                  "price": records[-1]["Close"]
              })
              LogStatus("current signal:", signal, "price:", records[-1]["Close"])
          Sleep(60000)
  

  
      rust
      
      
  fn main() {
      loop {
          if let Ok(records) = exchange.GetRecords("BTC_USDT", None, None) {
              let n = records.len();
              if n >= 21 {
                  let ma5 = TA.MA(&records, 5);
                  let ma20 = TA.MA(&records, 20);
                  let mut signal = "HOLD";
                  if ma5[n - 1] > ma20[n - 1] && ma5[n - 2] <= ma20[n - 2] {
                      signal = "BUY";
                  } else if ma5[n - 1] < ma20[n - 1] && ma5[n - 2] >= ma20[n - 2] {
                      signal = "SELL";
                  }
                  let price = records[n - 1].Close;
                  // Rust's SetChannelData only accepts a string; build the JSON text yourself
                  let data = format!(
                      r#"{{"timestamp": {}, "symbol": "BTC_USDT", "signal": "{}", "price": {}}}"#,
                      Unix() * 1000, signal, price
                  );
                  SetChannelData(&data);
                  LogStatus!("current signal:", signal, "price:", price);
              }
          }
          Sleep(60000);
      }
  }
  

• Follower strategy (reads and executes signals)

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      var masterId = "632799"  // live trading ID of the master strategy
      var lastSignal = null
  
      while (true) {
          var data = GetChannelData(masterId)
          if (!data) {
              LogStatus("waiting for the master strategy's signal...")
          } else {
              if (data.signal !== lastSignal) {
                  Log("new signal:", data.signal, "signal price:", data.price)
                  var ticker = exchange.GetTicker(data.symbol)
                  if (ticker && data.signal === "BUY") {
                      exchange.CreateOrder(data.symbol, "buy", ticker.Last, 0.01)
                  } else if (ticker && data.signal === "SELL") {
                      exchange.CreateOrder(data.symbol, "sell", ticker.Last, 0.01)
                  }
                  lastSignal = data.signal
              }
              LogStatus("current signal:", data.signal, "signal time:", _D(data.timestamp))
          }
          Sleep(5000)
      }
  }
  

  
      python
      
      
  def main():
      masterId = "632799"  # live trading ID of the master strategy
      lastSignal = None
  
      while True:
          data = GetChannelData(masterId)
          if not data:
              LogStatus("waiting for the master strategy's signal...")
          else:
              if data["signal"] != lastSignal:
                  Log("new signal:", data["signal"], "signal price:", data["price"])
                  ticker = exchange.GetTicker(data["symbol"])
                  if ticker and data["signal"] == "BUY":
                      exchange.CreateOrder(data["symbol"], "buy", ticker["Last"], 0.01)
                  elif ticker and data["signal"] == "SELL":
                      exchange.CreateOrder(data["symbol"], "sell", ticker["Last"], 0.01)
                  lastSignal = data["signal"]
              LogStatus("current signal:", data["signal"], "signal time:", _D(data["timestamp"]))
          Sleep(5000)
  

  
      rust
      
      
  // Rust's GetChannelData() takes no channel argument and cannot read the master strategy's channel
  

• Scenario: monitoring several strategies

  Each strategy publishes its status as the publisher above does; the monitoring live trading reads every channel, shows them in a table and marks those without an update for over 2 minutes as abnormal.

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      var monitorList = ["632799", "632800", "632801"]  // at most 10
  
      while (true) {
          var table = {type: "table", title: "Strategy status", cols: ["Live trading ID", "Status", "Last update", "Symbol", "Last price"], rows: []}
          for (var i = 0; i < monitorList.length; i++) {
              var data = GetChannelData(monitorList[i])
              if (data) {
                  var status = Date.now() - data.timestamp < 120000 ? "running" : "abnormal"
                  table.rows.push([monitorList[i], status, _D(data.timestamp), data.symbol || "-", data.lastPrice || "-"])
              } else {
                  table.rows.push([monitorList[i], "waiting for data", "-", "-", "-"])
              }
          }
          LogStatus("`" + JSON.stringify(table) + "`")
          Sleep(10000)
      }
  }
  

  
      python
      
      
  import json
  import time
  
  def main():
      monitorList = ["632799", "632800", "632801"]  # at most 10
  
      while True:
          table = {"type": "table", "title": "Strategy status", "cols": ["Live trading ID", "Status", "Last update", "Symbol", "Last price"], "rows": []}
          for robotId in monitorList:
              data = GetChannelData(robotId)
              if data:
                  status = "running" if time.time() * 1000 - data["timestamp"] < 120000 else "abnormal"
                  table["rows"].append([robotId, status, _D(data["timestamp"]), data.get("symbol", "-"), data.get("lastPrice", "-")])
              else:
                  table["rows"].append([robotId, "waiting for data", "-", "-", "-"])
          LogStatus("`" + json.dumps(table) + "`")
          Sleep(10000)
  

  
      rust
      
      
  // Rust's GetChannelData() takes no channel argument and cannot read other live tradings' channels
  

See Also

API Rate Limiting Control

Exchanges limit how often their API may be called. Going over the limit gets requests rejected at best and the account temporarily banned at worst. With exchange.IO("rate", ...) or exchange.IO("quota", ...) you can cap the call frequency of standard functions locally on the docker: a call that exceeds the limit is never sent.

            javascript
            
            
exchange.IO("rate" | "quota", name, count, window[, "delay"])

Two modes

• rate (token bucket): the bucket capacity defaults to count. It starts full and refills at a steady "count per window"; each call takes one token. Short bursts are allowed, while the long-run average never exceeds "count per window". Writing count as "10/5" means 10 refills per window with a bucket capacity of 5, which limits bursts.
• quota (fixed window): at most count calls per window; the counter resets when the next window starts. Windows are aligned to the Unix epoch: "1s" to whole seconds, "1m" to whole minutes, "1h" to whole hours, "1d" to UTC midnight (08:00 Beijing time). For example, counting that starts at 12:00:00.900 is already in a new window at 12:00:01.000.

Use quota with a window matching the exchange's counting period when you must guarantee "no more than N calls in any of the exchange's periods"; use rate when you only need to control the average frequency.

Parameters

Function names that can be limited

• GetAccount and GetAssets are the same underlying request; a rule under either name applies to both functions.
• Calls made concurrently through exchange.Go() are counted under the function actually called.

Scope of rules

• Rules are set per exchange object: a rule on exchanges[0] does not affect exchanges[1].
• Rules last for the current run only. Set them again after the live trading restarts, usually at the beginning of main().
• Setting the same name again replaces its rule; an empty name (exchange.IO("rate", "")) clears all rules of that exchange object.
• Each call is counted under one rule only: a function with its own rule is no longer counted under "*", so "*" cannot be used as a "total quota for all calls" stacked on top of specific rules.

When the limit is exceeded

With the default action, a call over the limit sends no request and is treated as a failed call (JavaScript returns null, Python returns None, Rust returns Err). The error message looks like:

            
            
            
rate limit exceeded: GetTicker 10/1s
quota limit exceeded: GetTicker 10/1m
quota limit exceeded: GetRecords 2000/day (resets at 0800)

With the "delay" action the call blocks until a call is available, so the time recorded in the log is the time after the wait. With a rule that resets daily, "delay" may wait until the next day; use it with care.

Examples

Examples

• Default action: calls over the limit fail

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      // GetTicker at most 5 calls per second on average (token bucket, capacity 5)
      exchange.IO("rate", "GetTicker", 5, "1s")
  
      for (var i = 0; i < 10; i++) {
          var ticker = exchange.GetTicker("BTC_USDT")
          if (ticker) {
              Log("call", i + 1, "succeeded:", ticker.Last)
          } else {
              // a call over the limit sends no request and returns null
              Log("call", i + 1, "rate limited:", GetLastError())
          }
      }
  }
  

  
      python
      
      
  def main():
      # GetTicker at most 5 calls per second on average (token bucket, capacity 5)
      exchange.IO("rate", "GetTicker", 5, "1s")
  
      for i in range(10):
          ticker = exchange.GetTicker("BTC_USDT")
          if ticker:
              Log("call", i + 1, "succeeded:", ticker["Last"])
          else:
              # a call over the limit sends no request and returns None
              Log("call", i + 1, "rate limited:", GetLastError())
  

  
      rust
      
      
  fn main() {
      // GetTicker at most 5 calls per second on average (token bucket, capacity 5)
      let _ = exchange.IO(("rate", "GetTicker", 5, "1s"));
  
      for i in 0..10 {
          match exchange.GetTicker("BTC_USDT") {
              Ok(ticker) => Log!("call", i + 1, "succeeded:", ticker.Last),
              // a call over the limit sends no request and returns Err
              Err(e) => Log!("call", i + 1, "rate limited:", e),
          }
      }
  }
  

• Rules grouped after the exchange's own limits

  Market data and trading each share one rule; trading calls wait instead of failing when over the limit; every other function without a rule of its own falls back to "*".

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      // market data: GetTicker and GetDepth together at most 20 calls per second on average
      exchange.IO("rate", "GetTicker,GetDepth", 20, "1s")
      // trading: placing orders (Buy/Sell included) and cancelling together 5 per second, wait when over the limit
      exchange.IO("rate", "CreateOrder,CancelOrder", 5, "1s", "delay")
      // fallback: other functions (such as GetAccount, GetPositions) together 60 per minute, window aligned to whole minutes
      exchange.IO("quota", "*", 60, "1m")
  
      while (true) {
          var ticker = exchange.GetTicker("BTC_USDT")
          var depth = exchange.GetDepth("BTC_USDT")
          if (ticker && depth) {
              Log("last:", ticker.Last, "best bid:", depth.Bids[0].Price)
          }
          Sleep(1000)
      }
  }
  

  
      python
      
      
  def main():
      # market data: GetTicker and GetDepth together at most 20 calls per second on average
      exchange.IO("rate", "GetTicker,GetDepth", 20, "1s")
      # trading: placing orders (Buy/Sell included) and cancelling together 5 per second, wait when over the limit
      exchange.IO("rate", "CreateOrder,CancelOrder", 5, "1s", "delay")
      # fallback: other functions (such as GetAccount, GetPositions) together 60 per minute, window aligned to whole minutes
      exchange.IO("quota", "*", 60, "1m")
  
      while True:
          ticker = exchange.GetTicker("BTC_USDT")
          depth = exchange.GetDepth("BTC_USDT")
          if ticker and depth:
              Log("last:", ticker["Last"], "best bid:", depth["Bids"][0]["Price"])
          Sleep(1000)
  

  
      rust
      
      
  fn main() {
      // market data: GetTicker and GetDepth together at most 20 calls per second on average
      let _ = exchange.IO(("rate", "GetTicker,GetDepth", 20, "1s"));
      // trading: placing orders (Buy/Sell included) and cancelling together 5 per second, wait when over the limit
      let _ = exchange.IO(("rate", "CreateOrder,CancelOrder", 5, "1s", "delay"));
      // fallback: other functions (such as GetAccount, GetPositions) together 60 per minute, window aligned to whole minutes
      let _ = exchange.IO(("quota", "*", 60, "1m"));
  
      loop {
          if let (Ok(ticker), Ok(depth)) = (exchange.GetTicker("BTC_USDT"), exchange.GetDepth("BTC_USDT")) {
              Log!("last:", ticker.Last, "best bid:", depth.Bids[0].Price);
          }
          Sleep(1000);
      }
  }
  

• Burst capacity, daily quota and deleting rules

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      // 10 calls per second on average, but at most 2 in a burst
      exchange.IO("rate", "GetDepth", "10/2", "1s")
      // resets every day at 08:00 Beijing time, at most 2000 calls per day
      exchange.IO("quota", "GetRecords", 2000, "@0800")
      // units can be combined: at most 100 calls every 1 hour 30 minutes
      exchange.IO("rate", "GetOrders", 100, "1h30m")
  
      // count 0: delete the rule for GetOrders
      exchange.IO("rate", "GetOrders", 0)
      // empty name: clear all rules of this exchange object
      exchange.IO("rate", "")
  }
  

  
      python
      
      
  def main():
      # 10 calls per second on average, but at most 2 in a burst
      exchange.IO("rate", "GetDepth", "10/2", "1s")
      # resets every day at 08:00 Beijing time, at most 2000 calls per day
      exchange.IO("quota", "GetRecords", 2000, "@0800")
      # units can be combined: at most 100 calls every 1 hour 30 minutes
      exchange.IO("rate", "GetOrders", 100, "1h30m")
  
      # count 0: delete the rule for GetOrders
      exchange.IO("rate", "GetOrders", 0)
      # empty name: clear all rules of this exchange object
      exchange.IO("rate", "")
  

  
      rust
      
      
  fn main() {
      // 10 calls per second on average, but at most 2 in a burst
      let _ = exchange.IO(("rate", "GetDepth", "10/2", "1s"));
      // resets every day at 08:00 Beijing time, at most 2000 calls per day
      let _ = exchange.IO(("quota", "GetRecords", 2000, "@0800"));
      // units can be combined: at most 100 calls every 1 hour 30 minutes
      let _ = exchange.IO(("rate", "GetOrders", 100, "1h30m"));
  
      // count 0: delete the rule for GetOrders
      let _ = exchange.IO(("rate", "GetOrders", 0));
      // empty name: clear all rules of this exchange object
      let _ = exchange.IO(("rate", ""));
  }
  

See Also

Options Trading

The FMZ Quant Trading Platform supports options trading on the cryptocurrency futures exchanges below. Options are used the same way as futures contracts: set the contract to an option code with exchange.SetContractType() (the option code is the exchange's native code, and the format differs between exchanges). After that, market data functions such as GetTicker() and GetDepth() and trading functions such as Buy(), Sell() (set the trade direction with exchange.SetDirection() before placing orders), CancelOrder() and GetPositions() all work on that option contract. You can also place orders with the full instrument code in the form pair.optionCode, for example BTC_USDT.BTC-260925-145000-C.

Option order books are usually thin: when there is no bid or ask, Buy and Sell in the Ticker are 0, and Last may be 0 for a contract that has never traded; see each exchange below. Whether exchange.GetMarkets() lists option contracts depends on the exchange; where it does not, get the option codes from the exchange's API or website.

Futures_Deribit

After setting an option contract you can get market data, place and cancel orders and query positions. Option code examples: BTC-13SEP24-60000-C, XRP_USDC-27SEP24-1-C; combination examples: BTC-CS-6SEP24-57000_57500, BTC-PCAL-20SEP24_13SEP24-55000. The result of exchange.GetMarkets() includes option contracts.

Reference strategy: Deribit options test strategy

Futures_OKX

Used the same way as Deribit. Set the trading pair to BTC_USD or similar; option codes look like BTC-USD-200626-4500-C. For an option that has never traded, Last in GetTicker() is the mark price. exchange.GetMarkets() does not list option contracts; the option contract list is available from OKX's /api/v5/public/instruments endpoint, for example BTC options:

            javascript
            
            
function main() {
    Log(HttpQuery("https://www.okx.com/api/v5/public/instruments?instType=OPTION&uly=BTC-USD"))
}

            python
            
            
import json
import urllib.request
def main():
    ret = json.loads(urllib.request.urlopen("https://www.okx.com/api/v5/public/instruments?instType=OPTION&uly=BTC-USD").read().decode('utf-8'))
    Log(ret)

            rust
            
            
fn main() {
    let body: String = HttpQuery("https://www.okx.com/api/v5/public/instruments?instType=OPTION&uly=BTC-USD", None);
    Log!(body);
}

Futures_Binance

Binance European options (USDT-settled) are supported. Set the trading pair to BTC_USDT or similar; option codes look like BTC-260925-145000-C (underlying-expiry YYMMDD-strike-C/P). Options trading must be enabled on the account. Limitations:

• Only limit orders are supported; market orders, conditional orders and order amendment (exchange.ModifyOrder()) are not.
• Leverage and margin mode settings such as exchange.SetMarginLevel() are not supported.
• Unified (portfolio margin) accounts do not support options.
• exchange.GetMarkets() does not list option contracts.

Futures_Bybit

Options with two settlement currencies are supported:

• USDC-settled: set the trading pair to ETH_USDC or similar; option codes look like ETH-25NOV22-1375-P.
• USDT-settled: set the trading pair to ETH_USDT or similar; the option code has an extra settlement-currency suffix compared with USDC-settled ones, like ETH-25JUN27-2800-C-USDT.

The result of exchange.GetMarkets() includes options of both settlement currencies. Bybit has no kline endpoint for options, so GetRecords() is built from trades.

Futures_Aevo

USDC options on Aevo are supported. Set the trading pair to ETH_USDC or similar; option codes look like ETH-30JUN23-1600-C. Last in GetTicker() is the mark price. Aevo has no kline endpoint, so GetRecords() is built from trades and is empty while the contract has no trades. The result of exchange.GetMarkets() includes option contracts.

Futures_GateIO

USDT options on Gate are supported. Set the trading pair to BTC_USDT or similar; option codes look like BTC_USDT-20211130-65000-C. The result of exchange.GetMarkets() includes option contracts. If options are not enabled on the account, order and position queries return the exchange's error.

Futures_Kraken

Options on Kraken Futures are supported. Set the trading pair to ETH_USD or similar; option codes look like OF_ETHUSD_261225_4000_C (OF_, underlying and quote currency, expiry YYMMDD, strike, C/P). The underlying and quote currency in the code must match the trading pair, and BTC is written as XBT in the code (e.g. OF_XBTUSD_...).

• Kraken has no option listing endpoint, so exchange.GetMarkets() does not include option contracts; get the option codes from the Kraken website.
• Last in GetTicker() is the mark price, and Buy, Sell, High and Low are 0; the raw data in Info carries the implied volatility, the greeks and other fields.
• Market data, klines, orders, positions and order history queries work; option orders go through the same order endpoint as futures contracts and have not been verified in live trading yet.
• Options have no funding rate, and exchange.SetMarginLevel() is not supported.

See Also

Web3

To swap tokens on the decentralized exchanges Uniswap and PancakeSwap, use the Uniswap exchange object (see Uniswap and PancakeSwap below). To read on-chain data, call smart contracts and send custom transactions, use the Web3 exchange object, which supports Ethereum and other EVM-compatible chains as well as TRON.

    javascript
    
    
function main() {
    var symbol = "ETH_USDC"
    exchange.IO("slippage", 0.003)   // 0.3% slippage for market orders

    var t = exchange.GetTicker(symbol)
    Log("bid:", t.Buy, "ask:", t.Sell)

    // quote only: best route for selling 0.1 ETH
    var r = exchange.IO("route", symbol, "sell", 0.1)
    Log("best route:", r.best, "price:", r.price)

    // simulate on chain first, no gas spent
    if (!exchange.IO("simulate", symbol, "sell", 0.1)) {
        Log("simulation failed:", GetLastError())
        return
    }

    // sell 0.1 ETH at market; the order ID is the transaction hash
    var id = exchange.CreateOrder(symbol, "sell", -1, 0.1)
    if (!id) {
        Log("order failed:", GetLastError())
        return
    }
    while (true) {
        var o = exchange.GetOrder(id)
        if (o && o.Status != ORDER_STATE_PENDING) {
            Log("status:", o.Status, "filled:", o.DealAmount, "average price:", o.AvgPrice)
            break
        }
        Sleep(3000)
    }
}

            javascript
            
            
exchange.IO("api", "eth", "eth_getBalance", wallet, "latest")   // native coin balance, on-chain integer (hex string)
exchange.IO("api", tokenAddress, "balanceOf", wallet)           // ERC20 balance, on-chain integer
exchange.IO("api", tokenAddress, "decimals")                    // token decimals

            javascript
            
            
exchange.IO("abi", poolAddress, "uniswapV3Pool")
var slot0 = exchange.IO("api", poolAddress, "slot0")

            url
            
            
https://api.etherscan.io/v2/api?chainid=1&module=contract&action=getabi&address=0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45&apikey=YourApiKey

            javascript
            
            
var amount = exchange.IO("toUnits", "100", tokenAddress)                 // 100 tokens as an on-chain integer
var txHash = exchange.IO("api", tokenAddress, "approve", spender, amount)

    javascript
    
    
function main() {
    var usdc = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"     // USDC on Ethereum mainnet
    var spender = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45"  // the contract to approve, Uniswap SwapRouter02 here
    var wallet = exchange.IO("address")

    // balances: standard ERC20 methods need no ABI registration
    var eth = exchange.IO("fromUnits", exchange.IO("api", "eth", "eth_getBalance", wallet, "latest"), 18)
    var usdcBalance = exchange.IO("fromUnits", exchange.IO("api", usdc, "balanceOf", wallet), usdc)
    Log("ETH:", eth, "USDC:", usdcBalance)

    // read a contract: current allowance
    var allowance = exchange.IO("api", usdc, "allowance", wallet, spender)
    Log("current allowance:", exchange.IO("fromUnits", allowance, usdc))

    // approve 100 USDC: rehearse first, then send
    var amount = exchange.IO("toUnits", "100", usdc)
    if (!exchange.IO("call", usdc, "approve", spender, amount)) {
        Log("rehearsal failed:", GetLastError())
        return
    }
    var txHash = exchange.IO("api", usdc, "approve", spender, amount)
    Log("tx hash:", txHash)

    // wait at most 3 minutes for the transaction to be mined
    var receipt = exchange.IO("waitReceipt", txHash, {timeout: 180000})
    if (receipt && receipt.status == 1) {
        Log("approved in block:", receipt.blockNumber)
    } else if (receipt) {
        Log("transaction failed:", receipt.revertReason)
    } else {
        // not mined yet: speedUp resends with a higher fee, cancelTx cancels it
        Log("not mined before timeout:", GetLastError())
    }
}

            javascript
            
            
// USDT (TRC20) contract
var usdt = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
Log(exchange.IO("api", usdt, "balanceOf", exchange.IO("address")))   // on-chain integer, USDT has 6 decimals

            javascript
            
            
exchange.IO("encode", "address", "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t")
// 000000000000000000000000a614f803b6fd780986a42c78ec9c7f77e6ded13c
exchange.IO("encodePacked", "address", "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t")
// a614f803b6fd780986a42c78ec9c7f77e6ded13c
exchange.IO("decode", "string", "0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000a5465746865722055534400000000000000000000000000000000000000000000")
// Tether USD

            javascript
            
            
var usdt = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
var raw = exchange.IO("api", usdt, "balanceOf", exchange.IO("address"))
Log(exchange.IO("fromUnits", raw, usdt))   // converted to a readable amount with the contract's decimals()