Market Data Models¶
OANDA Reference: Pricing Data Definitions | Instrument Data Definitions
Models for market pricing, instrument specifications, and candlestick (OHLC) data.
Pricing Models¶
ClientPrice¶
Current market prices for an instrument.
🔗 OANDA Definition: ClientPrice
🔗 Source: ClientPrice
| Field | Type | Required | Description |
|---|---|---|---|
type |
str | âž– | Price type identifier (default: "PRICE") |
instrument |
InstrumentName | ✅ | Trading instrument identifier |
time |
DateTime | ✅ | Timestamp when price was created |
status |
PriceStatus | âž– | Price status (deprecated but may still be present) |
tradeable |
bool | ✅ | Whether the instrument is currently tradeable |
bids |
list[PriceBucket] | ✅ | Available bid prices and liquidity levels |
asks |
list[PriceBucket] | ✅ | Available ask prices and liquidity levels |
closeout_bid |
PriceValue | ✅ | Bid price used for position closeout (closing long positions) |
closeout_ask |
PriceValue | ✅ | Ask price used for position closeout (closing short positions) |
quote_home_conversion_factors |
QuoteHomeConversionFactors | âž– | Currency conversion factors for quote currency calculations |
units_available |
UnitsAvailable | âž– | Available units for trading different order types |
QuoteHomeConversionFactors¶
Conversion factors for quote currency calculations.
🔗 OANDA Definition: QuoteHomeConversionFactors
🔗 Source: QuoteHomeConversionFactors
| Field | Type | Required | Description |
|---|---|---|---|
positive_units |
Decimal | ✅ | Conversion factor for positive (long) units |
negative_units |
Decimal | ✅ | Conversion factor for negative (short) units |
HomeConversions¶
Currency conversion factors for account calculations.
🔗 OANDA Definition: HomeConversions
🔗 Source: HomeConversions
| Field | Type | Required | Description |
|---|---|---|---|
currency |
Currency | ✅ | The currency being converted |
account_gain |
Decimal | ✅ | Factor for converting gains to account currency |
account_loss |
Decimal | ✅ | Factor for converting losses to account currency |
position_value |
Decimal | ✅ | Factor for converting position values |
PricingHeartbeat¶
Heartbeat message for pricing streams.
🔗 OANDA Definition: PricingHeartbeat
🔗 Source: PricingHeartbeat
| Field | Type | Required | Description |
|---|---|---|---|
type |
str | âž– | Always "HEARTBEAT" |
time |
DateTime | ✅ | Heartbeat timestamp |
UnitsAvailable¶
Representation of how many units of an Instrument are available to be traded.
🔗 OANDA Definition: UnitsAvailable
🔗 Source: UnitsAvailable
| Field | Type | Required | Description |
|---|---|---|---|
default |
dict[str, Decimal] | ✅ | Default units available by instrument |
reduce_first |
dict[str, Decimal] | ✅ | Units available for reduce-first fills by instrument |
reduce_only |
dict[str, Decimal] | ✅ | Units available for reduce-only fills by instrument |
open_only |
dict[str, Decimal] | ✅ | Units available for open-only fills by instrument |
PriceBucket¶
Price level with available liquidity.
🔗 OANDA Definition: PriceBucket
🔗 Source: PriceBucket
| Field | Type | Required | Description |
|---|---|---|---|
price |
PriceValue | ✅ | The quoted price at this level |
liquidity |
Decimal | ✅ | Available volume (units) at this price level |
Candlestick¶
OHLC candlestick data for an instrument.
🔗 OANDA Definition: Candlestick
🔗 Source: Candlestick
| Field | Type | Required | Description |
|---|---|---|---|
time |
DateTime | ✅ | Start time of the candlestick period |
bid |
CandlestickData | âž– | Bid-based OHLC data for the time period |
ask |
CandlestickData | âž– | Ask-based OHLC data for the time period |
mid |
CandlestickData | âž– | Mid-price OHLC data ((bid+ask)/2) for the time period |
volume |
int | ✅ | Number of price ticks during the time period |
complete |
bool | ✅ | Whether the candlestick is complete (end time is not in future) |
CandlestickData¶
Open, High, Low, Close data for one price type.
🔗 OANDA Definition: CandlestickData
🔗 Source: CandlestickData
| Field | Type | Required | Description |
|---|---|---|---|
o |
PriceValue | ✅ | Opening price for the time period |
h |
PriceValue | ✅ | Highest price during the time period |
l |
PriceValue | ✅ | Lowest price during the time period |
c |
PriceValue | ✅ | Closing price for the time period |
Instrument Models¶
Instrument¶
Trading instrument information and specifications.
🔗 OANDA Definition: Instrument
🔗 Source: Instrument
| Field | Type | Required | Description |
|---|---|---|---|
name |
InstrumentName | ✅ | Unique instrument identifier (e.g., "EUR_USD") |
type |
InstrumentType | ✅ | Classification of instrument (CURRENCY, CFD, METAL) |
display_name |
str | ✅ | Human-readable instrument name |
pip_location |
int | ✅ | Location of pip value (decimal places from right) |
display_precision |
int | ✅ | Number of decimal places for display formatting |
trade_units_precision |
int | ✅ | Decimal precision for trade unit values |
minimum_trade_size |
Decimal | ✅ | Smallest allowable trade size for this instrument |
maximum_trailing_stop_distance |
Decimal | ✅ | Maximum trailing stop distance allowed |
minimum_trailing_stop_distance |
Decimal | ✅ | Minimum trailing stop distance required |
maximum_position_size |
Decimal | ✅ | Maximum position size allowed for this instrument |
maximum_order_units |
Decimal | ✅ | Maximum order size allowed for this instrument |
margin_rate |
Decimal | ✅ | Margin requirement as decimal (e.g., "0.03333" for 30:1 leverage) |
minimum_guaranteed_stop_loss_distance |
Decimal | âž– | Minimum distance for guaranteed stop loss orders |
commission |
InstrumentCommission | âž– | Commission structure for this instrument |
guaranteed_stop_loss_order_mode |
GuaranteedStopLossOrderModeForInstrument | âž– | Guaranteed stop loss availability (DISABLED, ALLOWED, REQUIRED) |
guaranteed_stop_loss_order_execution_premium |
Decimal | âž– | Premium charged for guaranteed stop loss execution |
guaranteed_stop_loss_order_level_restriction |
GuaranteedStopLossOrderLevelRestriction | âž– | Restrictions on guaranteed stop loss levels |
financing |
InstrumentFinancing | âž– | Daily financing rate details for long and short positions |
tags |
list[Tag] | ✅ | Descriptive tags for instrument categorization |
InstrumentCommission¶
Commission structure for trading instruments.
🔗 OANDA Definition: InstrumentCommission
🔗 Source: InstrumentCommission
| Field | Type | Required | Description |
|---|---|---|---|
commission |
Decimal | ✅ | Commission rate per unit traded |
units_traded |
Decimal | ✅ | Units traded to apply commission |
minimum_commission |
Decimal | ✅ | Minimum commission amount |
FinancingDayOfWeek¶
Daily financing rate details for specific days.
🔗 OANDA Definition: FinancingDayOfWeek
🔗 Source: FinancingDayOfWeek
| Field | Type | Required | Description |
|---|---|---|---|
day_of_week |
DayOfWeek | ✅ | Day of the week (SUNDAY through SATURDAY) |
days_charged |
int | ✅ | Number of days of financing charged for this day |
InstrumentFinancing¶
Financing data for an instrument including long/short rates and daily schedule.
🔗 OANDA Definition: InstrumentFinancing
🔗 Source: InstrumentFinancing
| Field | Type | Required | Description |
|---|---|---|---|
long_rate |
Decimal | ✅ | Financing rate applied to long positions |
short_rate |
Decimal | ✅ | Financing rate applied to short positions |
financing_days_of_week |
list[FinancingDayOfWeek] | ✅ | Daily financing schedule for the week |
Tag¶
A tag associated with an entity for categorization.
🔗 OANDA Definition: Tag
🔗 Source: Tag
| Field | Type | Required | Description |
|---|---|---|---|
type |
str | ✅ | Type of the tag |
name |
str | ✅ | Name of the tag |
UnitsAvailableDetails¶
Units available for both long and short orders on an instrument.
🔗 OANDA Definition: UnitsAvailableDetails
🔗 Source: UnitsAvailableDetails
| Field | Type | Required | Description |
|---|---|---|---|
long |
UnitsAvailable | ✅ | Long position units availability |
short |
UnitsAvailable | ✅ | Short position units availability |
OrderBook¶
Order book depth data for an instrument showing bid/ask levels.
🔗 OANDA Definition: OrderBook
🔗 Source: OrderBook
| Field | Type | Required | Description |
|---|---|---|---|
instrument |
InstrumentName | ✅ | Instrument identifier |
time |
DateTime | ✅ | Time when order book data was captured |
price |
PriceValue | âž– | Reference price for the order book |
bucket_width |
PriceValue | âž– | Width of each price bucket |
buckets |
list[PriceBucket] | ✅ | Price buckets with bid/ask volume |
GuaranteedStopLossOrderEntryData¶
Details required by clients to add a Guaranteed Stop Loss Order for a specific instrument.
🔗 OANDA Definition: GuaranteedStopLossOrderEntryData
🔗 Source: GuaranteedStopLossOrderEntryData
| Field | Type | Required | Description |
|---|---|---|---|
minimum_distance |
Decimal | ✅ | Minimum distance from current price for GSL order |
premium |
Decimal | ✅ | Premium charged for guaranteed execution |
level_restriction |
GuaranteedStopLossOrderLevelRestriction | âž– | Level restrictions for this instrument |
GuaranteedStopLossOrderLevelRestriction¶
Volume and price range restrictions for guaranteed stop loss orders.
🔗 OANDA Definition: GuaranteedStopLossOrderLevelRestriction
🔗 Source: GuaranteedStopLossOrderLevelRestriction
| Field | Type | Required | Description |
|---|---|---|---|
volume |
Decimal | ✅ | Volume restriction level |
price_range |
Decimal | ✅ | Price range restriction |