tpqoa.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<img src=\"http://hilpisch.com/tpq_logo.png\" alt=\"The Python Quants\" width=\"35%\" align=\"right\" border=\"0\"><br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# tpqoa"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Algorithmic Trading with Oanda"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`tpqoa` is a wrapper class for the Oanda REST API v20 (http://developer.oanda.com/). It makes use of the Python package `v20` from Oanda (https://github.com/oanda/v20-python). The package is authored and maintained by The Python Quants GmbH. &copy; Dr. Yves J. Hilpisch. MIT License."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Disclaimer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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, code examples or other information is provided as general market commentary, and does not constitute investment advice. The Python Quants GmbH 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.\n",
    "\n",
    "The `tpqoa` package is intended as a technological illustration only. It comes with no warranties or representations, to the extent permitted by applicable law."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Installing from source via `Git` and `Github`:\n",
    "\n",
    "    git clone https://github.com/yhilpisch/tpqoa\n",
    "    cd tpqoa\n",
    "    python setup.py install\n",
    "    \n",
    "Using `pip` in combination with `Github`:\n",
    "\n",
    "    pip install git+git://github.com/yhilpisch/tpqoa\n",
    "\n",
    "Using `pip` directly:\n",
    "\n",
    "    pip install --index-url https://test.pypi.org/simple/ tpqoa"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Connection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to connect to the API, you need to have at least a practice account with Oanda (https://oanda.com/). Once logged in to you account, you can create an API token and can copy your account number. These are expected to be stored in a configuration file, with name `oanda.cfg`, for instance, as follows:\n",
    "\n",
    "    [oanda]\n",
    "    account_id = XYZ-ABC-...\n",
    "    access_token = ZYXCAB...\n",
    "    account_type = practice (default) or live"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can then set up an API connection by instantiating a connection object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import tpqoa"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "oanda = tpqoa.tpqoa('oanda.cfg')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Available Instruments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `get_instruments()` method retrieves all available instruments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "ins = oanda.get_instruments()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('Silver/CHF', 'XAG_CHF'),\n",
       " ('Silver/EUR', 'XAG_EUR'),\n",
       " ('UK 10Y Gilt', 'UK10YB_GBP'),\n",
       " ('GBP/ZAR', 'GBP_ZAR'),\n",
       " ('Soybeans', 'SOYBN_USD'),\n",
       " ('NZD/SGD', 'NZD_SGD'),\n",
       " ('USD/HKD', 'USD_HKD'),\n",
       " ('GBP/PLN', 'GBP_PLN'),\n",
       " ('Platinum', 'XPT_USD'),\n",
       " ('USD/JPY', 'USD_JPY')]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ins[:10]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Historical Data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `get_history()` method retrieves historical data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method get_history in module tpqoa.tpqoa:\n",
      "\n",
      "get_history(instrument, start, end, granularity, price) method of tpqoa.tpqoa.tpqoa instance\n",
      "    Retrieves historical data for instrument.\n",
      "    \n",
      "    Parameters\n",
      "    ==========\n",
      "    instrument: string\n",
      "        valid instrument name\n",
      "    start, end: datetime, str\n",
      "        Python datetime or string objects for start and end\n",
      "    granularity: string\n",
      "        a string like 'S5', 'M1' or 'D'\n",
      "    price: string\n",
      "        one of 'A' (ask) or 'B' (bid)\n",
      "    \n",
      "    Returns\n",
      "    =======\n",
      "    data: pd.DataFrame\n",
      "        pandas DataFrame object with data\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(oanda.get_history)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = oanda.get_history(instrument='EUR_USD',\n",
    "                  start='2019-07-01',\n",
    "                  end='2020-01-31',\n",
    "                  granularity='D',\n",
    "                  price='A')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'pandas.core.frame.DataFrame'>\n",
      "DatetimeIndex: 154 entries, 2019-06-30 21:00:00+00:00 to 2020-01-30 22:00:00+00:00\n",
      "Data columns (total 6 columns):\n",
      "volume      154 non-null int64\n",
      "complete    154 non-null bool\n",
      "o           154 non-null float64\n",
      "h           154 non-null float64\n",
      "l           154 non-null float64\n",
      "c           154 non-null float64\n",
      "dtypes: bool(1), float64(4), int64(1)\n",
      "memory usage: 7.4 KB\n"
     ]
    }
   ],
   "source": [
    "data.info()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "                           volume  complete        o        h        l  \\\n",
      "time                                                                     \n",
      "2019-06-30 21:00:00+00:00   18780      True  1.13644  1.13721  1.12819   \n",
      "2019-07-01 21:00:00+00:00   15567      True  1.12867  1.13233  1.12759   \n",
      "2019-07-02 21:00:00+00:00   14593      True  1.12871  1.13139  1.12695   \n",
      "2019-07-03 21:00:00+00:00    5731      True  1.12795  1.12960  1.12740   \n",
      "2019-07-04 21:00:00+00:00   15161      True  1.12871  1.12885  1.12081   \n",
      "\n",
      "                                 c  \n",
      "time                                \n",
      "2019-06-30 21:00:00+00:00  1.12867  \n",
      "2019-07-01 21:00:00+00:00  1.12871  \n",
      "2019-07-02 21:00:00+00:00  1.12797  \n",
      "2019-07-03 21:00:00+00:00  1.12859  \n",
      "2019-07-04 21:00:00+00:00  1.12305  \n"
     ]
    }
   ],
   "source": [
    "print(data.head())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Streaming Data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The method `stream_data()` allows the streaming of real-time data (bid & ask)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2020-02-19T16:47:33.801700552Z 1.07978 1.0799\n",
      "2020-02-19T16:47:36.115072873Z 1.07979 1.07989\n",
      "2020-02-19T16:47:36.941344979Z 1.07979 1.07991\n"
     ]
    }
   ],
   "source": [
    "oanda.stream_data('EUR_USD', stop=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By redefining the `on_success()` method, you can control what happes with the streaming data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "class myOanda(tpqoa.tpqoa):\n",
    "    def on_success(self, time, bid, ask):\n",
    "        ''' Method called when new data is retrieved. '''\n",
    "        print('BID: {:.5f} | ASK: {:.5f}'.format(bid, ask))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_oanda = myOanda('oanda.cfg')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "BID: 1.07978 | ASK: 1.07990\n",
      "BID: 1.07979 | ASK: 1.07991\n",
      "BID: 1.07979 | ASK: 1.07991\n",
      "BID: 1.07980 | ASK: 1.07992\n",
      "BID: 1.07980 | ASK: 1.07992\n"
     ]
    }
   ],
   "source": [
    "my_oanda.stream_data('EUR_USD', stop=5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Methods"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other major methods are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method create_order in module tpqoa.tpqoa:\n",
      "\n",
      "create_order(instrument, units, sl_distance=None, tsl_distance=None, tp_price=None, comment=None, ret=False) method of tpqoa.tpqoa.tpqoa instance\n",
      "    Places order with Oanda.\n",
      "    \n",
      "    Parameters\n",
      "    ==========\n",
      "    instrument: string\n",
      "        valid instrument name\n",
      "    units: int\n",
      "        number of units of instrument to be bought\n",
      "        (positive int, eg 'units=50')\n",
      "        or to be sold (negative int, eg 'units=-100')\n",
      "    sl_distance: float\n",
      "        stop loss distance price, mandatory eg in Germany\n",
      "    tsl_distance: float\n",
      "        trailing stop loss distance\n",
      "    tp_price: float\n",
      "        take profit price to be used for the trade\n",
      "    comment: str\n",
      "        string\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(oanda.create_order)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "\n",
      " {'id': '4481', 'time': '2020-02-19T16:47:42.095899410Z', 'userID': 5516121, 'accountID': '101-004-5516121-001', 'batchID': '4480', 'requestID': '24650336313951685', 'type': 'ORDER_FILL', 'orderID': '4480', 'instrument': 'EUR_USD', 'units': '100.0', 'gainQuoteHomeConversionFactor': '0.925994518112', 'lossQuoteHomeConversionFactor': '0.926097425449', 'price': 1.07992, 'fullVWAP': 1.07992, 'fullPrice': {'type': 'PRICE', 'bids': [{'price': 1.0798, 'liquidity': '10000000'}], 'asks': [{'price': 1.07992, 'liquidity': '10000000'}], 'closeoutBid': 1.0798, 'closeoutAsk': 1.07992}, 'reason': 'MARKET_ORDER', 'pl': '0.0', 'financing': '0.0', 'commission': '0.0', 'guaranteedExecutionFee': '0.0', 'accountBalance': '96758.8741', 'tradeOpened': {'tradeID': '4481', 'units': '100.0', 'price': 1.07992, 'guaranteedExecutionFee': '0.0', 'halfSpreadCost': '0.0056', 'initialMarginRequired': '5.0'}, 'halfSpreadCost': '0.0056'} \n",
      "\n"
     ]
    }
   ],
   "source": [
    "# going long 100 units\n",
    "# sl_distance of 20 pips\n",
    "oanda.create_order('EUR_USD', units=100, sl_distance=0.002)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "\n",
      " {'id': '4484', 'time': '2020-02-19T16:47:42.243308180Z', 'userID': 5516121, 'accountID': '101-004-5516121-001', 'batchID': '4483', 'requestID': '24650336313952080', 'type': 'ORDER_FILL', 'orderID': '4483', 'instrument': 'EUR_USD', 'units': '-100.0', 'gainQuoteHomeConversionFactor': '0.925994518112', 'lossQuoteHomeConversionFactor': '0.926097425449', 'price': 1.0798, 'fullVWAP': 1.0798, 'fullPrice': {'type': 'PRICE', 'bids': [{'price': 1.0798, 'liquidity': '10000000'}], 'asks': [{'price': 1.07992, 'liquidity': '9999900'}], 'closeoutBid': 1.0798, 'closeoutAsk': 1.07992}, 'reason': 'MARKET_ORDER', 'pl': '-0.0106', 'financing': '0.0', 'commission': '0.0', 'guaranteedExecutionFee': '0.0', 'accountBalance': '96758.8635', 'tradesClosed': [{'tradeID': '4475', 'units': '-20.0', 'price': 1.0798, 'realizedPL': '-0.0017', 'financing': '0.0', 'guaranteedExecutionFee': '0.0', 'halfSpreadCost': '0.0011'}], 'tradeReduced': {'tradeID': '4481', 'units': '-80.0', 'price': 1.0798, 'realizedPL': '-0.0089', 'financing': '0.0', 'guaranteedExecutionFee': '0.0', 'halfSpreadCost': '0.0044'}, 'halfSpreadCost': '0.0055'} \n",
      "\n"
     ]
    }
   ],
   "source": [
    "# closing out the position\n",
    "oanda.create_order('EUR_USD', units=-100)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method get_account_summary in module tpqoa.tpqoa:\n",
      "\n",
      "get_account_summary(detailed=False) method of tpqoa.tpqoa.tpqoa instance\n",
      "    Returns summary data for Oanda account.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(oanda.get_account_summary)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'id': '101-004-5516121-001',\n",
       " 'alias': 'Primary',\n",
       " 'currency': 'EUR',\n",
       " 'balance': '96758.8635',\n",
       " 'createdByUserID': 5516121,\n",
       " 'createdTime': '2017-03-08T16:28:21.276100637Z',\n",
       " 'guaranteedStopLossOrderMode': 'DISABLED',\n",
       " 'pl': '-121958.3725',\n",
       " 'resettablePL': '-121958.3725',\n",
       " 'resettablePLTime': '2017-03-08T16:28:21.276100637Z',\n",
       " 'financing': '-704.944',\n",
       " 'commission': '0.0',\n",
       " 'guaranteedExecutionFees': '0.0',\n",
       " 'marginRate': '0.05',\n",
       " 'openTradeCount': 1,\n",
       " 'openPositionCount': 1,\n",
       " 'pendingOrderCount': 1,\n",
       " 'hedgingEnabled': False,\n",
       " 'unrealizedPL': '-0.0022',\n",
       " 'NAV': '96758.8613',\n",
       " 'marginUsed': '1.0',\n",
       " 'marginAvailable': '96757.8613',\n",
       " 'positionValue': '20.0',\n",
       " 'marginCloseoutUnrealizedPL': '-0.0011',\n",
       " 'marginCloseoutNAV': '96758.8624',\n",
       " 'marginCloseoutMarginUsed': '1.0',\n",
       " 'marginCloseoutPercent': '1e-05',\n",
       " 'marginCloseoutPositionValue': '20.0',\n",
       " 'withdrawalLimit': '96757.8613',\n",
       " 'marginCallMarginUsed': '1.0',\n",
       " 'marginCallPercent': '1e-05',\n",
       " 'lastTransactionID': '4485'}"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oanda.get_account_summary()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method get_transactions in module tpqoa.tpqoa:\n",
      "\n",
      "get_transactions(tid=0) method of tpqoa.tpqoa.tpqoa instance\n",
      "    Retrieves and returns transactions data.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(oanda.get_transactions)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method print_transactions in module tpqoa.tpqoa:\n",
      "\n",
      "print_transactions(tid=0) method of tpqoa.tpqoa.tpqoa instance\n",
      "    Prints basic transactions data.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(oanda.print_transactions)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " 4451 | 2020-02-19T16:28:41.702443781Z |   EUR_USD |         10.0 |      0.0\n",
      " 4453 | 2020-02-19T16:28:41.833970928Z |   EUR_USD |        -10.0 |   0.0034\n",
      " 4456 | 2020-02-19T16:28:42.384410161Z |   EUR_USD |         10.0 |      0.0\n",
      " 4459 | 2020-02-19T16:28:42.519605501Z |   EUR_USD |        -10.0 |   0.0031\n",
      " 4461 | 2020-02-19T16:28:43.052289649Z |   EUR_USD |         10.0 |      0.0\n",
      " 4464 | 2020-02-19T16:28:46.212352103Z |   EUR_USD |         10.0 |      0.0\n",
      " 4468 | 2020-02-19T16:28:49.349725889Z |   EUR_USD |        -20.0 |   0.0074\n",
      " 4471 | 2020-02-19T16:31:46.964516516Z |   EUR_USD |        -10.0 |  -0.0046\n",
      " 4472 | 2020-02-19T16:32:01.924364975Z |   EUR_USD |        -10.0 |  -0.0056\n",
      " 4475 | 2020-02-19T16:46:56.227615256Z |   EUR_USD |        100.0 |      0.0\n",
      " 4478 | 2020-02-19T16:46:56.372352822Z |   EUR_USD |       -100.0 |  -0.0089\n",
      " 4481 | 2020-02-19T16:47:42.095899410Z |   EUR_USD |        100.0 |      0.0\n",
      " 4484 | 2020-02-19T16:47:42.243308180Z |   EUR_USD |       -100.0 |  -0.0106\n"
     ]
    }
   ],
   "source": [
    "oanda.print_transactions(tid=4450)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"http://hilpisch.com/tpq_logo.png\" alt=\"The Python Quants\" width=\"35%\" align=\"right\" border=\"0\"><br>\n",
    "\n",
    "<a href=\"http://tpq.io\" target=\"_blank\">http://tpq.io</a> | <a href=\"http://twitter.com/dyjh\" target=\"_blank\">@dyjh</a> | <a href=\"mailto:training@tpq.io\">training@tpq.io</a>"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  },
  "pycharm": {
   "stem_cell": {
    "cell_type": "raw",
    "metadata": {
     "collapsed": false
    },
    "source": []
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}