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:
- Your plugin receives the event.
- Reports you made in step 1 are delivered to the strategy.
- The strategy receives the event.
- Orders the strategy sent in steps 2 and 3 are passed to your plugin.
- 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 cmebacktester -c configs/cme-market-data-config.xml -i myStrategy.wasm \
-X myexchange.wasm --exchange-args "--fill-on-touch" -- strategyArg1
| 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,cmebacktesteranddbnbacktesterapplications. - 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
simulatorapplication 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
.wasmexchange plugin fails, it stops answering; the application keeps running. Check the log and the crash files.