FXCM RESTful API User Guide

Transcription

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comFXCM Socket REST API User GuideP a g e 1 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comRevision HistoryVersionLast UpdatedComments2.1.3May 1, 2019Added explanation of request parameter types and updatedsocket.io connection description.2.1.2Feb 9, 2019Fixed reference error on page 6.Price updates are now sent as milliseconds.Added more information about Orders table, including tradeId.Removed unused fields from trading tables.Added more information on close trade, change order,delete order, change trade stop limit andchange order stop limit functions.Added candle limit information to historical data.2.1.1Feb 6, 2019Remove offer, leverage profile and properties from list ofpossible tables to be subscribed to2.1Feb 2, 2019Added enumeration descriptions in trading tables and arraydescriptions for price updates2.0Jan 16, 2018Clean up after OAuth removal and re-add get instruments,update subscriptions1.9Sept 13, 2017Add table description on appendix1.8July 29, 2017Begin modifying requests to POST versions and standardizingstyle1.7July 27, 2017Remove sample code, replaced by sample program (will beupload to github for public access), to make documents niceand neat.1.6July 27, 2017Change accountId to account id1.5July 25, 2017Remove /trading/changePassword1.4June 28, 2017Replaced GET functions with POST, PATCH /DELETE1.3June 27, 2017Removed command line and redundant functions1.2June 26, 2017Add Historical data1.2June 22, 20171.0May 15, 2017Added response, requests, diagrams, sample codeP a g e 2 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comContents1Overview . 52Getting Started . 532.1Prerequisites . 52.2Logon and Authentication . 52.3Message Flow . 5Authentication Messages . 63.1456Open Socket and get socket id by passing access token . 6Market Data . 64.1Request a list of all available symbols . 64.2Subscribe to Market Data stream . 74.3Unsubscribe from Market Data stream . 84.4Price updates . 9Trading Tables . 95.1Subscribe to trading tables . 95.2Unsubscribe from trading tables . 105.3Request a snapshot of trading tables . 115.4Trading table responses . 125.4.1Offers table. 125.4.2Open Positions table . 145.4.3Closed Positions table . 165.4.4Orders table. 175.4.5Summary table . 195.4.6Accounts table . 20Trading Orders . 216.1/trading/open trade . 216.2/trading/close trade . 236.3/trading/change order . 246.4/trading/delete order . 256.5/trading/create entry order . 266.6/trading/simple oco . 27P a g e 3 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.com76.7/trading/add to oco . 286.8/trading/remove from oco . 296.9/trading/edit oco . 306.10/trading/change trade stop limit . 306.11/trading/change order stop limit . 316.12/trading/close all for symbol . 32Historical Data . 33P a g e 4 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.com1 OverviewFXCM offers a web-based REST API which can be used to establish secure connectivity with FXCM’s tradingsystems for the purpose of receiving market data and trading.This document provides an overview of this API, optional tools and sample implementations.2 Getting Started2.1 PrerequisitesTo use the REST API, you will need: Access Token generated with Trading Station Web https://tradingstation.fxcm.com/Socket.IO client library: https://socket.io/docs/client-api/o using JavaScript: https://www.npmjs.com/package/socket.ioo using Python: https://pypi.python.org/pypi/socketIO-client2.2 Logon and AuthenticationREST API uses a persistent Access Token. You can generate this token by logging into Trading Station Webat https://tradingstaton.fxcm.com/.2.3 Message FlowClients should establish a persistent WebSocket connection using socket.io library. All non-solicitedupdates will be sent over this connection. Client requests are to be sent via normal HTTP messages. EveryHTTP message must contain following TP versionVersion of HTTP usedHTTP/1.1YUser-AgentIdentification of the client softwarerequestYAcceptAcceptable response MIME typeapplication/jsonYContent-TypeMedia type of the requestapplication/x-www-form-urlencodedYP a g e 5 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comAuthorizationAuthorization string containing“Bearer “, ID of socket.ioconnection and persistent token.'Bearer ' socket id api tokenYAll request parameters sent to the server must be formatted as key value pairs.Possible types:a) String, URL encoded (“/” being represented as “%2F”, for example: key EUR%2FUSDb) Number, with decimals separated with a “.” character, for example: key 1.23c) Boolean, lowercase “true” or “false”, for example: key trueMultiple key value pairs are separated by “&” character, for example:key EUR%2FUSD&key2 1.23&key3 falseRequest parameters for GET method are sent as Query part of the URL.Request parameters for POST method are sent as request body.3 Authentication Messages3.1 Open SocketIO connection and get socket idSocket connection can be established using socket.io-client library. The connection needs to haveaccess token obtained from Trading Station Web as one of the parameters in query part of theconnection URL. This connection must stay open for requests to work.4 Market Data4.1 Request a list of all available symbolsWe need to know which symbols are available for MethodHTTP methodGETYURIResource/trading/get e RequestGET /trading/get instruments/? HTTP/1.1User-Agent: requestAccept: application/jsonContent-Type: application/x-www-form-urlencodedAuthorization: Bearer ac1b4c41eaHost: api-demo.fxcm.comConnection: closeRESPONSEParameterDescriptionValuesP a g e 6 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comexecutedExecution successfulBooleandataData of the responseObjectinstrumentList of instrumentsArraysymbolRepresentation of the instrumentSymbolvisivleIs symbol visible in Offers tableBooleanorderOrdering numberNumberSample ResponseHTTP/1.1 200 OKAccess-Control-Allow-Methods: GET,PUT,POST,DELETEAccess-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, AcceptX-Content-Type-Options: nosniffContent-Type: application/json; charset utf-8Content-Length: 2869ETag: W/"b35-wJL EwQsbuYSjtvqcCGh1g"Date: Tue, 16 Jan 2018 17:27:44 GMTConnection: closeLast-Modified: Tue, 16 Jan 2018 17:27:44 UTCVary: e,"order":1}, 4.2 Subscribe to Market Data streamAfter subscribing, market price updates will be pushed to the client via the HTTP ionValuesReq’dpairsSymbols to be subscribed toString, representation of the requestedsymbolYSample RequestPOST /subscribe HTTP/1.1User-Agent: requestAccept: application/jsonContent-Type: application/x-www-form-urlencodedAuthorization: Bearer ac1b4c41eaHost: api.fxcm.comConnection: closeTransfer-Encoding: chunked55pairs edExecution successfulBooleanerrorType of socketString. Internal variable of socket.iopairsSymbol informationObject containing information about the symbolUpdatedTimestamp of last updateNumber, Epoch timestamp in millisecondsP a g e 7 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comRatesCurrent ratesArray of Numbers, [Bid, Ask, Session High, Session Low]SymbolSymbolString representing the symbolSample ResponseHTTP/1.1 200 OKVary: : GET,PUT,POST,DELETEAccess-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, AcceptX-Content-Type-Options: nosniffContent-Type: application/json; charset utf-8Content-Length: 157ETag: W/"9d-YFo 3OmAbWV4Q8hgjKPcMA"Date: Fri, 28 Jul 2017 22:48:36 GMTConnection: closeSet-Cookie: BIGipServerapi.fxcm.com 3698998282.42783.0000; path /; Httponly; SecureLast-Modified: Fri, 28 Jul 2017 22:48:36 R/USD\"}"}4.3 Unsubscribe from Market Data TTP ptionValuesReq’dpairsSymbols to be unsubscribed fromString representing the symbolYSample RequestPOST /unsubscribe HTTP/1.1User-Agent: requestAccept: application/jsonContent-Type: application/x-www-form-urlencodedAuthorization: Bearer ac1b4c41eaHost: api.fxcm.comConnection: closeTransfer-Encoding: chunked55pairs ket IDupgradesType of socket40 digit hex value to be used as socket id in all futurerequestsString. Internal variable of socket.iopingIntervalInterval between pingsInteger value in milliseconds. Internal variable of socket.iopingTimeoutTimeout of pingsInteger value in milliseconds. Internal variable of socket.ioP a g e 8 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comSample ResponseHTTP/1.1 200 OKVary: : GET,PUT,POST,DELETEAccess-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, AcceptX-Content-Type-Options: nosniffContent-Type: application/json; charset utf-8Content-Length: 59ETag: W/"3b-3vU5f74yKnWdV/dyTgPejA"Date: Fri, 28 Jul 2017 22:48:40 GMTConnection: closeSet-Cookie: BIGipServerapi.fxcm.com 3698998282.42783.0000; path /; Httponly; SecureLast-Modified: Fri, 28 Jul 2017 22:48:40 ":"EUR/USD"}4.4 Price me of the updateInteger epoch time in millisecondsRatesPrice information[Bid, Ask, Session High, Session Low]SymbolInstrument of the updateString representation of the instrumentSample :\"EUR/USD\"}"]5 Trading Tables5.1 Subscribe to trading tablesSubscribes to the updates of the data models. Update will be pushed to client via the socket. Type ofupdate can be determined by “action” TTP DescriptionValuesReq’dmodelsName of the tablemodel to be subscribedtoString, one or more of: 'OpenPosition','ClosedPosition', 'Order', 'Account','Summary'YSample RequestPOST /trading/subscribe HTTP/1.1User-Agent: requestAccept: application/jsonContent-Type: application/x-www-form-urlencodedAuthorization: Bearer ac1b4c41eaHost: api.fxcm.comConnection: closeTransfer-Encoding: chunked52models Order0P a g e 9 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com utedExecution successfulBooleanSample ResponseHTTP/1.1 200 OKVary: : GET,PUT,POST,DELETEAccess-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, AcceptX-Content-Type-Options: nosniffContent-Type: application/json; charset utf-8Content-Length: 30ETag: W/"1e-/mvovEuhtN1hYjWJCVVEGQ"Date: Fri, 28 Jul 2017 23:19:59 GMTConnection: closeSet-Cookie: BIGipServerapi.fxcm.com 3698998282.42783.0000; path /; Httponly; SecureLast-Modified: Fri, 28 Jul 2017 23:19:59 UTC{"response":{"executed":true}}5.2 Unsubscribe from trading tablesUnsubscribes from the updates of the data models that are being pushed via the HTTP erDescriptionValuesReq’dmodelsName of the tablemodel to beunsubscribed toString, one or more of: 'Offer','OpenPosition', 'ClosedPosition', 'Order','Account', 'Summary', 'LeverageProfile','Properties'YSample RequestPOST /trading/unsubscribe HTTP/1.1User-Agent: requestAccept: application/jsonContent-Type: application/x-www-form-urlencodedAuthorization: Bearer ac1b4c41eaHost: api.fxcm.comConnection: closeTransfer-Encoding: chunked52models ecution successfulBooleanP a g e 10 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comSample ResponseHTTP/1.1 200 OKVary: : GET,PUT,POST,DELETEAccess-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, AcceptX-Content-Type-Options: nosniffContent-Type: application/json; charset utf-8Content-Length: 30ETag: W/"1e-/mvovEuhtN1hYjWJCVVEGQ"Date: Fri, 28 Jul 2017 23:20:05 GMTConnection: closeSet-Cookie: BIGipServerapi.fxcm.com 3698998282.42783.0000; path /; Httponly; SecureLast-Modified: Fri, 28 Jul 2017 23:20:05 UTC{"response":{"executed":true}}5.3 Request a snapshot of trading tablesIn case continuous updates of the trading tables is not needed, it is possible to request a one-timesnapshot.Gets current content snapshot of the specified data models.Model choices: 'Offer', 'OpenPosition', 'ClosedPosition', 'Order', 'Summary', 'LeverageProfile', uesReq’dMethodHTTP methodGETYURIResource/trading/get modelYParameterDescriptionValuesReq’dmodelsName of the tablemodel to beunsubscribed toString, one or more of: 'Offer','OpenPosition', 'ClosedPosition', 'Order','Account', 'Summary', 'LeverageProfile','Properties'YSample RequestGET/trading/get model/?models Offer&models OpenPosition&models ClosedPosition&models Order&models Summary&models Account&models LeverageProfile&models Properties HTTP/1.1Host: api.fxcm.comConnection: cution successfulBoolean models Requested tablesTable models. See chapter 5.4P a g e 11 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comSample ResponseHTTP/1.1 200 OKAccess-Control-Allow-Methods: GET,PUT,POST,DELETEAccess-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, AcceptX-Content-Type-Options: nosniffContent-Type: application/json; charset utf-8Content-Length: 12264ETag: W/"2fe8-79HiV0VI0lZqcM4i27YT1w"Date: Mon, 14 Aug 2017 15:01:06 GMTConnection: closeSet-Cookie: BIGipServerapi.fxcm.com 3698998282.42783.0000; path /; Httponly; SecureLast-Modified: Mon, 14 Aug 2017 15:01:06 UTCVary: Accept-Encoding{"response":{"executed":true},( )5.4 Trading table responses5.4.1 Offers tableThis section describes the Offers table that contains information about trading instruments, current prices,and high/low trading day prices.RESPONSEParameterDescriptionValuestID number of the table0ratePrecisionThe price precision of the instrument. It defines number of digits after thedecimal point in the instrument price quote.The unique identification number of the instrument.NumberNumberdefaultSortOrderThe interest amount added to the account balance for holding a one lotlong (buy) position overnight. In the case of FX instruments, lot size isdetermined by the system base unit size. In the case of CFD instruments,lot size equals to one contract. The interest amount is expressed in theaccount currency and can be positive or negative.The interest amount added to the account balance for holding a one lotshort (sell) position overnight. In the case of FX instruments, lot size isdetermined by the system base unit size. In the case of CFD instruments,lot size equals to one contract. The interest amount is expressed in theaccount currency and can be positive or negative.The price precision of the instrument. It defines number of digits after thedecimal point in the instrument price quote.The size of one pip. It used to define the smallest move the instrument canmake. In the case of FX instruments, it is expressed in the instrumentcounter currency. In the case of CFD instruments, it is expressed in theinstrument native currency.Sorting index of the instrumentcurrencyThe symbol of the pNumberNumberNumberNumberNumberP a g e 12 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.cominstrumentTypeNumbertimeThe type of the instrument. The possible values are:1 – Forex2 – Indices3 – Commodity4 – Treasury5 – Bullion6 – Shares7 – FXIndexThe simulated delivery date. The date and time when the position openedin the instrument could be automatically closed. The value of this field isprovided in the yyyyMMdd format. It is applicable only when instrumenttrades on account with the day netting trading. Otherwise, the value ofthis field is blank.The date and time of the last update of the instrument. ISO 8601 format.sellThe current market price the instrument can be sold at.NumberbuyThe current market price the instrument can be bought at.NumbersellTradableBooleanhighThe usage of the sell price. It defines whether the sell price of theinstrument is available for trading or not.The usage of the buy price. It defines whether the buy price of theinstrument is available for trading or not.The highest buy price of the instrument for the current trading day.lowThe lowest sell price of the instrument for the current trading day.NumbervolumeNumberpipFractionThe tick volume of the current minute. The value of this field representsthe number of ticks happened during the current minute.Minimum price change for the instrument.spreadDifference between Buy and Sell price in pips.NumbermmrMaintenance margin level.NumberemrEntry margin level.NumberlmrLimitation margin level.NumberpipCostThe cost of one pip per lot. It is expressed in the account currency andused to calculate the P/L value in the account currency.Type of update. Only applicable to updates through the socket.Possible values are:I – InsertU – UpdateD – BooleanNumberNumberStringSample ,"pipCost":0.0001}]5.4.1.1 Changing symbols subscribed to in Offers tableOffers table will show only symbols that we have subscribed to using update subscriptions. For a list ofsymbols available for subscription please see 4.1REQUESTP a g e 13 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com TP methodPOSTYURIResource/trading/update bolRequested symbolStringYvisibleShould the symbol be visible in Offers tableBooleanSample RequestPOST /trading/update subscriptions HTTP/1.1User-Agent: requestAccept: application/jsonContent-Type: application/x-www-form-urlencodedAuthorization: Bearer ac1b4c41eaHost: api-demo.fxcm.comConnection: closeTransfer-Encoding: chunked1dsymbol EUR%2FUSD&visible cution successfulBooleanSample ResponseHTTP/1.1 200 OKVary: : GET,PUT,POST,DELETEAccess-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, AcceptX-Content-Type-Options: nosniffContent-Type: application/json; charset utf-8Content-Length: 30ETag: W/"1e-/mvovEuhtN1hYjWJCVVEGQ"Date: Tue, 16 Jan 2018 17:45:51 GMTConnection: closeLast-Modified: Tue, 16 Jan 2018 17:45:50 UTC{"response":{"executed":true}}5.4.2 Open Positions tableThis section describes the Open Positions table that contains open positions data such as floatingprofit/loss, charged commission, cumulative interest, and so on.RESPONSEParameterDescriptionValuestID number of the table1ratePrecisionThe price precision of the instrument. It defines number of digitsafter the decimal point in the instrument price quote.The unique identification number of the open position. The numberis unique within the same database that stores the account theposition is opened on.The unique name of the account the position is opened on. Thename is unique within the database where the account is stored.NumbertradeIdaccountNameStringStringP a g e 14 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.comaccountIdThe unique identification number of the account the position isopened on. The number is unique within the database where theaccount is stored.The cumulative amount of funds that is added the account balancefor holding the position overnight.The amount of funds subtracted from the account balance to pay forthe broker's service in accordance with the terms and conditions ofthe account trading agreement.The price the position is opened at.StringvalueDateThe simulated delivery date. The date when the position could beautomatically closed. The date is provided in the yyyyMMdd format.It is applicable only for positions opened on accounts with the daynetting trading mode. Otherwise, the value of this field is blank.StringgrossPLThe current profit/loss of the position. It is expressed in the accountcurrency.The price at which the position can be closed at the moment.NumberThe current profit/loss per one lot of the position. It is expressed inthe account NumberNumberNumberNumberBooleancurrencyThe symbol of the instrument.StringisBuyBooleanamountKThe trade operation the position is opened by. The possible valuesare:True – BuyFalse – SellThe amount of the position in thousand units.currencyPoint?NumbertimeThe date and time when the position was opened.StringusedMarginThe amount of funds currently committed to maintain the position.NumberstopThe price of the associated stop order (loss limit level).NumberstopMoveNumberlimitThe number of pips the market should move before the stop ordermoves the same number of pips after it.If the trailing order is dynamic (automatically updates every 0.1 of apip), then the value of this field is 1.If the order is not trailing, the value of this field is 0.The price of the associated limit order (profit limit level).isTotalIndicates the row is a summary of for whole table.BooleanactionType of update. Only applicable to updates through the socket.Possible values are:I – InsertU – UpdateD – DeleteStringNumberNumberSample Response"open imit":0}]P a g e 15 34

