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
- RequestID - The unique identifier generated for the request
{ # # 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
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/jsonResponse 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" }
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/jsonResponse 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" }
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/jsonResponse 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
- 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
{ # # The instrument’s order book # orderBook : (OrderBook) }
Other Error Responses: 400, 401, 404, 405
Examples
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" } ] } }
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
- 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
{ # # The instrument’s position book # positionBook : (PositionBook) }
Other Error Responses: 400, 401, 404, 405
Examples
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" } ] } }
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" } ] } }