oandapyV20 Documentation

The oandapyV20.definitions module contains the data structures and object definitions that mirror the official OANDA REST-V20 specifications. You can use these definitions to construct valid request bodies and parse response data for various API resources.

The module is organized into submodules corresponding to specific OANDA resource types:

• oandapyV20.definitions.accounts: Account-related definitions.
• oandapyV20.definitions.instruments: Instrument-related definitions.
• oandapyV20.definitions.orders: Order-related definitions.
• oandapyV20.definitions.pricing: Pricing-related definitions.
• oandapyV20.definitions.trades: Trade-related definitions.
• oandapyV20.definitions.transactions: Transaction-related definitions.

The library is structured around APIRequest objects.

1. APIRequest: All endpoints are represented as APIRequest objects derived from a base APIRequest class.
2. Endpoint Groups: Functionality is organized into abstract classes representing endpoint groups (e.g., accounts, trades).
3. Specific Endpoints: Each specific endpoint within a group is implemented as a class derived from that group's abstract class.
4. Client: The API client class is responsible for processing these APIRequest objects.

You can optionally use ClientExtensions on Order Requests to attach custom metadata to your orders. This allows you to set a custom id, tag, and/or comment for tracking and identification purposes within the OANDA API.

from oandapyV20.contrib.requests import ClientExtensions

# Example of initializing client extensions
extensions = ClientExtensions(id="my_custom_id", tag="my_tag", comment="my_comment")

The oandapyV20.contrib.requests module provides optional support classes to simplify the creation of complex Order Requests. These classes are specifically useful when you need to define dependent orders that trigger once a primary position is filled, such as Take Profit and Stop Loss orders.

To implement these, you can use:

• contrib.requests.*Order classes to define the order specifications.
• contrib.requests.*Details classes to provide additional data required by those specifications.

When creating an order to open a position, you can use the oandapyV20.contrib.requests module to define dependent orders that are triggered once the initial position is filled. This is commonly used for setting Take Profit and Stop Loss instructions.

To implement this, use the following types of classes from oandapyV20.contrib.requests:

• *Order classes: To specify the order type and logic.
• *Details classes: To provide the additional data required by those order specifications.

Install the stable version of the oandapyV20 package directly from PyPI using pip.

$ pip install oandapyV20

If you need the most recent updates, you can install the development version directly from the GitHub repository.

$ pip install git+https://github.com/hootnot/oanda-api-v20.git

To run the project's test suite or install from a local source clone, follow these steps:

1. Clone the repository.
2. Navigate into the directory.
3. Run the tests using setup.py.
4. Install the package locally using setup.py.

$ git clone https://github.com/hootnot/oanda-api-v20.git
$ cd oanda-api-v20
$ python setup.py test
$ python setup.py install

The oandapyV20 package has integrated logging. You can capture API activity, including request URLs and error messages, by configuring the standard Python logging module. This is useful for debugging failed requests or monitoring connection activity.

import logging
from oandapyV20 import API
import oandapyV20.endpoints.orders as orders
from oandapyV20.exceptions import V20Error

# Configure logging to output to a file
logging.basicConfig(
    filename="v20.log",
    level=logging.INFO,
    format='%(asctime)s [%(levelname)s] %(name)s : %(message)s',
)

# Example usage
client = API(access_token='YOUR_TOKEN')
try:
    request = orders.OrderList(account_id='YOUR_ACCOUNT_ID')
    response = client.request(request)
except V20Error as e:
    logging.error(f"API Error: {e}")

The oandapyV20 library uses a decoupled architecture consisting of a Client and APIRequest objects:

• Client: Acts as the central API processor. It takes APIRequest objects, performs the network operation, and assigns the status and response properties to the request object. The client also returns the response.
• Requests: Endpoints are represented as APIRequest objects derived from a base APIRequest class. Endpoints are organized into hierarchical groups (e.g., accounts, trades) where an abstract class covers the group's functionality, and specific endpoint classes derive from those abstract classes.