Non Polar Magnetism

    node-kraken-api
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.2 • Public • Published

    About

    node-kraken-api is a typed REST/WS Node.JS client for the Kraken cryptocurrency exchange.
    This is an unofficial API. Please refer to the official documentation for up-to-date information.

    REST API Docs: kraken.com/features/api
    WebSocket API Docs: docs.kraken.com/websockets

    Features

    • Fully typed REST and WS responses and options.
      • REST methods/comments are generated from the official OpenAPI specifications file.
      • WS methods/comments are sourced from the official WebSockets 1.8.3 documentation.
      • Note:
        • All named response properties are optional and nullable unless explicitly marked required in the documentation.
    • RetrieveExport (binary endpoint); see the example.
    • Full WS orderbook mirroring and checksum validation.
    CHANGELOG Synopsis Usage Code

    MIGRATION FROM 0.4.1:

    The entire project has been completely rewritten using TypeScript and many features have changed.

    If you're upgrading, please review the changes and upgrade guide below.

    Added

    • Complete WS 1.8.3 functionality
    • Typings
    • New REST methods

    Deprecated

    • Custom response parsing (Settings.parse, Settings.dataFormatter)
      • To ensure type consistency, it is best to leave parsing to the user.
      • Used only for the deprecated .call() function.
    • Method name settings (Settings.pubMethods, Settings.privMethods)
      • Previously, settings were used to differentiate between public and private methods rather than requiring the user to specify for each call.
      • Instead, named requests are provided to hard-code these differences.
      • Used only for the deprecated .call() function.
    • .call()
      • Replaced by .request() and the named REST methods.

    Removed

    • Ratelimiting (Settings.limiter and Settings.tier)
      • The aim of this API is to maximize clear and accurate communication with the server; ratelimiting makes assumptions about the client setup and should be left to the user.
    • REST retries (Settings.retryCt)
      • This was originally included due to the occasional nonce and timeout error.
        • To reduce this possibility, increase your API key nonce window and the .timeout setting.
    • REST syncing (Settings.syncIntervals)
      • With the introduction of the WebSocket connection, REST syncing is no longer required for many data sources.
        • For all other sources, simply use an asynchronous loop.
    • Server Settings (Settings.hostname, Settings.version)
      • These values should be constants.
    • OTP value setting (Settings.otp and .setOTP())
      • Replaced by Settings.genotp
    • Direct construction using module.exports()
      • Changed to class export for modern standards.

    Changed

    • Errors have changed to named classes. Please review the synopsis.

    Upgrade Guide

    1. Replace all calls to .call() with the corresponding named method or .request().
      • Make sure to view the expected response types; they have changed since 0.4.1.
    2. Replace all sync instances with an async loop that requests every few seconds.
      • If you are syncing one of the endpoints provided by WS, use that instead.
    3. Ensure that your REST calls are not being made too quickly.
      • Ratelimiting has been removed; you may encounter server errors if you were relying on the limiter.
      • See the rate limits documentation.
    4. Increase your api key nonce window if you're getting invalid nonce errors.
      • Calls may now be performed concurrently (global queueing is removed).
    5. Remove calls to .setOTP() and Settings.otp; provide .genotp in the settings.
    6. Review the error classes; if you were parsing errors you will need to update your catch statements.
      • Note: calls are no longer automatically retried retryCt times.
    7. If you're constructing using module.exports (e.g. const kraken = require('node-kraken-api')({...})), you will need to use the module.exports.Kraken class instead: import { Kraken } from "node-kraken-api"; const kraken = new Kraken({...});

    MIGRATION FROM 1.0.0:

    Minor changes to the Emitter class.

    Changed

    • Kraken.Emitter moved to its own package and improved; filters now pass on type assertion result to listeners.
      • This changed the signature for event filtering:
        • (...args: <type>[]) => boolean -> (args: [<type>, <type>, ...]) => args is [<subtype>, <subtype>, ...]

    Removed

    • Kraken.Emitter

    Synopsis

    Methods

    Properties

    Classes

    Usage

    Integration

    npm i --save node-kraken-api
    import { Kraken } from "node-kraken-api";

    Settings

    new Kraken({
      /** REST API key. */
      key?: string;
      /** REST API secret. */
      secret?: string;
      /** REST API OTP generator. */
      genotp?: () => string;
      /**
       * Nonce generator (the default is ms time with an incrementation guarantee).
       * Note: Some other APIs use a spoofed microsecond time. If you are using an
       *       API key used by one of those APIs then you will need to use a custom
       *       nonce generator (e.g. () => Date.now() * 1000). See _GENNONCE for the
       *       default generation logic.
       */
      gennonce?: () => number;
      /** Connection timeout (default 1000). */
      timeout?: number;
    });

    REST API

    Public

    const kraken = new Kraken();
    
    const { unixtime } = await kraken.time();
    const { XXBT }     = await kraken.assets();
    const ticker       = await kraken.ticker({ pair: "XXBTZUSD" })

    Private

    const kraken = new Kraken({ key: "...", secret: "..." });
    
    const { txid } = await kraken.addOrder({
      pair:      "XXBTZUSD",
      type:      "buy",
      ordertype: "limit",
      price:     "65432.1",
      volume:    "1",
    });

    If your key requires an OTP, provide a generator:

    const kraken = new Kraken({ key: "...", secret: "...", genotp: () => "..." });

    RetrieveExport is the only method that promises a buffer:

    const kraken = new Kraken({ key: "...", secret: "..." });
    
    const buf = await kraken.retrieveExport({ id: "FOOB" })
    fs.writeFileSync("report.zip", buf)

    WebSockets

    • All WebSocket subscriptions and requests are located within .ws.
      • .ws.pub and .ws.priv provides ping, heartbeat, systemStatus, and general error monitoring.
    • Automatically connects to the socket when server data is requested.
      • See Kraken.WS.Connection.open() and Kraken.WS.Connection.close() for manual connection management.
    • Subscription methods return a Kraken.Subscriber object that manages subscriptions for a given name and options.

    Public

    const kraken = new Kraken();
    
    const trade = await kraken.ws.trade()
      .on('update', (update, pair)  => console.log(update, pair))
      .on('status', (status)        => console.log(status))
      .on('error',  (error, pair)   => console.log(error, pair))
      // .subscribe() never rejects! rely on the 'error' and 'status' events
      .subscribe('XBT/USD')
    
    const book100 = await kraken.ws.book({depth: 100})
      // live book construction from "snapshot", "ask", and "bid" events.
      .on("mirror", (mirror, pair) => console.log(mirror, pair))
      .on("error",  (error,  pair) => console.log(error,  pair))
      // resubscribes if there is a checksum validation issue (emits statuses).
      .on("status", (status)       => console.log(status)
      .subscribe("XBT/USD", "ETH/USD"); // subscribe to multiple pairs at once
    
    // unsubscribe from one or more subscriptions
    // .unsubscribe() never rejects! rely on the 'error' and 'status' events
    await book100.unsubscribe('XBT/ETH');

    Private

    const kraken = new Kraken({ key: "...", secret: "..." });
    
    const { token } = await kraken.getWebSocketsToken();
    
    const orders = kraken.ws.openOrders({ token: token! })
      .on("update", (update, sequence) => console.log(update, sequence))
      .subscribe();
    
    await orders.unsubscribe();
    
    // The token does not expire while the subscription is active, but if you wish
    // to resubscribe after unsubscribing you may need to call .ws.openOrders() again.

    Testing

    Testing is performed by @jpcx/testts.

    To run tests:

    • Save an auth.json file with your key and secret: { key: string, secret: string }
      • Please ensure that this key has readonly permissions.
    • Run npm test in the main directory.

    Development

    Contribution is welcome! Given the amount of typings in this project, there may be discrepancies so please raise an issue or create a pull request.

    Also, I am US-based and can't access the futures API; if you have access and want to contribute let me know!

    Author

    Justin Collier - jpcx

    msg: node-kraken-api
    btc: bc1q3asl6wjnmarx4r9qcc04gkcld9q2qaqk42dvh6
    sig: J4p7GsyX/2wQLk32Zfi/AmubUzGM66I6ah+mEn8Vpqf4EpfPuWYGaLcu2J8tdcsRGMAsmavbz/SJnw7yr3c0Duw=
    

    Inspired by npm-kraken-api (nothingisdead).

    License

    This project is licensed under the MIT License - see the LICENSE file for details

    Install

    npm i node-kraken-api

    DownloadsWeekly Downloads

    544

    Version

    2.2.2

    License

    MIT

    Unpacked Size

    117 kB

    Total Files

    5

    Last publish

    Collaborators

    • jpcx