A small library that wraps the OANDA API, for use in iOS
Objective-C Other
Latest commit b9e32c8 Jul 23, 2014 @stuartvc stuartvc updated README
Permalink
Failed to load latest commit information.
OTNetwork
OTNetworkDemo
OTNetworkOandaApiKiwi.xcworkspace fixed README bug Dec 5, 2012
AppledocSettings.plist
LICENSE
README.md
iOSNetworkingWithOandaApi.podspec

README.md

Disclaimer: The OANDA API is available for use on our live trading platform (fxTrade), our practice platform (fxTrade Practice) and our developer sandbox, where you are free to develop and test your apps. This sample code currently only works on our sandbox environment because this code does not support the authenticated requests needed by the other platforms.

OTNetwork is essentially a wrapper of the OANDA API, intended to handle all the low level requests with OANDA to trade in the FOREX market.

This simple guide describes how to incorporate it in your iOS app, so you could start trading FOREX.

Steps for Integration

These are the simple steps to follow to incorporate this library into your iOS project:

  1. Add the library itself. There are two ways to do this:
    • Manually include the library folder /OTNetwork/OTNetworkLayer into your project. This effectively includes OTNetworkController.h and OTNetworkController.m

      Please note you will need these third party libraries as well:

      • AFNetworking
      • JSONKit

* Or you could install the library via CocoaPods (assuming you have been following this workflow): * copy the included iOSNetworkingWithOandaApi.podspec to the location of your project's Podfile * edit your Podfile, and include this line:
            pod 'iOSNetworkingWithOandaApi', :podspec => 'iOSNetworkingWithOandaApi.podspec'
    
    * run <b>pod install</b> to update your .xcworkspace.  You should now find <b>iOSNetworkingWithOandaApi</b> as one of the pods installed.



2. Add these frameworks to your app: * MobileCoreServices.framework * SystemConfiguration.framework

3. Import OTNetworkController.h in relevant source files in your project

4. Create an instance of OTNetworkController. Your app should continue using it to handle all network requests to OANDA services (it's probably a good idea to store a pointer to it in your app's common shell).

That's it. Provided you have reliable network support (eg. Wifi, Ethernet, cell, etc.), you should be good to go.

NOTE: The library itself was developed using Kiwi as the testing framework, but it is not a mandatory requirement for your app.

For reference, please open the included OTNetworkOandaApi.xcworkspace. It includes the Kiwi framework, the OTNetwork library, and the simple demo OTNetworkDemo that illustrates how one could make asynchronous calls to the OANDA trading services via this library.

Notes on the OTNetwork Library

  • User authentication is not supported in this app, so simply pass in a username (see the API documentation page for details on creating a username). Please see accountListForUsername:success:failure: for further info.

  • It support the most commonly used feature set like polling for rates, making and closing orders & trades, generating reports, etc. Other features (eg. price alerts, news, etc.) are being worked on and not ready for this release.

  • We discourage creating more than once instance of the OTNetworkController, since having multiple ones simultaneously competing for network access from your app may result in poor and/or unpredictable performance.

  • Methods are asynchrounous, so do not expect to obtain results back immediately, or wait for them.

  • All methods require a Success block and a Failure block to be passed, and either would be triggered asynchronously depending on the outcome of network request. And these blocks all follow the same convention:

          typedef void (^NetworkSuccessBlock)(NSDictionary *result);
          typedef void (^NetworkFailBlock)(NSDictionary *error);
    
  • If an error occurs, the FailBlock above would return an NSDictionary with the following items to help you debug:

          "code" : OANDA error code, may or may not be the same as the HTTP status code
          "http status code" : response of the HTTP request to the network
          "message" : a description of the error which occurred, intended for developers
          "net error" : full error string received, intended for developers
    

Notes on the OTNetworkDemo App

  • It is a simple app created mainly to illustrate how to fetch updated rates, for all tradable symbol pairs, from the OANDA services. The most relevant sample code could be found in OTTableViewController.m

  • Kiwi is not needed for OTNetworkDemo.

