Instrument Endpoints


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.
instrument path InstrumentName Name of the Instrument [required]
price query PricingComponent The Price component(s) to get candlestick data for. [default=M]
granularity query CandlestickGranularity The granularity of the candlesticks to fetch [default=S5]
count query integer The number of candlesticks to return in the response. Count should not be specified if both the start and end parameters are provided, as the time range combined with the granularity will determine the number of candlesticks to return. [default=500, maximum=5000]
from query DateTime The start of the time range to fetch candlesticks for.
to query DateTime The end of the time range to fetch candlesticks for.
smooth query boolean A flag that controls whether the candlestick is “smoothed” or not. A smoothed candlestick uses the previous candle’s close price as its open price, while an un-smoothed candlestick uses the first price from its time range as its open price. [default=False]
includeFirst query boolean A flag that controls whether the candlestick that is covered by the from time should be included in the results. This flag enables clients to use the timestamp of the last completed candlestick received to poll for future candlesticks but avoid receiving the previous candlestick repeatedly. [default=True]
dailyAlignment query integer The hour of the day (in the specified timezone) to use for granularities that have daily alignments. [default=17, minimum=0, maximum=23]
alignmentTimezone query string The timezone to use for the dailyAlignment parameter. Candlesticks with daily alignment will be aligned to the dailyAlignment hour within the alignmentTimezone. Note that the returned times will still be represented in UTC. [default=America/New_York]
weeklyAlignment query WeeklyAlignment The day of the week used for granularities that have weekly alignment. [default=Friday]

Responses

Response Headers

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

{
    # 
    # The instrument whose Prices are represented by the candlesticks.
    # 
    instrument : (InstrumentName),

    # 
    # The granularity of the candlesticks provided.
    # 
    granularity : (CandlestickGranularity),

    # 
    # The list of candlesticks that satisfy the request.
    # 
    candles : (Array[Candlestick])
}

Other Error Responses: 400, 401, 404, 405

Examples

