Market Data Models¶
OANDA Reference: Pricing Data Definitions | Instrument Data Definitions
Models for market pricing, instrument specifications, and candlestick (OHLC) data.
Field names are Python attributes. Required means required at model construction;
None in the type indicates a nullable value. Defaults and local validation do not
establish server eligibility. See reading model tables.
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 | str | None | âž– | Trading instrument identifier |
time |
DateTime | None | âž– | Timestamp when price was created |
status |
PriceStatus | None | âž– | Price status (deprecated but may still be present) |
tradeable |
bool | None | âž– | 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 | None | âž– | Currency conversion factors for quote currency calculations |
units_available |
UnitsAvailable | None | âž– | 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 quote-currency amounts |
negative_units |
Decimal | ✅ | Conversion factor for negative quote-currency amounts |
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 |
UnitsAvailableDetails | ✅ | Long and short availability under default position-fill behavior |
reduce_first |
UnitsAvailableDetails | ✅ | Long and short availability for reduce-first fills |
reduce_only |
UnitsAvailableDetails | ✅ | Long and short availability for reduce-only fills |
open_only |
UnitsAvailableDetails | ✅ | Long and short availability for open-only fills |
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 | None | âž– | Bid-based OHLC data for the time period |
ask |
CandlestickData | None | âž– | Ask-based OHLC data for the time period |
mid |
CandlestickData | None | âž– | Mid-price OHLC data ((bid+ask)/2) for the time period |
volume |
int | ✅ | Number of prices created during the interval, not traded units |
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 | str | ✅ | 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 | None | âž– | Minimum distance for guaranteed stop loss orders |
commission |
InstrumentCommission | None | âž– | Commission structure for this instrument |
guaranteed_stop_loss_order_mode |
GuaranteedStopLossOrderModeForInstrument | None | âž– | Guaranteed stop loss availability (DISABLED, ALLOWED, REQUIRED) |
guaranteed_stop_loss_order_execution_premium |
Decimal | None | âž– | Premium charged for guaranteed stop loss execution |
guaranteed_stop_loss_order_level_restriction |
GuaranteedStopLossOrderLevelRestriction | None | âž– | Restrictions on guaranteed stop loss levels |
financing |
InstrumentFinancing | None | âž– | 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 |
Decimal | ✅ | Long position units availability |
short |
Decimal | ✅ | Short position units availability |
OrderBookBucket¶
Order book price partition with percentages of open orders on each side.
🔗 OANDA Definition: OrderBookBucket
🔗 Source: OrderBookBucket
| Field | Type | Required | Description |
|---|---|---|---|
price |
PriceValue | ✅ | Lowest price (inclusive) covered by this bucket |
long_count_percent |
Decimal | ✅ | Percentage of total open orders in the bucket that are long |
short_count_percent |
Decimal | ✅ | Percentage of total open orders in the bucket that are short |
OrderBook¶
Snapshot of open orders for an instrument, partitioned into price buckets.
🔗 OANDA Definition: OrderBook
🔗 Source: OrderBook
| Field | Type | Required | Description |
|---|---|---|---|
instrument |
InstrumentName | str | ✅ | Instrument identifier |
time |
DateTime | ✅ | Time when order book snapshot was created |
unix_time |
DateTime | None | âž– | Snapshot time as a Unix timestamp |
price |
PriceValue | None | âž– | Price (midpoint) at the time of the snapshot |
bucket_width |
PriceValue | None | âž– | Width of each price bucket |
buckets |
list[OrderBookBucket] | âž– | Partitioned order book buckets; only buckets with a non-zero count are returned |
PositionBookBucket¶
Position book price partition with percentages of open positions on each side.
🔗 OANDA Definition: PositionBookBucket
🔗 Source: PositionBookBucket
| Field | Type | Required | Description |
|---|---|---|---|
price |
PriceValue | ✅ | Lowest price (inclusive) covered by this bucket |
long_count_percent |
Decimal | ✅ | Percentage of total open positions in the bucket that are long |
short_count_percent |
Decimal | ✅ | Percentage of total open positions in the bucket that are short |
PositionBook¶
Snapshot of open positions for an instrument, partitioned into price buckets.
🔗 OANDA Definition: PositionBook
🔗 Source: PositionBook
| Field | Type | Required | Description |
|---|---|---|---|
instrument |
InstrumentName | str | ✅ | Instrument identifier |
time |
DateTime | ✅ | Time when position book snapshot was created |
unix_time |
DateTime | None | âž– | Snapshot time as a Unix timestamp |
price |
PriceValue | None | âž– | Price (midpoint) at the time of the snapshot |
bucket_width |
PriceValue | None | âž– | Width of each price bucket |
buckets |
list[PositionBookBucket] | âž– | Partitioned position book buckets; only buckets with a non-zero count are returned |
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 | None | âž– | 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 |