{"mock":"https://private-anon-f6490fdf24-matthiola.apiary-mock.com","proxy":"https://private-anon-f6490fdf24-matthiola.apiary-proxy.com"}

FORMAT: 1A # Matthiola The API doc of [Matthiola](https://github.com/project-matthiola), a distributed commodities OTC electronic trading system. ## Authentication JSON Web Token # Group Private All actions in group **Private** except `POST /auth` require the `token`. ## Authentication [/auth] ### Sign a Contract [POST] Sign a contract with the broker. + Request (application/json) + Attributes (object) + firm_name: Matthiola (string) + Headers Accept: application/json + Body { "firm_name": "Matthiola", "expires_at": "2018-08-22T16:52:23Z" } + Response 201 (application/json) + Attributes (object) + data (object) + firm_id: 1 (number) + firm_name: Matthiola (string) + credit: 100 (number) + token (string) + Body { "data": { "firm_id": 1, "firm_name": "Matthiola", "credit": 100, "token": "QWxhZGRpbjpvcGVuIHNlc2FtZQ==" } } + Response 409 (application/json) { "error": { "status": 409, "title": "Conflict", "message": "Duplicated firm name." } } ### Validate [GET] Validate the token generated by the broker. + Request + Headers Authorization: Bearer QWxhZGRpbjpvcGVuIHNlc2FtZQ== + Response 200 (application/json) + Attributes (object) + data (object) + firm_id: 1 (number) + firm_name: Matthiola (string) + credit: 100 (number) + token (string) + Body { "data": { "firm_id": 1, "firm_name": "Matthiola", "credit": 100, "token": "QWxhZGRpbjpvcGVuIHNlc2FtZQ==" } } + Response 401 (application/json) { "error": { "status": 401, "title": "Unauthorized", "message": "Invalid token." } } ## Order Collection [/orders{?status,futures_id}] + Attributes (array[Order]) + Parameters + status (string, optional) - new | partially_filled | filled | canceled | all + default: all + futures_id (string, optional) + default: null ### List Orders [GET] List your current open orders. + Request + Headers Authorization: Bearer QWxhZGRpbjpvcGVuIHNlc2FtZQ== + Response 200 (application/json) + Attributes (object) + data (Order Collection) + Body { "data": [{ "order_id": "D4CA73A0-FE34-4B09-991F-E889813B1C15", "order_type": "limit", "side": "buy", "futures_id": "GC_SEP18", "trader_name": "John", "quantity": 50, "open_quantity": 40, "price": 30.12, "status": "open", "created_at": "2018-05-17T12:00:00Z", "updated_at": "2012-05-17T13:00:00Z" }] } + Response 401 (application/json) { "error": { "status": 401, "title": "Unauthorized", "message": "Invalid token." } } + Response 404 (application/json) { "error": { "status": 404, "title": "Not Found", "message": "Invalid futures id." } } ## Order [/orders/{order_id}] + Attributes (object) + order_id (string, required) + order_type: new | partially_filled | filled | canceled (string, required) + side: buy | sell (string, required) + futures_id (string, required) + trader_name: John (string, required) + quantity: 50 (number, required) + open_quantity: 40 (number, required) + price: 30.12 (number, optional) + status: open | canceled | done (string, required) + created_at (string, required) + updated_at (string, optional) + Parameters + order_id (UUID) - The UUID of the order. ### Get an Order [GET] Get a single order by order id. + Request + Headers Authorization: Bearer QWxhZGRpbjpvcGVuIHNlc2FtZQ== + Response 200 (application/json) + Attributes (object) + data (Order) + Body { "data": { "order_id": "D4CA73A0-FE34-4B09-991F-E889813B1C15", "order_type": "limit", "side": "buy", "futures_id": "GC_SEP18", "trader_name": "John", "quantity": 50, "open_quantity": 40, "price": 30.12, "status": "open", "created_at": "2018-05-17T12:00:00Z", "updated_at": "2012-05-17T13:00:00Z" } } + Response 401 (application/json) { "error": { "status": 401, "title": "Unauthorized", "message": "Invalid token." } } + Response 404 (application/json) { "error": { "status": 404, "title": "Not Found", "message": "Invalid order id." } } ### Cancel an Order [DELETE] Cancel a single order by order id. + Request + Headers Authorization: Bearer QWxhZGRpbjpvcGVuIHNlc2FtZQ== + Response 204 + Response 401 (application/json) { "error": { "status": 401, "title": "Unauthorized", "message": "Invalid token." } } + Response 404 (application/json) { "error": { "status": 404, "title": "Not Found", "message": "Invalid order id." } } ## Trades [/trades{?self_only,futures_id}] + Attributes (object) + trade_id (string) + quantity: 50 (number) + price: 30.12 (number) + futures_id (string) + initiator (object) + firm (string) + side (string) + trader (string) + completion (object) + firm (string) + side (string) + trader (string) + trade_time (string) + Parameters + self_only (boolean, optional) + default: false + futures_id (string, optional) + default: null ### Get Trades [GET] List the latest trades for futures. + Request + Headers Authorization: Bearer QWxhZGRpbjpvcGVuIHNlc2FtZQ== + Response 200 (application/json) + Attributes (object) + data (array[Trades]) + Body { "data": [{ "trade_id": "E271129A-D050-4D05-AFEA-5FB630CDF895", "quantity": 50, "price": 30.12, "futures_id": "GC_SEP18", "initiator": { "firm": "A", "side": "buy", "trader": "John" }, "completion": { "firm": "B", "side": "sell", "trader": "Doe" }, "trade_time": "2012-01-01T12:00:00Z" }] } + Response 404 (application/json) { "error": { "status": 404, "title": "Not Found", "message": "Invalid futures id." } } # Group Market Data ## Futures [/futures] + Attributes (object) + futures_id (string, required) + futures_name: Gold (string) + symbol: GC (string) + period: MAY18 (string) ### Get Futures [GET] Get a list of available futures for trading. + Response 200 (application/json) + Attributes (object) + data (array[Futures]) + Body { "data": [ { "futures_id": "GC_MAY18", "futures_name": "Gold", "symbol": "GC", "period": "MAY18" } ] } ## Order Book [/futures/{futures_id}/book{?level}] + Attributes (array) + 295.86 (number) - Price + 10.34 (number) - Quantity + Parameters + futures_id (string) - The id of the futures. + level (number, optional) - The level of the order book. + default: 5 ### Get Order Book [GET] Get a list of open orders for futures. + Response 200 (application/json) + Attributes (object) + data (object) + bids (array[Order Book]) + asks (array[Order Book]) + level: 5 (number) + Body { "data": { "bids": [ [ 295.96, 10.34 ], [ 295.95, 5.67 ], [ 295.93, 3.46 ], [ 295.92, 4.62 ], [ 295.90, 5.17 ] ], "asks": [ [ 295.89, 2.41 ], [ 295.88, 3.45 ], [ 295.87, 1.56 ], [ 295.86, 7.23 ], [ 295.85, 3.41 ] ], "level": 5 } } + Response 404 (application/json) { "error": { "status": 404, "title": "Not Found", "message": "Invalid futures id." } } # Group Administrator ## Admin [/admin] ### Get Trades [GET /admin/trades] List all trades. + Response 200 (application/json) + Attributes (object) + data (array[Trades]) + Body { "data": [{ "trade_id": "E271129A-D050-4D05-AFEA-5FB630CDF895", "quantity": 50, "price": 30.12, "futures_id": "GC_SEP18", "initiator": { "firm": "A", "side": "buy", "trader": "John" }, "completion": { "firm": "B", "side": "sell", "trader": "Doe" }, "trade_time": "2012-01-01T12:00:00Z" }] } ### Get Orders [GET /admin/orders] Get all orders. + Response 200 (application/json) + Attributes (object) + data (array[Order]) + Body { "data": [{ "order_id": "D4CA73A0-FE34-4B09-991F-E889813B1C15", "order_type": "limit", "side": "buy", "futures_id": "GC_SEP18", "trader_name": "John", "quantity": 50, "open_quantity": 40, "price": 30.12, "status": "open", "created_at": "2018-05-17T12:00:00Z", "updated_at": "2012-05-17T13:00:00Z" }] } # Group FIX API The [FIX](https://en.wikipedia.org/wiki/Financial_Information_eXchange), 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. | #### 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 | ### 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. |