Which API should I use?

  • Use v20 REST API only if you have a v20 account
  • Use v1 REST API if your account id contains only digits (ie. 2534253) as it is a legacy account

Pricing Endpoints


GET/v3/accounts/{accountID}/pricing

Get pricing information for a specified list of Instruments within an Account.

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]
instruments query List of InstrumentName (csv) List of Instruments to get pricing for. [required]
since query DateTime Date/Time filter to apply to the response. Only prices and home conversions (if requested) with a time later than this filter (i.e. the price has changed after the since time) will be provided, and are filtered independently.
includeUnitsAvailable query boolean Flag that enables the inclusion of the unitsAvailable field in the returned Price objects. [default=True]

Deprecated: Will be removed in a future API update.

includeHomeConversions query boolean Flag that enables the inclusion of the homeConversions field in the returned response. An entry will be returned for each currency in the set of all base and quote currencies present in the requested instruments list. [default=False]

Responses

Response Headers

  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json) 

{
    # 
    # The list of Price objects requested.
    # 
    prices : (Array[Price], required),

    # 
    # The list of home currency conversion factors requested. This field will
    # only be present if includeHomeConversions was set to true in the request.
    # 
    homeConversions : (Array[HomeConversions]),

    # 
    # The DateTime value to use for the “since” parameter in the next poll
    # request.
    # 
    time : (DateTime)
}

Other Error Responses: 400, 401, 404, 405

Examples

Request 
curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/accounts/<ACCOUNT>/pricing?instruments=EUR_USD%2CUSD_CAD"
Response Headers 
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format
Content-Encoding: gzip
Transfer-Encoding: chunked
Server: openresty/1.7.0.1
Connection: keep-alive
Date: Wed, 22 Jun 2016 18:41:38 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body 
{
  "prices": [
    {
      "asks": [
        {
          "liquidity": 10000000, 
          "price": "1.13028"
        }, 
        {
          "liquidity": 10000000, 
          "price": "1.13030"
        }
      ], 
      "bids": [
        {
          "liquidity": 10000000, 
          "price": "1.13015"
        }, 
        {
          "liquidity": 10000000, 
          "price": "1.13013"
        }
      ], 
      "closeoutAsk": "1.13032", 
      "closeoutBid": "1.13011", 
      "instrument": "EUR_USD", 
      "quoteHomeConversionFactors": {
        "negativeUnits": "0.95904000", 
        "positiveUnits": "0.95886000"
      }, 
      "status": "tradeable", 
      "time": "2016-06-22T18:41:36.201836422Z", 
      "unitsAvailable": {
        "default": {
          "long": "2013434", 
          "short": "2014044"
        }, 
        "openOnly": {
          "long": "2013434", 
          "short": "2014044"
        }, 
        "reduceFirst": {
          "long": "2013434", 
          "short": "2014044"
        }, 
        "reduceOnly": {
          "long": "0", 
          "short": "0"
        }
      }
    }, 
    {
      "asks": [
        {
          "liquidity": 1000000, 
          "price": "1.28260"
        }, 
        {
          "liquidity": 2000000, 
          "price": "1.28261"
        }, 
        {
          "liquidity": 5000000, 
          "price": "1.28262"
        }, 
        {
          "liquidity": 10000000, 
          "price": "1.28264"
        }
      ], 
      "bids": [
        {
          "liquidity": 1000000, 
          "price": "1.28241"
        }, 
        {
          "liquidity": 2000000, 
          "price": "1.28240"
        }, 
        {
          "liquidity": 5000000, 
          "price": "1.28239"
        }, 
        {
          "liquidity": 10000000, 
          "price": "1.28237"
        }
      ], 
      "closeoutAsk": "1.28264", 
      "closeoutBid": "1.28237", 
      "instrument": "USD_CAD", 
      "quoteHomeConversionFactors": {
        "negativeUnits": "0.74785000", 
        "positiveUnits": "0.74759000"
      }, 
      "status": "tradeable", 
      "time": "2016-06-22T18:41:36.042678456Z", 
      "unitsAvailable": {
        "default": {
          "long": "2275373", 
          "short": "2276522"
        }, 
        "openOnly": {
          "long": "2275373", 
          "short": "2276522"
        }, 
        "reduceFirst": {
          "long": "2275373", 
          "short": "2276522"
        }, 
        "reduceOnly": {
          "long": "0", 
          "short": "0"
        }
      }
    }
  ]
}

