This is a barebones API library for Stockfighter, the trading game by the Starfighter crew.

It provides functions to interact with the Stock as well as the GM APIs.

Note: these are the versions this library was tested with. It's possible using older versions is compatible.

• python: 3.4.3+
• requests: 2.8.1+
• ws4py: 0.3.4+

The api is initialised using your api key and - optionally - a python logging level.

Note: the default log level is logging.INFO.

from Stockfighter.Api import StockFighterApi
import logging

api_key = '1234567890ABCDE'
log_level = logging.DEBUG
api = StockFighterApi(api_key, log_level)

The API will pass your api key along where needed. There is no need for you to keep track of this.

The API library is not stateful! That means all calls take every parameter the raw API requires. If you want ease-of-use - e.g. store venue, account_id, etc during a level - you will need to provide this in your own code.

All calls to the API will return the response - be it ok or error - as a JSON object.

# call the heartbeat endpoint
json = api.heartbeat()
print(json)

Will print

{'error': '', 'ok': True}

Returns the heartbeat of the main API.

json = api.heartbeat()

See https://starfighter.readme.io/docs/heartbeat for responses and more info.

Returns the heartbeat of a specific venue

venue = "ABCD"
json = api.venue_heartbeat(venue)

See https://starfighter.readme.io/docs/venue-healthcheck for responses and more info.

Returns the list of stocks (tickers) on the venue.

venue = "ABCD"
json = api.venue_stocks(venue)

See https://starfighter.readme.io/docs/list-stocks-on-venue for responses and more info.

Returns all the orders placed by your account.

venue = "ABCD"
my_account = "ABCDTRADER09"
json = api.account_orders(venue, my_account)

See https://starfighter.readme.io/docs/status-for-all-orders for responses and more info.

Returns all orders - closed or open - for your account.

venue = "ABCD"
my_account = "ABCDTRADER09"
target_stock = "TICKER01"
json = api.account_stock_orders(venue, my_account, target_stock)

See https://starfighter.readme.io/docs/status-for-all-orders-in-a-stock for responses and more info.

Returns an anonimised view of the ask and bid status of a stock, i.e. the orderbook.

venue = "ABCD"
target_stock = "TICKER01"
json = api.stock_orderbook(venue, target_stock)

See https://starfighter.readme.io/docs/get-orderbook-for-stock for responses and more info.

Gets a quote for a specific stock.

venue = "ABCD"
target_stock = "TICKER01"
json = api.stock_quote(venue, target_stock)

See https://starfighter.readme.io/docs/a-quote-for-a-stock for responses and more info.

Puts in an order in a given direction, at the given price, for the given stock using the given orde type.

venue = "ABCD"
target_stock = "TICKER01"
my_account = "ABCDTRADER09"
price = 1000 # this is actually $10.00!! The API ignores the decimal
quantity = 5
direction = 'buy' # use 'sell' to sell, obviously
order_type = 'market'
json = api.stock_order(venue, my_account, target_stock, price, quantity, direction, order_type)

See https://starfighter.readme.io/docs/place-new-order for responses and more info, especially order types.

Returns the current status of an existing order. The order_id is received when you first made the order.

order_id = "1234"
venue = "ABCD"
target_stock = "TICKER01"
json = api.stock_order_status(venue, target_stock, order_id)

See https://starfighter.readme.io/docs/status-for-an-existing-order for responses and more info.

Cancels an outstanding order.

order_id = "1234"
venue = "ABCD"
target_stock = "TICKER01"
json = api.stock_order_cancel(venue, target_stock, order_id)

See https://starfighter.readme.io/docs/cancel-an-order for responses and more info.

If you fail to provide a callback function the default message handler will log the raw message (level = debug), as well as a pretty-printed version of the actual JSON (level = info).

Your callback function must have the following signature:

import json
def received_message(self, m):
    try:
        if m.is_text:
            msg = json.loads(m.data.decode('utf-8'))
    except ValueError:
        pass

Please see https://ws4py.readthedocs.org/en/latest/sources/clienttutorial/ for more details on handling the sockets (including dealing with 5 minute timeouts on the Stockfighter API).

Subscribes to the tickertape socket for a particular stock and a given account_id. Messages are handled by the callback function (if provided).

venue = "ABCD"
target_stock = "TICKER01"
my_account = "ABCDTRADER09"
# This returns a WebSocketClient object which is already actively listening
my_socket = stock_ticker_socket(venue, target_stock, my_account)

See https://starfighter.readme.io/docs/quotes-ticker-tape-websocket for responses and more info.

Subscribes to the execution socket for a particular stock and a given account_id. Messages are handled by the callback function (if provided).

venue = "ABCD"
target_stock = "TICKER01"
my_account = "ABCDTRADER09"
# This returns a WebSocketClient object which is already actively listening
my_socket = stock_execution_socket(venue, target_stock, my_account)

See https://starfighter.readme.io/docs/executions-fills-websocket for responses and more info.

Subscribes to the tickertape socket for all stocks in the venue, for a given account_id. Messages are handled by the callback function (if provided).

venue = "ABCD"
my_account = "ABCDTRADER09"
# This returns a WebSocketClient object which is already actively listening
my_socket = stock_ticker_socket(venue, my_account)

See https://starfighter.readme.io/docs/quotes-ticker-tape-websocket for responses and more info.

Subscribes to the executions socket for all stocks in the venue, for a given account_id. Messages are handled by the callback function (if provided).

venue = "ABCD"
my_account = "ABCDTRADER09"
# This returns a WebSocketClient object which is already actively listening
my_socket = stock_ticker_socket(venue, my_account)

See https://starfighter.readme.io/docs/executions-fills-websocket for responses and more info.

Please note that these calls are not documented on the Stockfighter documentation site.

Starts a new level, based on the name/id. Note that the API will resume a level instead if it's already running.

level_id = 'the_name_of_my_level'
json = api.gm_start(level_id)

The JSON returned for a succesful call looks like this:

{
    "account": "EXB123456", 
    "instanceId": 314159, 
    "instructions": {
        "Instructions": "# Welcome to Your New Job...", 
        "Order Types": "Stock exchanges..."
    }, 
    "ok": true, 
    "secondsPerTradingDay": 5, 
    "tickers": [
        "FOOBAR"
    ], 
    "venues": [
        "TESTEX"
    ]
}

Returns the status of a - presumably - running level instance.

# Got this from my start
instance = '123'
json = api.gm_status(instance)

The JSON returned for a succesful call looks like this:

{
    "details": {
        "endOfTheWorldDay": 499, 
        "tradingDay": 1
    }, 
    "done": False, 
    "id": 123, 
    "ok": True, 
    "state": "open"
}

Stops a running level instance.

# I'm fed up with my level
instance = '123'
json = api.gm_stop(instance)

The JSON returned for a succesful call looks like this:

{
  "ok": True, 
  "error": ''
}

Restarts a running level instance.

# Once more
instance = '123'
json = api.gm_restart(instance)

The JSON returned for a succesful call looks like this:

{
  "ok": True, 
  "error": ''
}

Resumes a running level instance. Note: if you're not sure just call start instead and it will auto-resume. Same usage as start.

There are several other API and GM calls in the library which aren't explicitly documented here. Some may be useful for debugging purposes, but that is left as an exercise to the reader.