Request
curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/instruments/EUR_USD/candles?count=6&price=M&granularity=S5"
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-Length: 854
Content-Type: application/json
Response Body
{
  "candles": [
    {
      "complete": true, 
      "mid": {
        "c": "1.09946", 
        "h": "1.09949", 
        "l": "1.09946", 
        "o": "1.09949"
      }, 
      "time": "2016-10-17T15:16:40.000000000Z", 
      "volume": 2
    }, 
    {
      "complete": true, 
      "mid": {
        "c": "1.09947", 
        "h": "1.09947", 
        "l": "1.09947", 
        "o": "1.09946"
      }, 
      "time": "2016-10-17T15:16:45.000000000Z", 
      "volume": 1
    }, 
    {
      "complete": true, 
      "mid": {
        "c": "1.09947", 
        "h": "1.09950", 
        "l": "1.09947", 
        "o": "1.09947"
      }, 
      "time": "2016-10-17T15:17:00.000000000Z", 
      "volume": 2
    }, 
    {
      "complete": true, 
      "mid": {
        "c": "1.09951", 
        "h": "1.09951", 
        "l": "1.09951", 
        "o": "1.09947"
      }, 
      "time": "2016-10-17T15:17:05.000000000Z", 
      "volume": 1
    }, 
    {
      "complete": true, 
      "mid": {
        "c": "1.09954", 
        "h": "1.09954", 
        "l": "1.09954", 
        "o": "1.09951"
      }, 
      "time": "2016-10-17T15:17:15.000000000Z", 
      "volume": 1
    }, 
    {
      "complete": false, 
      "mid": {
        "c": "1.09961", 
        "h": "1.09961", 
        "l": "1.09958", 
        "o": "1.09954"
      }, 
      "time": "2016-10-17T15:17:20.000000000Z", 
      "volume": 3
    }
  ], 
  "granularity": "S5", 
  "instrument": "EUR/USD"
}
Request
curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/instruments/USD_CAD/candles?price=BA&from=2016-10-17T15%3A00%3A00.000000000Z&granularity=M1"
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-Length: 3620
Content-Type: application/json
Response Body
{
  "candles": [
    {
      "ask": {
        "c": "1.31469", 
        "h": "1.31520", 
        "l": "1.31467", 
        "o": "1.31509"
      }, 
      "bid": {
        "c": "1.31454", 
        "h": "1.31502", 
        "l": "1.31450", 
        "o": "1.31493"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:00:00.000000000Z", 
      "volume": 70
    }, 
    {
      "ask": {
        "c": "1.31447", 
        "h": "1.31485", 
        "l": "1.31445", 
        "o": "1.31469"
      }, 
      "bid": {
        "c": "1.31431", 
        "h": "1.31470", 
        "l": "1.31427", 
        "o": "1.31454"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:01:00.000000000Z", 
      "volume": 68
    }, 
    {
      "ask": {
        "c": "1.31448", 
        "h": "1.31454", 
        "l": "1.31440", 
        "o": "1.31447"
      }, 
      "bid": {
        "c": "1.31429", 
        "h": "1.31437", 
        "l": "1.31423", 
        "o": "1.31431"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:02:00.000000000Z", 
      "volume": 53
    }, 
    {
      "ask": {
        "c": "1.31474", 
        "h": "1.31482", 
        "l": "1.31452", 
        "o": "1.31448"
      }, 
      "bid": {
        "c": "1.31458", 
        "h": "1.31464", 
        "l": "1.31433", 
        "o": "1.31429"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:03:00.000000000Z", 
      "volume": 56
    }, 
    {
      "ask": {
        "c": "1.31433", 
        "h": "1.31476", 
        "l": "1.31433", 
        "o": "1.31474"
      }, 
      "bid": {
        "c": "1.31417", 
        "h": "1.31458", 
        "l": "1.31417", 
        "o": "1.31458"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:04:00.000000000Z", 
      "volume": 31
    }, 
    {
      "ask": {
        "c": "1.31453", 
        "h": "1.31462", 
        "l": "1.31417", 
        "o": "1.31433"
      }, 
      "bid": {
        "c": "1.31435", 
        "h": "1.31443", 
        "l": "1.31396", 
        "o": "1.31417"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:05:00.000000000Z", 
      "volume": 50
    }, 
    {
      "ask": {
        "c": "1.31452", 
        "h": "1.31454", 
        "l": "1.31443", 
        "o": "1.31453"
      }, 
      "bid": {
        "c": "1.31434", 
        "h": "1.31436", 
        "l": "1.31426", 
        "o": "1.31435"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:06:00.000000000Z", 
      "volume": 35
    }, 
    {
      "ask": {
        "c": "1.31446", 
        "h": "1.31468", 
        "l": "1.31444", 
        "o": "1.31452"
      }, 
      "bid": {
        "c": "1.31429", 
        "h": "1.31449", 
        "l": "1.31426", 
        "o": "1.31434"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:07:00.000000000Z", 
      "volume": 49
    }, 
    {
      "ask": {
        "c": "1.31453", 
        "h": "1.31453", 
        "l": "1.31432", 
        "o": "1.31446"
      }, 
      "bid": {
        "c": "1.31435", 
        "h": "1.31435", 
        "l": "1.31414", 
        "o": "1.31429"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:08:00.000000000Z", 
      "volume": 55
    }, 
    {
      "ask": {
        "c": "1.31444", 
        "h": "1.31454", 
        "l": "1.31435", 
        "o": "1.31453"
      }, 
      "bid": {
        "c": "1.31427", 
        "h": "1.31435", 
        "l": "1.31418", 
        "o": "1.31435"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:09:00.000000000Z", 
      "volume": 40
    }, 
    {
      "ask": {
        "c": "1.31454", 
        "h": "1.31460", 
        "l": "1.31446", 
        "o": "1.31444"
      }, 
      "bid": {
        "c": "1.31436", 
        "h": "1.31442", 
        "l": "1.31428", 
        "o": "1.31427"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:10:00.000000000Z", 
      "volume": 45
    }, 
    {
      "ask": {
        "c": "1.31359", 
        "h": "1.31454", 
        "l": "1.31359", 
        "o": "1.31454"
      }, 
      "bid": {
        "c": "1.31339", 
        "h": "1.31437", 
        "l": "1.31338", 
        "o": "1.31436"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:11:00.000000000Z", 
      "volume": 55
    }, 
    {
      "ask": {
        "c": "1.31389", 
        "h": "1.31391", 
        "l": "1.31330", 
        "o": "1.31359"
      }, 
      "bid": {
        "c": "1.31370", 
        "h": "1.31370", 
        "l": "1.31312", 
        "o": "1.31339"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:12:00.000000000Z", 
      "volume": 79
    }, 
    {
      "ask": {
        "c": "1.31405", 
        "h": "1.31405", 
        "l": "1.31365", 
        "o": "1.31389"
      }, 
      "bid": {
        "c": "1.31385", 
        "h": "1.31387", 
        "l": "1.31347", 
        "o": "1.31370"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:13:00.000000000Z", 
      "volume": 87
    }, 
    {
      "ask": {
        "c": "1.31418", 
        "h": "1.31418", 
        "l": "1.31392", 
        "o": "1.31405"
      }, 
      "bid": {
        "c": "1.31399", 
        "h": "1.31399", 
        "l": "1.31372", 
        "o": "1.31385"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:14:00.000000000Z", 
      "volume": 63
    }, 
    {
      "ask": {
        "c": "1.31421", 
        "h": "1.31423", 
        "l": "1.31411", 
        "o": "1.31418"
      }, 
      "bid": {
        "c": "1.31402", 
        "h": "1.31406", 
        "l": "1.31392", 
        "o": "1.31399"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:15:00.000000000Z", 
      "volume": 43
    }, 
    {
      "ask": {
        "c": "1.31440", 
        "h": "1.31443", 
        "l": "1.31425", 
        "o": "1.31421"
      }, 
      "bid": {
        "c": "1.31422", 
        "h": "1.31426", 
        "l": "1.31406", 
        "o": "1.31402"
      }, 
      "complete": true, 
      "time": "2016-10-17T15:16:00.000000000Z", 
      "volume": 41
    }, 
    {
      "ask": {
        "c": "1.31425", 
        "h": "1.31444", 
        "l": "1.31420", 
        "o": "1.31440"
      }, 
      "bid": {
        "c": "1.31406", 
        "h": "1.31425", 
        "l": "1.31402", 
        "o": "1.31422"
      }, 
      "complete": false, 
      "time": "2016-10-17T15:17:00.000000000Z", 
      "volume": 22
    }
  ], 
  "granularity": "M1", 
  "instrument": "USD/CAD"
}
Request
curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/instruments/USD_JPY/candles?count=10&price=A&from=2016-01-01T00%3A00%3A00.000000000Z&granularity=D"
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-Length: 1424
Content-Type: application/json
Response Body
{
  "candles": [
    {
      "ask": {
        "c": "119.461", 
        "h": "120.473", 
        "l": "118.713", 
        "o": "120.245"
      }, 
      "complete": true, 
      "time": "2016-01-03T22:00:00.000000000Z", 
      "volume": 42744
    }, 
    {
      "ask": {
        "c": "119.080", 
        "h": "119.725", 
        "l": "118.801", 
        "o": "119.461"
      }, 
      "complete": true, 
      "time": "2016-01-04T22:00:00.000000000Z", 
      "volume": 33404
    }, 
    {
      "ask": {
        "c": "118.494", 
        "h": "119.185", 
        "l": "118.258", 
        "o": "119.080"
      }, 
      "complete": true, 
      "time": "2016-01-05T22:00:00.000000000Z", 
      "volume": 46689
    }, 
    {
      "ask": {
        "c": "117.683", 
        "h": "118.767", 
        "l": "117.337", 
        "o": "118.494"
      }, 
      "complete": true, 
      "time": "2016-01-06T22:00:00.000000000Z", 
      "volume": 63402
    }, 
    {
      "ask": {
        "c": "117.288", 
        "h": "118.902", 
        "l": "117.259", 
        "o": "117.683"
      }, 
      "complete": true, 
      "time": "2016-01-07T22:00:00.000000000Z", 
      "volume": 67876
    }, 
    {
      "ask": {
        "c": "117.772", 
        "h": "118.035", 
        "l": "116.719", 
        "o": "117.288"
      }, 
      "complete": true, 
      "time": "2016-01-10T22:00:00.000000000Z", 
      "volume": 57592
    }, 
    {
      "ask": {
        "c": "117.663", 
        "h": "118.082", 
        "l": "117.236", 
        "o": "117.772"
      }, 
      "complete": true, 
      "time": "2016-01-11T22:00:00.000000000Z", 
      "volume": 51312
    }, 
    {
      "ask": {
        "c": "117.678", 
        "h": "118.389", 
        "l": "117.652", 
        "o": "117.663"
      }, 
      "complete": true, 
      "time": "2016-01-12T22:00:00.000000000Z", 
      "volume": 43982
    }, 
    {
      "ask": {
        "c": "118.081", 
        "h": "118.292", 
        "l": "117.302", 
        "o": "117.678"
      }, 
      "complete": true, 
      "time": "2016-01-13T22:00:00.000000000Z", 
      "volume": 54370
    }, 
    {
      "ask": {
        "c": "117.063", 
        "h": "118.282", 
        "l": "116.517", 
        "o": "118.081"
      }, 
      "complete": true, 
      "time": "2016-01-14T22:00:00.000000000Z", 
      "volume": 63671
    }
  ], 
  "granularity": "D", 
  "instrument": "USD/JPY"
}

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.
instrument path InstrumentName Name of the Instrument [required]
time query DateTime The time of the snapshot to fetch. If not specified, then the most recent snapshot is fetched.

Responses

Response Headers

  • Content-Encoding - Value will be “gzip” regardless of provided Accept-Encoding header
  • Link - A link to the next/previous order book snapshot.
  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The instrument’s order book
    # 
    orderBook : (OrderBook)
}

Other Error Responses: 400, 401, 404, 405

Examples

Request
curl \
  --compressed \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/instruments/USD_JPY/orderBook"
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-Length: 1424
Content-Type: application/json
Link: </v3/instruments/USD_JPY/orderBook?time=2017-01-10T14:20:00Z>; rel="prev", </v3/instruments/USD_JPY/orderBook?time=2017-01-10T15:00:00Z>; rel="next"
Response Body
{
  "orderBook": {
    "instrument": "USD_JPY",
    "time": "2017-01-10T14:40:00Z",
    "price": "115.774",
    "bucketWidth": "0.050",
    "buckets": [
      {
        "price": "0.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      },
      {
        "price": "80.900",
        "longCountPercent": "0.0106",
        "shortCountPercent": "0.0000"
      },
      {
        "price": "115.450",
        "longCountPercent": "0.1583",
        "shortCountPercent": "0.0317"
      },
      {
        "price": "115.500",
        "longCountPercent": "0.3378",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "115.550",
        "longCountPercent": "0.2428",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "116.000",
        "longCountPercent": "0.4434",
        "shortCountPercent": "0.1689"
      },
      {
        "price": "150.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      }
    ]
  }
}
Request
curl \
  --compressed \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/instruments/USD_JPY/orderBook?time=2017-01-13T04%3A20%3A00.000Z"
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-Length: 1424
Content-Type: application/
Link: </v3/instruments/USD_JPY/orderBook?time=2017-01-13T04:00:00Z>; rel="prev", </v3/instruments/USD_JPY/orderBook?time=2017-01-13T04:40:00Z>; rel="next"
Response Body
{
  "orderBook": {
    "instrument": "USD_JPY",
    "time": "2017-01-13T04:20:00Z",
    "price": "115.096",
    "bucketWidth": "0.050",
    "buckets": [
      {
        "price": "0.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      },
      {
        "price": "80.900",
        "longCountPercent": "0.0106",
        "shortCountPercent": "0.0000"
      },
      {
        "price": "115.450",
        "longCountPercent": "0.1583",
        "shortCountPercent": "0.0317"
      },
      {
        "price": "115.500",
        "longCountPercent": "0.3378",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "115.550",
        "longCountPercent": "0.2428",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "116.000",
        "longCountPercent": "0.4434",
        "shortCountPercent": "0.1689"
      },
      {
        "price": "150.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      }
    ]
  }
}

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.
instrument path InstrumentName Name of the Instrument [required]
time query DateTime The time of the snapshot to fetch. If not specified, then the most recent snapshot is fetched.

Responses

Response Headers

  • Content-Encoding - Value will be “gzip” regardless of provided Accept-Encoding header
  • Link - A link to the next/previous position book snapshot.
  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The instrument’s position book
    # 
    positionBook : (PositionBook)
}

Other Error Responses: 400, 401, 404, 405

Examples

Request
curl \
  --compressed \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/instruments/USD_JPY/positionBook"
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-Length: 1424
Content-Type: application/json
Link: </v3/instruments/USD_JPY/positionBook?time=2017-01-10T14:20:00Z>; rel="prev", </v3/instruments/USD_JPY/positionBook?time=2017-01-10T15:00:00Z>; rel="next"
Response Body
{
  "positionBook": {
    "instrument": "USD_JPY",
    "time": "2017-01-10T14:40:00Z",
    "price": "115.774",
    "bucketWidth": "0.050",
    "buckets": [
      {
        "price": "0.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      },
      {
        "price": "80.900",
        "longCountPercent": "0.0106",
        "shortCountPercent": "0.0000"
      },
      {
        "price": "115.450",
        "longCountPercent": "0.1583",
        "shortCountPercent": "0.0317"
      },
      {
        "price": "115.500",
        "longCountPercent": "0.3378",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "115.550",
        "longCountPercent": "0.2428",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "116.000",
        "longCountPercent": "0.4434",
        "shortCountPercent": "0.1689"
      },
      {
        "price": "150.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      }
    ]
  }
}
Request
curl \
  --compressed \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/instruments/USD_JPY/positionBook?time=2017-01-13T04%3A00%3A00.000Z"
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-Length: 1424
Content-Type: application/
Link: </v3/instruments/USD_JPY/positionBook?time=2017-01-13T03:40:00Z>; rel="prev", </v3/instruments/USD_JPY/positionBook?time=2017-01-13T04:20:00Z>; rel="next"
Response Body
{
  "positionBook": {
    "instrument": "USD_JPY",
    "time": "2017-01-13T04:00:00Z",
    "price": "115.096",
    "bucketWidth": "0.050",
    "buckets": [
      {
        "price": "0.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      },
      {
        "price": "80.900",
        "longCountPercent": "0.0106",
        "shortCountPercent": "0.0000"
      },
      {
        "price": "115.450",
        "longCountPercent": "0.1583",
        "shortCountPercent": "0.0317"
      },
      {
        "price": "115.500",
        "longCountPercent": "0.3378",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "115.550",
        "longCountPercent": "0.2428",
        "shortCountPercent": "0.1161"
      },
      {
        "price": "116.000",
        "longCountPercent": "0.4434",
        "shortCountPercent": "0.1689"
      },
      {
        "price": "150.000",
        "longCountPercent": "0.0000",
        "shortCountPercent": "0.0106"
      }
    ]
  }
}