Introduction

WalletAPI is an implementation for accounting systems to keep track of account balances and allow various complex transactions between them.

WAPI aims to solve many complex and annoying problems when trying to keep track of user balances do transactions in a reliable and performant manner.

WAPI Client is a library allowing to connect to WAPI Server over WebSockets and simplifies the adoption of WAPI into a project by providing simplified interfaces to various functionality.

Core Entities

Token

A counter of value that can be transferred between Wallet entities. Usually some form of currency.

Wallet

Entity which is able to hold and transfer tokens within the system. Is usually in one-to-one relation with some entity in Users system.

Balance

Entity describing the relationship between a wallet and token. Balances usually can't be negative for regular wallets nor can they be positive for Token wallets.

Transfer

An entity describing transfer of tokens from one wallet to another. The transfer of value is always positive and results an amount of Token being deducted from one Wallet and added to another Wallet.

Transfer Group

An entity grouping transfers together and allowing them to be treated as a single entity. Immitating a Transaction with long lifetime you can set up a complex pending TransferGroup and then complete or cancel it with a single transaction.

Core concepts

0-Sum system

All Balances within WAPI will always sum to 0. It means no value is ever created within WAPI nor will it leave it is only redistributed between wallets.

Serial history

Transfers can only ever be appended to the list. Inserting transfers into random locations in the history is not permitted thus any new transfer must be the latest transfer within the system.

Immutability

Most entities have only a limited set of properties that can be updated. Most things are immutable. For customization and integration to Users system metadata JSON fields are provided which to hold customer specific data.

Getting started

With WAPI, you can use either websocket or HTTPS - specified using the client parameter. Default is 'ws'

Using websockets to connect to WAPI:

basic

const client = WAPI.create({
  client: 'ws',
  connection: {
    host: 'https://myhost',
    apikey: 'apikey',
    apisecret: 'myapisecret',
  },
});

with options

 const client = WAPI.create({
   client: 'ws',
   connection: {
     host: 'https://myhost',
     apikey: 'apikey',
     apisecret: 'myapisecret',
   },
   config: {
     hooks: {
       // will fire after initial connection has been made
       connected() {
         console.log('connected');
       },
       // will fire if the connection drops
       disconnected() {
         console.log('disconnected');
       },
       // will fire before attempting to reconnect
       // if this function returns false it will not reconnect
       reconnect() {
         console.log('reconnect attempt');
         // return false; from this hook to prevent reconnecting
       },
       // will fire if there is a problem with reconnecting
       reconnectError(err) {
         console.error(err);
       }
       // will fire before each message is sent to server
       // if this message returns false then the message is not sent
       preflight(msg) => {
         console.log('sending msg', msg);
       },
       // will fire when a message is received from the server
       message(msg) => {
         console.log('got msg', msg);
       },
     },
     // default token to be used in methods that require a token
     // allows you to skip specifying the token each time if you only care about one token
     token: 'EUR',
     // how long to wait on initial connection before throwing an error
     // default is to wait underlying network layer timeout
     connectingTimeout: 60000;
     // how long to wait on reconnect attempts before erroring
     // default is to wait underlying network layer timeout
     reconnectingTimeout: 60000;
     // how long to wait for server ACK response on sending a command
     // NB! erroring on this timeout does not mean the command is not executed
     // as the command might have gotten through, but return ACK did not
     sendingTimeout: 60000;
   }
 });

Setting environment variable WAPI_DEBUG=true will enable client side debug logging.

Healthcheck

There are two different healthcheck endpoints for WAPI instances - API healthcheck and DB healthcheck.

You can check that the Sandbox API is healthy by making a GET request to https://client.node.wapi.dev/healthcheck

To check the Live API make a GET request to https://client.stable.wapi.dev/healthcheck

In order to check the health of your database use the healthcheck method from the API.