Connecting

To connect to the feed, you will need to generate an SSH public/private key pair, and pass your public key on to Mustard Systems, who will provide you with a username. Your private key must be kept private from everyone -- if you suspect that it may have been exposed over an unencrypted channel or leaked in any way, you should generate a new pair and send the new public key to Mustard Systems.

To establish the initial SSH connection, you should use your username as well as your private key for authentication. After connection, the client should then send this message::

{ "request": "init", "msg": {} }

Please note, if an "init" request isn't made within 10 seconds of connecting to xenophobe you will be disconnected. We will not start heartbeating a connection until after this "init" request has been made.

After this, the server will start sending push messages detailing the available data for subscription.

The response to the "init" request will contain a unique session_id. Please provide this session id when raising any queries regarding the messages received for a given session.

If we have to close your connection for any reason, you will receive a push message::

{ "mode": "push", "status": "error", "session_id": <session_id>, reason": <reason> }

where <reason> will be one of: "no init sent", "max connections hit", "connection rate limit hit", "slow reader", "internal disconnection requested", or "service error".

In addition to rate limiting connections, API requests are also rate limited. The response to a request that breached a rate limit will be as follows::

{ "mode": "resp", "status": "error", "msg": "API limit breached", "request_id": <request_id> }

where request_id will only be present if you provided a request ID with the original request.

Recovering from disconnection

If your connection is terminated for any reason (including deliberately on your part due to a missed heartbeat, you should try to reconnect as soon as possible, reconnection attempts should be made with a 30 second interval. While you do not have an open connection, you must treat all markets as suspended. Once your connection is re-established, you must treat each market as suspended until you have received a <market-status-update> for that market. Until you receive that market update, it is not possible to know if any changes occurred to the market since you were last connected.

Details of SSH Connection

Once the SSH connection is established, the client should create a channel of type “session” and request a “shell” within that channel. All communication takes place on the “session” channel. A command line client will generally do this correctly. Some libraries may abstract away this level of detail as well.

If you are using a command line client to connect, either for testing or as a subprocess of the live client, you should tell it not to try to allocate a pseudo-tty. For the SSH client in most Linux distributions, this corresponds to the “-T” option. PuTTY for Windows uses the same option. It isn’t harmful to attempt to allocate a pseudo-tty, but it will result in a warning message.