FXCM Group20 Gresham Street, 4th Floor, London EC2V 7JE, UKEmail: api@fxcm.com www.fxcm.com5.4.3 Closed Positions tableThis section describes the Closed Positions table that contains information about the positions closedduring the current trading day such as realized profit/loss, charged commission, cumulative interest, andso on.RESPONSEParameterDescriptionValuestID number of the table2ratePrecisionThe price precision of the instrument. It defines number of digits after thedecimal point in the instrument price quote.The unique identification number of the open position. The number isunique within the same database that stores the account the position isopened on.The unique name of the account the position is opened on. The name isunique within the database where the account is stored.The cumulative amount of funds that is added the account balance forholding the position overnight.The amount of funds subtracted from the account balance to pay for thebroker's service in accordance with the terms and conditions of theaccount trading agreement.The price the position is opened at.NumberThe simulated delivery date. The date when the position could beautomatically closed. The date is provided in the yyyyMMdd format. It isapplicable only for positions opened on accounts with the day nettingtrading mode. Otherwise, the value of this field is blank.The current profit/loss of the position. It is expressed in the accountcurrency.The price at which the position can be closed at the moment.StringThe current profit/loss per one lot of the position. It is expressed in theaccount currency.The symbol of the instrument.NumberThe trade operation the position is opened by. The possible values are:True – BuyFalse – SellThe amount of the position in thousand ingNumberNumberopenTimeThe date and time when the position was opened.StringcloseTimeThe date and time when the position was closed.StringisTotalIndicates the row is a summary of for whole table.actionType of update. Only applicable to updates through the socket. Possiblevalues are:I – InsertU – UpdateD – Del

FXCM Group 20 Gresham Street, 4th Floor, London EC2V 7JE, UK Email: api@fxcm.com www.fxcm.com FXCM Socket REST API User Guide . P a g e 2 34 . Email: api@fxcm.com www.fxcm.com Rates Current rates Array of Numbers, [Bid, Ask, Session High, Session Low] Symbol Symbol String representing the symbol Sample Response