Introduction

This is the documentation of Project Matthiola, a distributed commodities OTC electronic trading system, instructed by Morgan Stanley.

Architecture

• Receiver (FIX server)
• Matcher
• Server (HTTP Server)
• Broadcaster (WebSocket Server)

API /server

The RESTful API for traders and brokers. Please visit apiary for more details.

Authentication

Matthiola uses JWT, or JSON Web Token for authentication. Traders should send a request to sign a contract with the broker, then the broker will return the access token.

Code	Name	Description	Value
sub	Subject	Identifies the subject of the JWT.	Firm ID
aud	Audience	Identifies the recipients that the JWT is intended for.	Firm Name
exp	Expiration time	Identifies the expiration time on or after which the JWT must not be accepted for processing. The value should be in NumericDate format.	Defined according to the request
iat	Issued at	Identifies the time at which the JWT was issued.	The current time
jti	JWT ID	Case sensitive unique identifier of the token even among different issuers.	UUID

Sign a Contract

Sign a contract with the broker.

HTTP Request

POST /server/api/v1/auth

Request

{
    "firm_name": "Matthiola",
    "expires_at": "2018-08-22T16:52:23Z"
}

Request

Param	Description
firm_name	Name of firm to be signed
expires_at	Expire time in ISO 8601

Response

{
    "data": {
        "firm_id": 1,
        "firm_name": "Matthiola",
        "credit": 100,
        "token": "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
    }
}

Response

Param	Description
firm_id	ID of firm stored in the database
firm_name	Name of firm to be signed
credit	Credit of the firm
token	Access token generated by server

Validate

Validate the token generated by the broker.

HTTP Request

GET /server/api/v1/auth

Request

Headers

Authorization: Bearer token

Response

{
    "data": {
        "firm_id": 1,
        "firm_name": "Matthiola",
        "credit": 100,
        "token": "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
    }
}

Response

Param	Description
firm_id	ID of firm stored in the database
firm_name	Name of firm to be signed
credit	Credit of the firm
token	Access token generated by server

Trader

List Orders

List your current open orders.

HTTP Request

GET /server/api/v1/orders

Parameters

Param	Description	Required	Default
futures_id	Specific futures	False
trader_name	Specific trader	False
status	Specific status	False
page	Page number	False	0

Request

Headers

Authorization: Bearer token

Response

{
    "count": 1,
    "data": [
        {
            "order_id": "cc8115fb-6b15-11e8-aebf-6a000223d540",
            "order_type": "LIMIT",
            "side": "SELL",
            "futures_id": "GC_SEP18",
            "firm": "Sender",
            "trader_name": "John Doe",
            "quantity": "14.21",
            "open_quantity": "14.21",
            "price": "50.01",
            "stop_price": "0",
            "status": "NEW",
            "created_at": "2018-06-08 20:25:07 +0800 CST",
            "updated_at": "2018-06-08 20:25:07 +0800 CST"
        }
    ],
    "page": 7,
    "total": 61
}

Response

Param	Description
count	Current count of data of orders
data	Array of data of orders
page	Page number
total	Total count of data of orders

List Trades

List your current open trades.

HTTP Request

GET /server/api/v1/trades

Parameters

Param	Description	Required	Default
futures_id	Specific futures	False
trader_name	Specific trader	False
page	Page number	False	0

Request

Headers

Authorization: Bearer token

Response

{
    "count": 1,
    "data": [
        {
            "trade_id": "3bf4921d-68c0-11e8-9c81-6a000223d540",
            "quantity": "10",
            "price": "50",
            "futures_id": "GC_SEP18",
            "initiator": {
                "firm": "Matthiola",
                "side": "SELL",
                "trader": "John Doe"
            },
            "completion": {
                "firm": "Matthiola",
                "side": "BUY",
                "trader": "John Doe"
            },
            "trade_time": "2018-06-08 20:52:23 +0800 CST"
        }
    ],
    "page": 6,
    "total": 51
}

Response

Param	Description
count	Current count of data of trades
data	Array of data of trades
page	Page number
total	Total count of data of trades

Broker

Sign as admin

HTTP Request

POST /server/api/v1/admin/auth

Request

{
    "name": "John Doe",
    "expires_at": "2018-08-22T16:52:23Z"
}

Request

Param	Description
name	Name of admin
expires_at	Expire time in ISO 8601

Response

{
    "data": {
        "name": "John Doe",
        "token": "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
    }
}

Response

Param	Description
fname	Name of admin
token	Admin access token generated by server

List Orders

List all orders.

HTTP Request

GET /server/api/v1/admin/orders

Parameters

Param	Description	Required	Default
page	Page number	False	0

Request

Headers

Authorization: Bearer admin token

Response

{
    "count": 1,
    "data": [
        {
            "order_id": "cc8115fb-6b15-11e8-aebf-6a000223d540",
            "order_type": "LIMIT",
            "side": "SELL",
            "futures_id": "GC_SEP18",
            "firm": "Sender",
            "trader_name": "John Doe",
            "quantity": "14.21",
            "open_quantity": "14.21",
            "price": "50.01",
            "stop_price": "0",
            "status": "NEW",
            "created_at": "2018-06-08 20:25:07 +0800 CST",
            "updated_at": "2018-06-08 20:25:07 +0800 CST"
        }
    ],
    "page": 7,
    "total": 61
}

Response

