Home

Table of contents

• Deriv API
  • API instantiation
    • Examples
      • Passing a connection
      • With endpoint and appId
  • API Methods
    • ticks and ticksHistory
    • candles and candlesHistory
    • contract
    • underlying
    • account
    • assets
• Usage examples
  • Short examples
    • Authenticate to an account using token
    • Get all the assets info
    • Ask for an specific underlying
    • Get a contract group by its name
    • Get supported durations for a contract group
    • Create a datepicker for forward starting sessions
  • Examples with more details
    • An account object
    • Create an underlying and get all the ticksHistory for showing on a chart
    • Create a contract if trading is allowed for an underlying
• UML diagram of classes

Deriv API

API instantiation

You can either create an instance of WebSocket and pass it as connection or pass the endpoint and appId to the constructor to create the connection for you.

If you pass the connection it's up to you to reconnect in case the connection drops (cause API doesn't know how to create the same connection).

Examples

Passing a connection

const connection = new WebSocket('wss://frontend.binaryws.com/websockets/v3?l=EN&app_id=1234');
const api = new DerivAPI({ connection })

With endpoint and appId

const api = new DerivAPI({ endpoint: 'frontend.binaryws.com', lang: 'EN', appId: 1234 })

API Methods

All API methods are asynchronous, meaning that they either return a Promise or an Observable depending on the usage. But you should not expect them to return the requested data immediately.

ticks and ticksHistory

const history = await api.ticksHistory('R_100'); // Get a list of ticks

// Observable
api.ticks('R_100').subscribe(tick => console.log('New tick: %s', tick.bid.pipSized));

// With callback
api.ticks('R_100', tick => console.log('New tick: %s', tick.bid.pipSized));

candles and candlesHistory

const history = await api.candlesHistory('R_100'); // Get a list of 1min candles

api.candles('R_100').subscribe(candle => console.log('Candle close: %s', candle.close.pipSized));

api.candles('R_100', candle => { console.log('Candle close: %s', candle.close.pipSized) })

contract

const contract = await api.contract({
    contractType: 'call',
    symbol: 'R_100',
    duration: 1,
    durationUnit: 't',
    ...contractOptions
});

underlying

const underlying = await api.underlying('R_100');

// You can also call ticks and candles related calls on an underlying instance
const ticksHistory = await underlying.ticksHistory();

// You can create a contract from an underlying
const contract = await underlying.contract(contractOptions);

account

const account = await api.account('AccountToken');
const balance = account.balance;

// You can create a contract from an account instance
const contract = await account.contract(contractOptions);

assets

const assets = await api.assets();
if (!assets.underlyings.R_100.isTradingSuspended) {
    const contract = api.contract(contractOptions);
    // The rest
}

Usage examples

Short examples

const api = new DerivAPI(/* options here */);

Authenticate to an account using token

const accout = await api.account('YourToken');

Get all the assets info

const assets = await api.assets();

assets.openMarkets.forEach(market => {
    console.log('Market %s is open', market.name.full);
});

Ask for an specific underlying

const underlying = await api.underlying('R_100');

Get a contract group by its name

const { callput } = underlying.contractGroups;

Get supported durations for a contract group

const { min: duration, unit: durationUnit } = callput.duration.tick;

Create a datepicker for forward starting sessions

const { forwardSessions } = callput;

const [ firstSession ] = forwardSessions;

const $el = <input type="date" value={await api.time} min={firstSession.open} max={firstSession.close}>

Examples with more details

An account object

const account = await api.account('YourToken');

// Loop through all associated accounts and print whether they're virtual
account.user.accounts.forEach(u => {
    console.log('Is %s virtual? %s', u.loginid, u.isVirtual);
});

const balance = account.balance;

console.log('%s has %s %s', account.loginid, balance.currency, balance.format);

balance.onUpdate(balance => {
    console.log('%s has now %s %s', account.loginid, balance.currency, balance.format);
});

Create an underlying and get all the ticksHistory for showing on a chart

const underlying = await api.underlying('R_100');

const history = await underlying.ticksHistory(tick => {
    // Update chart info with the new ticks
    chart.show(tick);
});

// Initialize the chart with the list of ticks available
chart.init(history);

Create a contract if trading is allowed for an underlying

const underlying = api.underlying('R_100');

if (underlying.isTradingSuspended) {
    console.log('Trading is suspended for %s', underlying.name.full);
} else {
    // Get the contract group for Rise/Fall
    const callput = underlying.contractGroups.callput;

    // Get the duration allowed for tick contracts
    const { min: duration, unit: durationUnit } = callput.duration.tick;

    const [contractType] = callput.contractTypes;

    const contract = api.contract({
        symbol: underlying.symbol,
        contractType,
        duration,
        durationUnit,
    });
}

UML diagram of classes

Each font face indicates a different type of field:

Bold: a link to another class object(s)

Italic: accessors (the property is calculated from other properties)

endingWithParenthesis(): A method name, usually doing some action on the object

normalProperties: The camel case name of a property stored on the object