1.1.7 • Public • Published

    Simple FxTrade

    A node js wrapper for the Oanda Rest v20 api to make things really simple.

    Build Status Coverage Status npm version GitHub license


    This package is a wrapper around the Oanda Rest-v20 api. All request parameters, payloads or response structures are documented there so you won't find that information here.

    The purpose of this package is to simplify the url constructions and expose the endpoints in a nice way for any Nodejs based projects. The package should also work as described in browsers via fx global or by require / import.

    Here is an example:

    const fx = require('simple-fxtrade');
    // Just an example, you need an async function to use async / await
    const run = async () => {
      // Configure api key, you can set env: OANDA_API_KEY instead and remove this call
          apiKey: 'your-api-key-per-oanda-docs',
      // Get accounts for authorized user (using OANDA_API_KEY env var)
      const {accounts: [{id}]} = await fx.accounts()
      // Set the id context for all future api calls
      // Get the instruments for the account
      const {instruments} = await fx.instruments();
      console.log(instruments); // [...] logs many instruments
    // Call the above function. Included to reduce any possible confusion


    Install via npm with the following

    npm i --save simple-fxtrade



    To change certain aspects of the api wrapper, you can use the configure function. For example you may want to set the apiKey.

    // Use configure to change the default values which are shown below
      apiKey: 'dsadsds',  // Defaults to OANDA_API_KEY environment variable
      live: false,        // Set to true to use the live api instead of practice
      version: 'v3',      // Probably never need to change this
      accountId: '23243', // Set this if you know the accountId up front
      dateTimeFormat: 'RFC3339', // Per oanda documentation
      fullResponse : false // * See notes
    // You needn't set all values, a more realistic example may be like
    fx.configure({ live: true, accountId: '111-002-111-2' });
    • apiKey - Default: env variable OANDA_API_KEY. Sets the Authorization header key. Best practice would be to use some config or env management package to set this and never pass the value. But you can if you want.

    • live - Default: false. This affects the endpoint url. If set to true the host is, when false its

    • accountId - Default: not set. If you know the accountId you could set it here. Most endpoints need the accountId set

    • fullResponse - Default: false. When this not set to true, you get a short form response for all requests like the following:

        status: 200,
        headers: {}, // Some headers
        candles: []  // The relevant payload that you would expect

      if the fullResponse is set to true then you get a full axios response.

    If you are messing around on a demo account, with the OANDA_API_KEY set, then you may never need to use configure. Instead you can just use setAccount, in fact for most of the endpoints you must set the account before hand. Heres what it might look like if you maybe know the id.

    // Usually get the accounts and the id, but then set it
    // All defaults are already configured to work

    Api Endpoints

    The following api endpoints are implemented. In most cases the request parameters are the same and response is a direct pass through. Each heading matches with the official documentation headings.

    Note: ALL api examples assume that you have setAccount(id) as there are only 3 or so routes that dont need it set


    Only the accounts() function can be used without setting the accountId

    // GET /accounts
    const {accounts} = await fx.accounts();
    // GET /accounts/:id
    const {account} = await fx.accounts({ id });
    // PATCH /accounts/:id/configuration
    await fx('patch').accounts({ id, alias: 'Default' });
    // GET /accounts/:accountId/summary - Notice the accountId is used from the config
    const {account} = await fx.summary();
    // GET /accounts/:accountId/instruments
    const {instruments} = await fx.instruments();
    // GET /accounts/:id/changes
    const {changes} = await fx.changes({ sinceTransactionID: 20 });


    The only relevant function here is candles() it doesn't require the accountId.

    // GET /instrument/:id/candles
    const {candles, instrument} = await fx.candles({ id: 'AUD_USD' });


    All of the functions for orders require the accountId to be set.

    // GET /accounts/:accountId/orders
    const {orders} = await fx.orders();
    // GET /accounts/:accountId/orders/:id
    const {orders} = await fx.orders({ id });
    // POST /accounts/:accountId/orders
    await fx.orders.create({
      order: {
        units: 1,
        instrument: 'AUD_USD',,
        timeInForce: 'FOK'
        type: 'MARKET',
        positionFill: 'DEFAULT',
        tradeId: 6368
    // PUT /accounts/:accountId/orders/:id
    await fx.orders.replace({ id, order: ... });  // See oanda docs for payload examples
    // PUT /accounts/:accountId/orders/:id/cancel
    await fx.orders.cancel({ id });
    // PUT /accounts/:accountId/orders/:id/clientExtensions
    await fx.orders.clientExtensions({ id, clientExtensions });


    All of the functions require the accountId to be set. See oanda docs for payload examples. They are just provided as an object parameter.

    // GET /accounts/:accountId/trades
    const {trades} = await fx.trades({ count: 10, instrument: 'AUD_USD' });
    // GET /accounts/:accountId/trades/:id
    const {trade} = await fx.trades({ id });
    // PUT /accounts/:accountId/trades/:id/close
    await fx.trades.close({ id })
    // PUT /accounts/:accountId/trades/:id/clientExtensions
    await fx.trades.clientExtensions({ id, clientExtensions });
    // PUT /accounts/:accountId/trades/:id/orders
    await fx.trades.orders({ id, takeProfit }); // etc...


    Again all functions need the accountId to have been set before hand.

    // GET /accounts/:accountId/positions
    const {positions} = await fx.positions();
    // GET /accounts/:accountId/positions/:id <- instrument id
    const {position} = await fx.positions({ id });
    // PUT /accounts/:accountId/positions/:id/close
    await fx.positions.close({ id });


    Set the accountId first

    // GET /accounts/:accountId/transactions
    const {transactions} = await fx.transactions()
    // GET /accounts/:accountId/transactions/:id
    const {transactions} = await fx.transactions({ id })


    // GET /accounts/:accountId/pricing?instruments=AUD_USD
    const {prices} = await fx.pricing({ instruments: 'AUD_USD' })

    Stream Endpoints

    Good news, both the pricing and the transactions streams are implemented. Here is an example of using the pricing stream.

    // GET /accounts/:accountId/pricing/stream?instruments=AUD_USD
    const stream = await{ instruments: 'AUD_USD' });
    // Handle some data
    stream.on('data', data => {
      console.log(data.type); // PRICE or HEARTBEAT
    // Sometime later when done with the stream


    npm i simple-fxtrade

    DownloadsWeekly Downloads






    Unpacked Size

    152 kB

    Total Files


    Last publish


    • lessonteacher