GET/v3/accounts/{accountID}/pricing/stream

Get a stream of Account Prices starting from when the request is made. This pricing stream does not include every single price created for the Account, but instead will provide at most 4 prices per second (every 250 milliseconds) for each instrument being requested. If more than one price is created for an instrument during the 250 millisecond window, only the price in effect at the end of the window is sent. This means that during periods of rapid price movement, subscribers to this stream will not be sent every price. Pricing windows for different connections to the price stream are not all aligned in the same way (i.e. they are not all aligned to the top of the second). This means that during periods of rapid price movement, different subscribers may observe different prices depending on their alignment.

Note: This endpoint is served by the streaming URLs.

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]
instruments query List of InstrumentName (csv) List of Instruments to stream Prices for. [required]
snapshot query boolean Flag that enables/disables the sending of a pricing snapshot when initially connecting to the stream. [default=True]

Responses

Response Body Schema (application/octet-stream)

The response body for the Pricing Stream uses chunked transfer encoding. Each chunk contains Price and/or PricingHeartbeat objects encoded as JSON. Each JSON object is serialized into a single line of text, and multiple objects found in the same chunk are separated by newlines. Heartbeats are sent every 5 seconds.

The specification for the objects found in response stream are as follows:

Other Error Responses: 400, 401, 404, 405

Examples

Request 
curl \
  -H "Authorization: Bearer <TOKEN>" \
  "<STREAM_URL>/v3/accounts/<ACCOUNT>/pricing/stream?instruments=EUR_USD%2CUSD_CAD"
Response Headers 
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format, OANDA-Agent
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Access-Control-Allow-Origin: *
Content-Type: application/octet-stream
Response Body 
{"asks":[{"liquidity":10000000,"price":"1.11704"},{"liquidity":10000000,"price":"1.11706"}],"bids":                        [{"liquidity":10000000,"price":"1.11690"},{"liquidity":10000000,"price":"1.11688"}],"closeoutAsk":"1.11708","closeoutBid":"1.11686","instrument":"EUR_USD","status":"tradeable","time":"2016-09-20T15:05:47.960449532Z"}
{"asks":[{"liquidity":1000000,"price":"1.32149"},{"liquidity":2000000,"price":"1.32150"},{"liquidity":5000000,"price":"1.32151"},{"liquidity":10000000,"price":"1.32153"}],"bids":[{"liquidity":1000000,"price":"1.32128"},{"liquidity":2000000,"price":"1.32127"},{"liquidity":5000000,"price":"1.32126"},{"liquidity":10000000,"price":"1.32124"}],"closeoutAsk":"1.32153","closeoutBid":"1.32124","instrument":"USD_CAD","status":"tradeable","time":"2016-09-20T15:05:48.157162748Z"}
{"asks":[{"liquidity":1000000,"price":"1.32145"},{"liquidity":2000000,"price":"1.32146"},{"liquidity":5000000,"price":"1.32147"},{"liquidity":10000000,"price":"1.32149"}],"bids":[{"liquidity":1000000,"price":"1.32123"},{"liquidity":2000000,"price":"1.32122"},{"liquidity":5000000,"price":"1.32121"},{"liquidity":10000000,"price":"1.32119"}],"closeoutAsk":"1.32149","closeoutBid":"1.32119","instrument":"USD_CAD","status":"tradeable","time":"2016-09-20T15:05:48.272079801Z"}
{"asks":[{"liquidity":1000000,"price":"1.32147"},{"liquidity":2000000,"price":"1.32148"},{"liquidity":5000000,"price":"1.32149"},{"liquidity":10000000,"price":"1.32151"}],"bids":[{"liquidity":1000000,"price":"1.32126"},{"liquidity":2000000,"price":"1.32125"},{"liquidity":5000000,"price":"1.32124"},{"liquidity":10000000,"price":"1.32122"}],"closeoutAsk":"1.32151","closeoutBid":"1.32122","instrument":"USD_CAD","status":"tradeable","time":"2016-09-20T15:05:48.540813660Z"}
{"time":"2016-09-20T15:05:50.163791738Z","type":"HEARTBEAT"}