15 KiB
Server API
The Gekko project has three major components:
- Actual Gekko instance
- A nodejs server that:
- starts and manages gekkos
- broadcasts all updates from all gekkos and tracks their overall state
- has API calls to query and manage historical data (by importing more for example)
- A web UI (vue frontend project)
The nodejs server can also be used standalone as a webserver in combination with your own software (such as a new UI, a mobile app or a higher level backtester), see other software for examples).
The server exposes two different APIs: A websocket API to push gekko updates and a REST API for everything else.
When you run node gekko --ui it will automatically start a server. You can also do this manually by running:
cd gekko/web
node server
The server will now run on the host/port configured in gekko/web/vue/public/UIConfig.js (under api.host).
REST API
GET /api/info
Get version information of current running Gekko Server.
NOTE: The API does not have dedicated versioning, instead it uses the version of the complete Gekko project.
response
{ "version": "0.6.0" }
GET /api/strategies
Get all strategies known to this Gekko. The value of the params key is a TOML string.
response
[
{
"name": "DEBUG_single-advice",
"params": ""
},
{
"name": "DEBUG_toggle-advice",
"params": ""
},
{
"name": "DEMA",
"params": "weight = 21\n\n[thresholds]\ndown = -0.025\nup = 0.025\n"
},
{
"name": "MACD",
"params": "short = 10\nlong = 21\nsignal = 9\n\n[thresholds]\ndown = -0.025\nup = 0.025\npersistence = 1"
},
// etc.
]
GET /api/apiKeys
Returns a list of exchanges that this Gekko has API keys stored for.
NOTE: for security reasons the Gekko never exposes the API keys themselves.
response
["bitstamp","bitfinex"]
GET /api/imports
Returns a list of currently running data imports.
response
[
{
"watch": {
"exchange": "poloniex",
"currency": "USDT",
"asset": "BTC"
},
"id": "765606096903592",
"latest": "2018-04-03T07:13:00Z",
"from": "2018-04-03 05:13",
"to": "2018-07-03 05:13",
"done": false
}
]
GET /api/gekkos
Returns a list of currently running and archived Gekkos.
response
{
"live": {
"2018-07-03-13-14-papertrader-384222057313623": {
"mode": "realtime",
"config": {
// complete config that was passed when creating
},
"id": "2018-07-03-13-14-papertrader-384222057313623",
"type": "leech",
"logType": "papertrader",
"active": true,
"stopped": false,
"errored": false,
"errorMessage": false,
"events": {
"initial": {
"candle": {
"id": 419824,
"start": "2018-07-03T04:47:00.000Z",
"open": 6664.79999887,
"high": 6664.79999887,
"low": 6659.99999989,
"close": 6659.99999989,
"vwp": 6662.402395386147,
"volume": 0.001202,
"trades": 3
},
"portfolioChange": {
"asset": 1,
"currency": 100
},
"portfolioValueChange": {
"balance": 6759.99999989
}
},
"latest": {
"candle": {
"id": 419849,
"start": "2018-07-03T05:12:00.000Z",
"open": 6643.21466865,
"high": 6656.58532982,
"low": 6643.01,
"close": 6656,
"vwp": 6643.884436854498,
"volume": 1.9966113400000003,
"trades": 15
},
"portfolioChange": {
"asset": 1,
"currency": 100
},
"portfolioValueChange": {
"balance": 6756
}
}
},
"start": "2018-07-03T05:14:23.582Z",
"latestUpdate": "2018-07-03T05:14:24.090Z"
}
},
"archive": {}
}
GET /api/exchanges
Returns a list of supported exchanges with meta information (such as supported features and tradable markets).
response
{
"name": "Bitstamp",
"slug": "bitstamp",
"currencies": [
"USD",
// and more
],
"assets": [
"BTC",
// and more
],
"maxTradesAge": 60,
"maxHistoryFetch": null,
"markets": [
{
"pair": [
"USD",
"EUR"
],
"minimalOrder": {
"amount": 5,
"unit": "currency"
},
"precision": 2
},
// and more
],
"requires": [
"key",
"secret",
"username"
],
"fetchTimespan": 60,
"tid": "tid",
"tradable": true
}
POST /api/addApiKey
Adds an API key for an exchange account to Gekko. As of now only 1 API keypair can be added per exchange.
request
{
"exchange": "bitstamp",
"values": {
"key": "x",
"secret": "y"
}
}
response
{
"status": "ok"
}
POST /api/removeApiKey
Removes an API key from Gekko.
request
{
"exchange": "bitstamp"
}
response
{
"status": "ok"
}
POST /api/scan
Scans a daterange to find all datasets for a specific market.
request
{
"watch": {
exchange: "bitstamp",
"currency": "USD",
"asset": "BTC"
}
}
response
[
{
"to": 1464787560,
"from": 1464783960
},
{
"to": 1479115560,
"from": 1471112760
}
]
POST /api/scansets
Scans the database for all datasets for all markets.
request
{}
response
{
"datasets": [
{
"exchange": "bitfinex",
"currency": "USD",
"asset": "BTC",
"ranges": [
{
"to": 1508551500,
"from": 1508493900
}
]
},
{
"exchange": "binance",
"currency": "USDT",
"asset": "BTC",
"ranges": [
{
"to": 1514351280,
"from": 1510632480
},
{
"to": 1522915680,
"from": 1522678080
}
]
},
],
"errors": [
{
"exchange": "poloniex",
"currency": "BTC",
"asset": "BTC"
}
]
}
POST /api/backtest
Perform a backtest.
request
(a valid gekko config object)
Tweak the config.backtestResultExporter.data object to control what is included in the output. For example skip stratCandles if you only care about the final profit report. This way the server won't include megabytes of candle data in the output.
{
"watch": {
"exchange": "poloniex",
"currency": "USDT",
"asset": "ETH"
},
"paperTrader": {
"feeMaker": 0.25,
"feeTaker": 0.25,
"feeUsing": "maker",
"slippage": 0.05,
"simulationBalance": {
"asset": 1,
"currency": 100
},
"reportRoundtrips": true,
"enabled": true
},
"tradingAdvisor": {
"enabled": true,
"method": "MACD",
"candleSize": 60,
"historySize": 10
},
"MACD": {
"short": 10,
"long": 21,
"signal": 9,
"thresholds": {
"down": -0.025,
"up": 0.025,
"persistence": 1
}
},
"backtest": {
"daterange": {
"from": "2016-06-01T11:57:00Z",
"to": "2016-11-13T14:57:00Z"
}
},
"backtestResultExporter": {
"enabled": true,
"writeToDisk": false,
"data": {
"stratUpdates": false,
"roundtrips": true,
"stratCandles": true,
"stratCandleProps": [
"open"
],
"trades": true
}
},
"performanceAnalyzer": {
"riskFreeReturn": 2,
"enabled": true
}
}
response
{
"performanceReport": {
"startTime": "2018-04-02 14:08:00",
"endTime": "2018-04-05 04:08:00",
"timespan": "3 days",
"market": -2.159980297428632,
"startBalance": 7083.86,
"balance": 7424.849452897501,
"profit": 340.989452897501,
"relativeProfit": 4.813610840664566,
"yearlyProfit": 48210.518806418906,
"relativeYearlyProfit": 680.5684867631334,
"startPrice": 6983.86,
"endPrice": 6833.01,
"trades": 3,
"exposure": 0.3709677419354839,
"sharpe": null,
"downside": null,
"alpha": 343.14943319492966
},
"roundtrips": [
{
"id": 0,
"entryAt": 1522685280,
"entryPrice": 7019.99,
"entryBalance": 7119.6899337771,
"exitAt": 1522768080,
"exitPrice": 7365,
"exitBalance": 7447.19106625,
"duration": 82800000,
"pnl": 327.5011324729003,
"profit": 4.599935327508788
},
// and more
],
"stratCandles": [
{
"open": 6990.06,
"start": 1522678080
},
// and more
],
"trades": [
{
"id": "trade-1",
"adviceId": "advice-1",
"action": "buy",
"cost": 0.30000000000000027,
"amount": 1.01420229,
"price": 7019.99,
"portfolio": {
"asset": 1.08661475,
"currency": 0
},
"balance": 7119.6899337771,
"date": 1522685280
},
// and more
]
}
POST /api/import
Start a data import.
request
(a valid gekko config object)
{
"watch": {
"exchange": "poloniex",
"currency": "USDT",
"asset": "BTC"
},
"importer": {
"daterange": {
"from": "2018-04-03 05:46",
"to": "2018-07-03 05:46"
}
},
"candleWriter": {
"enabled": true
}
}
response
NOTE: this only contains information regarding the started import, updates are pushed through the websocket.
{
"watch": {
"exchange": "poloniex",
"currency": "USDT",
"asset": "BTC"
},
"id": "7324830525419355",
"latest": "",
"from": "2018-04-03 05:46",
"to": "2018-07-03 05:46"
}
POST /api/startGekko
Start a gekko instance
request
(a valid gekko config object)
In order to start a stratRunner, pass a config object that includes plugins required for a stratrunner (such as paperTrader, tradingAdvisor and performanceAnalyzer).
{
"watch": {
"exchange": "poloniex",
"currency": "USDT",
"asset": "BTC"
},
"candleWriter": {
"enabled": true,
},
"type": "market watcher",
"mode": "realtime"
}
response
NOTE: this only contains information regarding the started gekko, updates from are pushed through the websocket.
{
"mode": "realtime",
"config": {
// config that was passed in the request
},
"id": "2018-07-03-13-49-watcher-404457189518044",
"type": "watcher",
"logType": "watcher",
"active": true,
"stopped": false,
"errored": false,
"errorMessage": false,
"events": {
"initial": {},
"latest": {}
},
"start": "2018-07-03T05:49:06.685Z"
}
POST /api/stopGekko
Stop a gekko instance
request
{
"id": "2018-07-03-13-49-watcher-404457189518044"
}
response
{
"status": "ok"
}
POST /api/deleteGekko
Delete a stopped gekko instance from the archive.
request
{
"id": "2018-07-03-13-49-watcher-404457189518044"
}
response
{
"status": "ok"
}
POST /api/getCandles
Load candles directly from the database.
request
{
"watch": {
"exchange": "poloniex",
"currency": "USDT",
"asset": "BTC"
},
"daterange": {
"to": "2018-07-03T05:53:00.000Z",
"from": "2018-07-03T05:40:00.000Z"
},
"candleSize": 1
}
response
[
{
"start": 1530596400,
"open": 6645.49999958,
"high": 6649.83970225,
"low": 6642,
"close": 6642,
"vwp": 6644.840723040122,
"volume": 0.007383000000000001,
"trades": 23
},
{
"start": 1530596460,
"open": 6649.69979936,
"high": 6649.69979936,
"low": 6642,
"close": 6648.89999912,
"vwp": 6645.926390922748,
"volume": 0.007383450000000001,
"trades": 21
},
// etc.
]
Websocket API
A websocket server is started at the basepath of the API. Connecting to it means you'll receive update messages. Messages you send to the server via the websocket connection are completely ignored, to control the server use the REST API instead.
The possible messages are:
import_update
Whenever there is an update regarding a running import.
{
type: 'import_update',
import_id: '7324830525419355',
updates: {
latest: '2018-07-03T05:49:06.685Z',
done: false
}
}
import_error
Whenever there is a fatal error in a running import. After receiving this the import will not continue.
{
type: 'import_error',
import_id: '7324830525419355',
error: "Error string"
}
gekko_new
Whenever a new Gekko has been started.
{
"type": "gekko_new",
"id": "2018-07-03-16-37-watcher-938815758693549",
"state": {
"mode": "realtime",
"config": {
// the complete config that was passed
},
"id": "2018-07-03-16-37-watcher-938815758693549",
"type": "watcher",
"logType": "watcher",
"active": true,
"stopped": false,
"errored": false,
"errorMessage": false,
"events": {
"initial": {},
"latest": {}
},
"start": "2018-07-03T08:37:51.965Z"
}
}
gekko_event
Whenever a gekko instance has a new Gekko event. See the gekko events doc for a list of all possible events and details.
{
"type": "gekko_event",
"id": "2018-07-03-16-37-watcher-938815758693549",
"event": {
"type": "candle",
"payload": {
"start": "2018-07-03T08:38:00.000Z",
"open": 6623.00000066,
"high": 6623.00000066,
"low": 6623.00000066,
"close": 6623.00000066,
"vwp": 6623.00000066,
"volume": 0,
"trades": 0
}
}
}
gekko_stopped
Whenever a Gekko has been stopped, does not fire when the instance had a fatal error. For that see gekko_error.
{
"type": "gekko_stopped",
"id": "2018-07-03-16-37-watcher-938815758693549"
}
gekko_error
Whenever a gekko received a fatal error and crashed.
{
"type": "gekko_error",
"id": "2018-07-03-16-37-watcher-938815758693549",
"error": "Error message"
}
gekko_archived
Whenever the server does not consider the instance to be relevant anymore, fires after a gekko has been stopped or had a fatal error. After this event the gekko instance is placed in an in memory archive. It will stay here stale (as it won't be updated) until it's deleted.
{
"type": "gekko_stopped",
"id": "2018-07-03-16-37-watcher-938815758693549"
}
gekko_deleted
Whenever an archived gekko instance got deleted.
{
"type": "gekko_stopped",
"id": "2018-07-03-16-37-watcher-938815758693549"
}