Skip to content
Get Started

Custom Exchange Plugins

An exchange plugin replaces the built-in Nanoconda Simulator with your own code. The simulator, cmebacktester and dbnbacktester applications send every order to your plugin instead of the simulator, and your plugin decides what happens to it: acknowledge, reject, fill, cancel.

Typical uses:

  • Your own fill model: queue position, partial fills, latency, fees.
  • Replaying a backtest with different matching rules without changing the strategy.
  • A bridge to an external venue (see Connecting to an External Venue for what is supported today).

The plugin uses only the regular nanoconda.h API: a listener to receive callbacks, and a second listener to report back.


How It Works

Your strategy does not change. It sends orders with session->newOrder() and receives onorderack(), onfill() and the other callbacks as usual. Only the side that answers the orders is replaced.

Step What happens
1 The strategy calls session->newOrder(&o). Pre-trade risk checks run as usual (simulator application only, see Notes).
2 Your plugin receives onneworder(const order*).
3 Your plugin calls reports->onorderack(&answer), later reports->onfill(&answer).
4 Nanoconda updates the order manager, positions, P&L, risk counters and the trade log.
5 The strategy receives onorderack() and onfill().

Step 4 is the same path the built-in simulator and a live exchange use, so risk limits, positions and the trade log behave the same way with your plugin.


Entry Point

Your plugin must define the following function. The application calls it once at startup.

extern "C" nanoconda::listener* init_nanoconda_exchange(int argc, char** argv, nanoconda::listener* reports);
Parameter Description
argc, argv Plugin arguments from --exchange-args. argv[0] is the plugin file name.
reports Where your plugin reports acknowledgements, fills, rejects and cancels. Keep this pointer.
Return value Your listener. Nanoconda sends market data and order requests to it. Do not return NULL.

There are two listeners with opposite directions:

Listener Called by Implemented by
The one you return Nanoconda: market data and order requests Your plugin
reports Your plugin: acknowledgements, fills, rejects Nanoconda

Callbacks Your Plugin Receives

Order requests

The same callbacks used by Trace File replay:

Callback When
onneworder(const order*) A new order arrives
onmodifyorder(const order*) A modify request arrives. price, quantity and triggerPrice hold the requested values
oncancelorder(const order*) A cancel request arrives

Cancel-all and flatten requests never reach the plugin as such: Nanoconda turns them into single cancels and new orders before they are sent.

Market data

Your plugin receives the same market data callbacks as a strategy in the same application: onsecurity, onbook, ontrade, onbookorder, ongap, onsnapshotstart, onsnapshotend, onlive, ontradebust and ontradestatistics.

Keep what you need from onsecurity (tick size, multiplier, price bands): nanoconda::getSecurity() and nanoconda::getSymbolName() are not available inside an exchange plugin.

Callbacks you can leave empty

listener requires onorderack, oncancelack, onmodifyack, onorderreject, onmodifyreject, oncancelreject, onfill, onout and onorderstatus. Nanoconda never calls them on your plugin's listener. Implement them as empty functions.


Reporting Back

Call the matching method on reports:

Method Use it to
onorderack(const order*) Accept a new order
onorderreject(const order*) Reject a new order
onmodifyack(const order*) Confirm a modify
onmodifyreject(const order*) Reject a modify
oncancelack(const order*) Confirm a cancel
oncancelreject(const order*) Reject a cancel
onfill(const order*) Report a fill, full or partial
onfillcorrect(const order*) Correct a reported fill
onfillcancel(const order*) Cancel (bust) a reported fill
onout(const order*) Remove an order without a cancel request, for example an expired order or the unfilled rest of a fill-and-kill order
onorderstatus(const order*) Report the current state of an order
onerror(const error*) Report an error that is not an answer to one request

Filling in the answer

Start every answer from the order you received in the request and change only what the answer is about:

Field Set it to
orderId, symbolId, side, type, customId Keep as received. Nanoconda matches the answer to the order by these
price, quantity, triggerPrice The order's working values. For a modify acknowledgement, the new values
quantityLast, priceLast Fills only: quantity and price of this fill
quantityFilled Fills only: total filled so far, including this fill. Nanoconda keeps its own count; this value is for your records
execId Fills only: your own execution number. It appears in the log
exchangeOrderId Optional: your own order number
transactiontime Your plugin's market time for the event (see Time)
code Rejects: a reason code, for example nanoconda::ORDER_NOT_FOUND or nanoconda::ORDER_TYPE_NOT_SET
exchangeReason Rejects: leave 0 unless you use CME reject codes. Some interfaces show this value as CME reject text

You do not need to set status. Nanoconda sets it from the method you call. For a fill it decides partial or complete by comparing the filled quantity with the order quantity it has on record.

After the last fill an order is complete. Do not send onout() or oncancelack() for it.

Example

