Core classes for API interaction including the main Context class for managing connections and making requests, and the Response class for handling HTTP responses.
The Context class is the main entry point for interacting with the OANDA v20 API. It manages HTTP/HTTPS communication and provides access to all API endpoints through EntitySpec instances.
/**
* Creates a new Context instance for API communication
* @param hostname - API server hostname (e.g., 'api-fxpractice.oanda.com')
* @param port - API server port (typically 443 for HTTPS)
* @param ssl - Boolean indicating whether to use HTTPS (true) or HTTP (false)
* @param application - Optional application identifier string for user agent
*/
class Context {
constructor(hostname, port, ssl, application);
/**
* Sets the API authentication token
* @param token - API authentication token from OANDA
*/
setToken(token);
/**
* Makes an HTTP request to the API
* @param method - HTTP method (GET, POST, PUT, PATCH, DELETE)
* @param path - API endpoint path
* @param body - Request body object
* @param streamChunkHandler - Optional handler for streaming responses
* @param responseHandler - Callback receiving Response object
*/
request(method, path, body, streamChunkHandler, responseHandler);
// Properties
username: string;
hostname: string;
port: number;
headers: object;
token: string;
http: object; // HTTP or HTTPS module instance
// EntitySpec instances for each API area
account: AccountEntitySpec;
order: OrderEntitySpec;
trade: TradeEntitySpec;
position: PositionEntitySpec;
pricing: PricingEntitySpec;
transaction: TransactionEntitySpec;
instrument: InstrumentEntitySpec;
user: UserEntitySpec;
primitives: PrimitivesEntitySpec;
pricing_common: PricingCommonEntitySpec;
site: SiteEntitySpec;
}Usage Example:
const { Context } = require('@oanda/v20/context');
// Create context for practice environment
const ctx = new Context(
'api-fxpractice.oanda.com', // hostname
443, // port
true, // use HTTPS
'MyTradingBot v1.0' // application identifier
);
// Set authentication token
ctx.setToken('YOUR_API_TOKEN');
// All API operations are now available via ctx properties
// Examples:
// ctx.account.list(responseHandler)
// ctx.order.create(accountID, params, responseHandler)
// ctx.pricing.stream(accountID, params, streamHandler, responseHandler)The Response class wraps HTTP responses from the OANDA API and provides convenient status checking methods.
/**
* Represents an HTTP response from the OANDA API
* @param method - HTTP method used
* @param path - Request path
* @param statusCode - HTTP status code
* @param statusMessage - HTTP status message
* @param contentType - Response content type
* @param rawBody - Raw response body string
*/
class Response {
constructor(method, path, statusCode, statusMessage, contentType, rawBody);
/**
* Returns true if response status code is 2xx (success)
*/
isSuccess();
/**
* Returns true if response status code is 3xx (redirection)
*/
isRedirection();
/**
* Returns true if response status code is 4xx (client error)
*/
isClientError();
/**
* Returns true if response status code is 5xx (server error)
*/
isServerError();
/**
* Returns true if response is either client error or server error
*/
isError();
// Properties
method: string; // HTTP method
path: string; // Request path
statusCode: string; // HTTP status code (as string)
statusMessage: string; // HTTP status message
contentType: string; // Response content type
rawBody: string; // Raw response body
body: object | null; // Parsed response body (null initially, populated by EntitySpec)
}Usage Example:
ctx.account.get('YOUR_ACCOUNT_ID', response => {
// Check response status
if (response.isSuccess()) {
// Parse successful response
const account = response.body.account;
console.log('Account balance:', account.balance);
console.log('Unrealized P/L:', account.unrealizedPL);
} else if (response.isClientError()) {
console.error('Client error:', response.statusCode, response.statusMessage);
console.error('Error details:', response.rawBody);
} else if (response.isServerError()) {
console.error('Server error:', response.statusCode, response.statusMessage);
}
});All data model classes in the library extend the Definition base class, which provides common serialization and formatting methods.
/**
* Base class for all definition/model classes
*/
class Definition {
/**
* Returns JSON representation excluding internal properties
* @param key - Optional key parameter (standard toJSON signature)
*/
toJSON(key);
/**
* Returns formatted name string with property value substitution
*/
name();
/**
* Returns formatted summary string with property value substitution
*/
summary();
/**
* Returns combined name and summary as title
*/
title();
/**
* Returns detailed string representation with all properties
*/
toString();
/**
* Returns array of Field objects for all defined properties
*/
fields();
// Internal properties (not included in JSON serialization)
_summaryFormat: string;
_nameFormat: string;
_properties: Property[];
}Supporting classes for property metadata and field values.
/**
* Represents a property definition
* @param name - Property name
* @param displayName - Display name for UI
* @param description - Property description
* @param typeClass - Type classification (primitive, object, array_object, array_primitive)
* @param typeName - Type name string
*/
class Property {
constructor(name, displayName, description, typeClass, typeName);
name: string;
displayName: string;
description: string;
typeClass: string;
typeName: string;
}
/**
* Represents a property with an assigned value
* @param property - Property definition
* @param value - Property value
*/
class Field extends Property {
constructor(property, value);
value: any;
}Usage Example:
// All definition objects have these methods
const account = response.body.account;
// Get JSON representation
const json = account.toJSON();
// Get formatted strings
console.log(account.name()); // Formatted name
console.log(account.summary()); // Formatted summary
console.log(account.title()); // Combined name and summary
console.log(account.toString()); // Full string representation
// Get all fields with values
const fields = account.fields();
fields.forEach(field => {
console.log(`${field.displayName}: ${field.value}`);
});