# WAPI Client

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 trakc 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.

[Documentation](https://docs.wapi.dev)

## 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.