void onneworder(const nanoconda::order* o)
{
   nanoconda::order answer = *o;
   answer.transactiontime = _marketTime;
   _reports->onorderack(&answer);

   answer.priceLast = o->price;
   answer.quantityLast = o->quantity;
   answer.quantityFilled = o->quantity;
   answer.execId = ++_execId;
   _reports->onfill(&answer);
}

Time

Use market time, not the system clock. Keep your own clock from the market data your plugin receives (exchangetime or transactiontime of books and trades) and put it in transactiontime of your answers.

-L (simulated exchange latency) applies only to the built-in simulator. Requests reach your plugin as soon as Nanoconda sends them. If you want latency, hold the request in your plugin and answer it later, for example on the first market data update after your chosen delay.


Threading

Nanoconda never calls your plugin from two threads at the same time.

Application Calls into your plugin come from
cmebacktester, dbnbacktester The market data replay thread
simulator The market data thread or the simulator thread, one at a time

In the backtesters, every market data event is processed in this order:

  1. Your plugin receives the event.
  2. Reports you made in step 1 are delivered to the strategy.
  3. The strategy receives the event.
  4. Orders the strategy sent in steps 2 and 3 are passed to your plugin.
  5. Reports you made in step 4 are delivered to the strategy.

reports can be called from any thread, including threads your plugin starts itself. In the backtesters, report from inside the callbacks to get the same result on every run; reports from other threads are delivered with the next market data event.

Do not block inside the callbacks. In the simulator application a slow callback delays every order and every report.


Sample Plugin

src/sampleexchange.cpp in the Nanoconda package is a small working plugin to start from:

  • accepts limit and market orders, rejects other order types
  • fills a limit order in full when the opposite best price reaches its price, or when a trade prints through it
  • fills a market order at the opposite best price
  • handles modify and cancel, rejects requests for unknown orders
  • optional argument --fill-on-touch: also fill when a trade prints exactly at the order price

It does not model queue position, partial fills or latency. These are the parts you replace with your own logic.

Build it with the provided Makefile:

make sampleexchange                                  # sampleexchange.so
make sampleexchangewasm WASI_SDK=/opt/wasi-sdk       # sampleexchange.wasm

Building

An exchange plugin is built exactly like a strategy plugin.

Native:

g++ -std=c++17 -shared -fPIC -I ../include myexchange.cpp -o myexchange.so -L ../lib -lnanoconda -pthread

WebAssembly: use the commands from Building & Running (C++). If C++ code in a .wasm plugin throws an exception that is not caught, the plugin stops; Nanoconda writes the exception type to the log and creates crash files with a backtrace and a memory dump, the same as for any other plugin failure.

Exchange plugins are written in C++. A strategy and an exchange plugin can be in the same source file: define both init_nanoconda_plugin and init_nanoconda_exchange, and pass the same file to -i and -X.


Running

Add -X with your plugin file. Arguments for your plugin go in --exchange-args, in quotes. Arguments for your strategy still go after --.

nanoconda-cli -a dbnbacktester -c configs/dbn-playback.xml -i myStrategy.so -X myexchange.so
nanoconda-cli -a cmebacktester -c configs/cme-market-data-config.xml -i myStrategy.wasm \
    -X myexchange.wasm --exchange-args "--fill-on-touch" -- strategyArg1
nanoconda-cli -a simulator -c configs/simulator-session-xcme.xml -X myexchange.so > simulator.out &
Option Description
-X FILE, --exchange-plugin FILE Exchange plugin to use instead of the built-in simulator: .so or .wasm
--exchange-args "ARGS" Arguments for the plugin, separated by spaces

Without -X the applications use the built-in simulator as before.

If the plugin cannot be loaded or init_nanoconda_exchange is missing, the application prints the reason and exits. A .so plugin whose init_nanoconda_exchange returns NULL is treated the same way.

A .wasm exchange plugin writes its log to wasmexchange.log in the working directory.


Connecting to an External Venue

The same interface can forward orders to another venue: send the order out in onneworder(), and call reports->onorderack() and reports->onfill() when the venue answers, from your own network thread if needed.

Current limits for this use:

  • The plugin runs only in the simulator, cmebacktester and dbnbacktester applications.
  • Market data and instrument definitions come from the application's feed (CME or Databento). A plugin cannot yet publish another venue's instruments or market data.
  • There is no way yet to report the venue connection as down or up to Nanoconda.

Notes

  • Pre-trade risk limits are applied in the simulator application before an order reaches your plugin. The backtesters do not apply them, the same as with the built-in simulator.
  • Quantities up to 4095 per order are supported.
  • Spread leg fills (onlegfill) cannot be reported.
  • The strategy sees the recorded market data, not your plugin's view of the book. Your own resting orders are not added to the book the strategy receives.
  • If a .wasm exchange plugin fails, it stops answering; the application keeps running. Check the log and the crash files.