Example 1: Getting Rates

Getting updated rates (ie. prices) for tradable currency pairs from OANDA is one of the most common operations. The following is a simple walkthrough for doing this using the OTNetwork library (for more info, please refer to the included OTNetworkDemo app):

  • Call rateListSymbolsSuccess:failure: to obtain a list of tradable currency pairs. In the Success block, extract the actual instruments list from the returned NSDictionary. Further extract a list of just symbol pairs, to be used later to quote for rates. You may want to save the original instruments list as well since it has more detailed info on each tradable pair (like proper display name).

           [self.networkDelegate rateListSymbolsSuccess:^(NSDictionary *responseObject)
           {
               //NSLog(@"Success!  %@", responseObject);
               self.listSymbols = [responseObject objectForKey:@"instruments"];
               
               // Build the array of strings to pass into rateQuote
               self.symbolsArray = [[NSMutableArray alloc] initWithCapacity:self.listSymbols.count];
               for (NSDictionary *symbolDict in self.listSymbols)
               {
                   [self.symbolsArray addObject:[NSString stringWithString:[symbolDict valueForKey:@"instrument"]]];
               }
               
               allowRatesFetching = YES;
           } failure:^(NSDictionary *error) {
               NSLog(@"Failure");
           }];
    
  • Call rateQuote:success:failure: to get actual quotes for a list of symbol pairs. In the Success block, extract the prices list from the returned NSDictionary.

          [self.networkDelegate rateQuote:self.symbolsArray
                           success:^(NSDictionary *responseObject)
           {
               NSLog(@"Success!  %d", callCount++);
               self.listRates = [responseObject objectForKey:@"prices"];
               [self.tableView reloadData];
               //NSLog(@"Rates: %@", responseObject);
               
           } failure:^(NSDictionary *error) {
               NSLog(@"Failure");
           }];
    
  • You now have a list of symbols and a list of prices ready for display.

Example 2: Making a "BUY" (ie. long) Order

You need a valid username with an active account to do this. In fact, at this point almost all requests to the OANDA services would need an account number:

  • (If you only have a username but no account number, follow this step, otherwise skip ahead) Call accountListForUsername:success:failure: to get a list of all active accounts belonging to your username. Then extract and save the account number of your choice from the list.

          [self.networkDelegate accountListForUsername:@"kyley"
                                               success:^(NSDictionary *responseObject)
           {
               NSLog(@"Success!  %@", responseObject);
               
               // say this is the account I am interested in
               NSDictionary *anAccount = [[responseObject objectForKey:@"array"] lastObject];
               gAccountId = [anAccount valueForKey:@"id"];
                                
           } failure:^(NSDictionary *error) {
               NSLog(@"Failure");
           }];
    
  • Using the obtained account ID, call createOrderForAccount:...success:failure: to make a order request. A successful network request would return an NSDictionary, and you could extract the order's id key value for later use (eg. quote the status of the order, make changes, cancel the order, etc.)

          [self.networkDelegate createOrderForAccount:gAccountId
                                        symbol:@"EUR/GBP"
                                         units:[NSNumber numberWithInt:123]
                                         side:@"buy"
                                          type:@"long"  //a buy request
                                         price:[[NSDecimalNumber alloc] initWithFloat:0.80443]
                                        expiry:[NSNumber numberWithInt:600]  // set to expire in 10 minutes
                             minExecutionPrice:nil  //optional
                             maxExecutionPrice:nil  //optional
                                      stopLoss:nil  //optional
                                    takeProfit:nil  //optional
                                  trailingStop:nil  //optional
                                       success:^(NSDictionary *responseObject)
           {
               NSLog(@"Success!  Order Created: %@", responseObject);
               gOrderId = [responseObject valueForKey:@"id"];
               // do something with gOrderId somewhere else
                                
           } failure:^(NSDictionary *error) {
               NSLog(@"Failure");
           }];
    

Further Details

For more information on the methods provided, please refer to the documentation in OTNetworkController.h

For in-depth info on the OANDA API used under the hood, please check out The OANDA API