1. Quick Start¶
1.1. Disclaimer¶
FXCM Group, LLC and each of its affiliates and subsidiaries are herein referred to as, “FXCM”.
Trading forex/CFDs on margin carries a high level of risk and may not be suitable for all investors as you could sustain losses in excess of deposits. Leverage can work against you. Due to the certain restrictions imposed by the local law and regulation, German resident retail client(s) could sustain a total loss of deposited funds but are not subject to subsequent payment obligations beyond the deposited funds. Be aware and fully understand all risks associated with the market and trading. Prior to trading any products, carefully consider your financial situation and experience level. Any opinions, news, research, analyses, prices, or other information is provided as general market commentary, and does not constitute investment advice. FXCM will not accept liability for any loss or damage, including without limitation to, any loss of profit, which may arise directly or indirectly from use of or reliance on such information.
1.2. Introduction¶
FXCM provides a RESTful API (henceforth the “API”) to interact with its trading platform. Among others, it allows the retrieval of historical data as well as of streaming data. In addition, it allows to place different types of orders and to read out account information. The overall goal is to allow the implementation automated, algortithmic trading programs.
In this documentation, you learn all about the fxcmpy Python wrapper
package (henceforth just fxcmpy or “package”).
1.3. Demo Account¶
To get started with the the API and the package, a demo account with FXCM is sufficient. You can open such an account under https://www.fxcm.com/uk/forex-trading-demo/.
1.4. Python Installation¶
fxcmpy works with Python 3.4 and later. If you need to install
Python itself and/or additional packages, we recommend the use
of the conda package and environment manager.
To this end, you can download the Miniconda installer from
https://conda.io/miniconda.html for your operating system and get it
installed.
You can then download and use the following yaml file to create a
Python environment:
http://fxcmpy.tpq.io/_static/fxcm.yml
Having downloaded this file, the environment is created on the command line as follows:
conda env create -f fxcm.yml -n fxcm
Activate it under Mac OS/Linux via:
conda activate fxcm
And under Windows via:
activate fxcm
You can then start, for instance, Jupyter to interactively explore the examples of this documentation.
1.5. Package Installation¶
The code of the package is hosted under https://github.com/fxcm/fxcmpy.
You can clone the Git repository and install the fxcmpy package
locally via
git clone https://github.com/fxcm/fxcmpy/
cd fxcmpy
python setup.py install
However, installation in general is easiest via pip install on the
command line.
pip install fxcmpy
Make sure to update/upgrade regularly via
pip install fxcmpy --upgrade
Working in an interactive context (e.g. IPython or Jupyter), you
can then check whether the package is installed via
In [1]:
import fxcmpy
In [2]:
fxcmpy.__version__
Out[2]:
'1.1.24'
1.6. API Token¶
To connect to the API, you need an API token that you can create or revoke from within your (demo) account in the Trading Station https://tradingstation.fxcm.com/.
Important: Please send an email with you user name to api@fxcm.com to get RESTful API access and to activate your token, respectively.
In an interactive context, you can use e.g. a variable called TOKEN
to reference your unique API token.
TOKEN = YOUR_FXCM_API_TOKEN
Connecting to the server, then boils down to the following line of code.
con = fxcmpy.fxcmpy(access_token=TOKEN, log_level='error')
However, it is recommended to store the API token in a configuration file which allows for re-usability and hides the token on the GUI level. The file should contain the following lines.
[FXCM]
log_level = error
log_file = PATH_TO_AND_NAME_OF_LOG_FILE
access_token = YOUR_FXCM_API_TOKEN
It is assumed onwards that this file is in the current working directory
and that its name is fxcm.cfg.
With such a configuration file in the current working directory, only the filename need to be passed as a parameter to connect to the API.
In [3]:
con = fxcmpy.fxcmpy(config_file='fxcm.cfg')
By default, the class connects to the demo server.
con = fxcmpy.fxcmpy(config_file='fxcm.cfg', server='demo')
To connect to the live server, the server parameter must be set to
real.
con = fxcmpy.fxcmpy(config_file='fxcm.cfg', server='real')
1.7. First Steps¶
Having established the connection to the API, data retrieval is straightforward.
For example, you can look up which instruments are available via the
con.get_instruments() method.
In [4]:
print(con.get_instruments())
['EUR/USD', 'USD/JPY', 'GBP/USD', 'USD/CHF', 'EUR/CHF', 'AUD/USD', 'USD/CAD', 'NZD/USD', 'EUR/GBP', 'EUR/JPY', 'GBP/JPY', 'CHF/JPY', 'GBP/CHF', 'EUR/AUD', 'EUR/CAD', 'AUD/CAD', 'AUD/JPY', 'CAD/JPY', 'NZD/JPY', 'GBP/CAD', 'GBP/NZD', 'GBP/AUD', 'AUD/NZD', 'USD/SEK', 'EUR/SEK', 'EUR/NOK', 'USD/NOK', 'USD/MXN', 'AUD/CHF', 'EUR/NZD', 'USD/ZAR', 'USD/HKD', 'ZAR/JPY', 'USD/TRY', 'EUR/TRY', 'NZD/CHF', 'CAD/CHF', 'NZD/CAD', 'TRY/JPY', 'USD/CNH', 'AUS200', 'ESP35', 'FRA40', 'GER30', 'HKG33', 'JPN225', 'NAS100', 'SPX500', 'UK100', 'US30', 'Copper', 'CHN50', 'EUSTX50', 'USDOLLAR', 'USOil', 'UKOil', 'SOYF', 'NGAS', 'Bund', 'XAU/USD', 'XAG/USD']
Simlarly, historical data is retrieved via the con.get_cancles()
method.
In [5]:
data = con.get_candles('EUR/USD', period='m1', number=250)
In [6]:
data.head()
Out[6]:
| bidopen | bidclose | bidhigh | bidlow | askopen | askclose | askhigh | asklow | tickqty | |
|---|---|---|---|---|---|---|---|---|---|
| date | |||||||||
| 2018-07-13 16:50:00 | 1.16700 | 1.16715 | 1.16718 | 1.16700 | 1.16724 | 1.16738 | 1.16741 | 1.16724 | 122 |
| 2018-07-13 16:51:00 | 1.16716 | 1.16741 | 1.16748 | 1.16716 | 1.16739 | 1.16765 | 1.16771 | 1.16739 | 309 |
| 2018-07-13 16:52:00 | 1.16741 | 1.16762 | 1.16765 | 1.16741 | 1.16765 | 1.16785 | 1.16789 | 1.16765 | 201 |
| 2018-07-13 16:53:00 | 1.16762 | 1.16752 | 1.16763 | 1.16752 | 1.16785 | 1.16776 | 1.16785 | 1.16776 | 162 |
| 2018-07-13 16:54:00 | 1.16751 | 1.16724 | 1.16752 | 1.16721 | 1.16775 | 1.16748 | 1.16775 | 1.16744 | 321 |
In [7]:
data.tail()
Out[7]:
| bidopen | bidclose | bidhigh | bidlow | askopen | askclose | askhigh | asklow | tickqty | |
|---|---|---|---|---|---|---|---|---|---|
| date | |||||||||
| 2018-07-13 20:55:00 | 1.16848 | 1.16850 | 1.16851 | 1.16841 | 1.16874 | 1.16877 | 1.16878 | 1.16868 | 61 |
| 2018-07-13 20:56:00 | 1.16850 | 1.16846 | 1.16854 | 1.16844 | 1.16877 | 1.16874 | 1.16879 | 1.16872 | 67 |
| 2018-07-13 20:57:00 | 1.16846 | 1.16842 | 1.16846 | 1.16841 | 1.16874 | 1.16870 | 1.16874 | 1.16868 | 13 |
| 2018-07-13 20:58:00 | 1.16842 | 1.16847 | 1.16855 | 1.16842 | 1.16870 | 1.16878 | 1.16883 | 1.16870 | 37 |
| 2018-07-13 20:59:00 | 1.16847 | 1.16831 | 1.16847 | 1.16831 | 1.16878 | 1.16879 | 1.16879 | 1.16878 | 5 |
Such data can be visualized with standard functionality of Python and pandas, for instance.
In [8]:
from pylab import plt
plt.style.use('seaborn')
%matplotlib inline
In [9]:
data['askclose'].plot(figsize=(10, 6));
As last step, it is recommended to close the connection to free resources.
In [10]:
con.close()
1.8. Resources¶
If you have questions regarding demo or full accounts, reach out to:
- info@fxcm.co.uk
- +44 (0) 207 398 4050
If you have questions regarding the RESTful API, reach out to:
The detailed documentation of the API is found under:
The book Python for Finance — Mastering Data-Driven Finance (O’Reilly) provides detailed information about the use of Python in Finance:
In-depth courses and programs about Python for Algorithmic Trading:
1.9. License¶
Here, you can download the license text.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- FXCM’s name may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY FXCM “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL FXCM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.10. Risk Warning¶
As a condition to your use, you understand and agree that your download and/or use of the software will expose you to risks associated with the download and/or use of software, including without limitation:
- risk of delays or failures in transmission, connection, or communication;
- risks of error in the data, code, software updates or patches;
- the risk that the software maybe discontinued, terminated or become obsolete at any time without notice;
- modification or updates to the software may cause disruption or errors;
- the risk that you are solely responsible to ensure you obtain and are using the most up to date version of the software, which may be modified or updated without notice; and
- software or data may not be compatible with your equipment or for your use.
You hereby agree to accept such risks including but not limited to failure of or damage to hardware, software, communication lines or systems, and/or other computer equipment. FXCM expressly disclaims any liability with respect to the foregoing.