Param	Description
count	Current count of data of orders
data	Array of data of orders
page	Page number
total	Total count of data of orders

List Trades

List all trades.

HTTP Request

GET /server/api/v1/admin/trades

Parameters

Param	Description	Required	Default
page	Page number	False	0

Request

Headers

Authorization: Bearer admin token

Response

{
    "count": 1,
    "data": [
        {
            "trade_id": "3bf4921d-68c0-11e8-9c81-6a000223d540",
            "quantity": "10",
            "price": "50",
            "futures_id": "GC_SEP18",
            "initiator": {
                "firm": "Matthiola",
                "side": "SELL",
                "trader": "John Doe"
            },
            "completion": {
                "firm": "Matthiola",
                "side": "BUY",
                "trader": "John Doe"
            },
            "trade_time": "2018-06-08 20:52:23 +0800 CST"
        }
    ],
    "page": 6,
    "total": 51
}

Response

Param	Description
count	Current count of data of trades
data	Array of data of trades
page	Page number
total	Total count of data of trades

WebSocket /broadcaster

Order Book

{
    "type": "order_book",
    "mode": "snapshot",
    "futures_id": "GC_SEP18",
    "data": {
        "bids": [
            ["49.99","133.95"]
        ],
        "asks":[
            ["50.01","25.77"]
        ]
    }
}

Traders would get snapshots of order books after order books had been changed. bids and asks are arrays of [price, size] tuples and represent the entire order book.

Trade

Snapshot

{
    "type": "trade",
    "mode": "snapshot",
    "futures_id": "GC_SEP18",
    "data": [
        {
            "price": "50.01",
            "quantity": "7.35",
            "time": "2018-06-08 20:47:37 +0800 CST"
        }
    ]
}

When subscribing to the channel, it will first send a message with the type trade, mode snapshot and the corresponding futures_id and data array with data of trades.

Update

{
    "type": "trade",
    "mode": "update",
    "futures_id": "GC_SEP18",
    "data": {
        "price": "50.01",
        "quantity": "7.35",
        "time": "2018-06-08 20:47:37 +0800 CST"
    }
}

Subsequent updates will have the mode update, with the corresponding data of the single trade updated.

FIX

The FIX, or Financial Information eXchange protocol is an electronic communications protocol initiated in 1992 for international real-time exchange of information related to the securities transactions and markets.

Messages

Header

Reference: https://legacy.fixspec.com//FIX/5.0-SP2/Standard-Header

Tag	Name	Type	Description
8	BeginString	String	Must be FIXT.1.1.
9	BodyLength	Length	Message length, in bytes, forward to the CheckSum field.
35	MsgType	String	Defines message type.
49	SenderCompID	String	The ID of the sender.
56	TargetCompID	String	The ID of the target.
34	MsgSeqNum	SeqNum	Integer message sequence number.
52	SendingTime	UTCTimestamp	Time of message transmission.
50	SenderSubID	String	The name of the trader.
1128	ApplVerID	Char	Must be 9.

Trailer

Reference: https://legacy.fixspec.com/FIX/5.0-SP2/Standard-Trailer

Tag	Name	Type	Description
10	CheckSum	String	Checksum.

New Order Single (MsgType = D)

Sent by the client to enter an order.

Reference: https://legacy.fixspec.com/FIX/5.0-SP2/New-Order-Single

Tag	Name	Type	Description
11	ClOrdID	UUID	Unique identifier of the order as assigned by institution or by the intermediary with closest association with the investor.
40	OrdType	Char	Order type.
54	Side	Char	Must be 1 to buy or 2 to sell.
55	Symbol	String	Representation of the futures. E.g. CG_SEP18
38	OrderQty	Qty	Quantity of the futures.
44	Price	Price	Required for limit and stop limit OrdTypes.
99	StopPx	Price	Required for stop market and stop limit OrdTypes.
60	TransactTime	UTCTimestamp	Time this order request was initiated/released by the trader, trading system, or intermediary.

Order Cancel Request (MsgType = F)

The order cancel request message requests the cancellation of all of the remaining quantity of an existing order. Note that the Order Cancel/Replace Request should be used to partially cancel (reduce) an order).

Reference: https://legacy.fixspec.com/FIX/5.0-SP2/Order-Cancel-Request

Tag	Name	Type	Description
11	ClOrdID	UUID	Unique ID of cancel request as assigned by the institution.
37	OrderID	UUID	OrderID of the order to be canceled.
55	Symbol	String	Symbol of the order to cancel.

Mapping

OrdType

Value	Meaning
1	MARKET
2	LIMIT
3	STOP MARKET
4	STOP LIMIT

Side

Value	Meaning
1	BUY
2	SELL

OrdStatus

Value	Meaning
0	NEW
1	PARTIALLY_FILLED
2	FILLED
3	CANCELED
8	REJECTED
A	PENDING_NEW

Authors

• Yuchen Cheng @rudeigerc
• Jiawei Lyu @ljw9609
• Jason Liu @jasonliu747

Errors

Error Code	Meaning
400	Bad Request
401	Unauthorized
404	Not Found
409	Conflict
500	Internal Server Error

Parameters

Example

{
    "error": {
        "status": 401,
        "title": "Unauthorized",
        "message": "Invalid token."
    }
}

Param	Description
status	Status code
title	Description of error
message	Message of error

References

• GDAX | API Reference
• commodity-trading-system