Namby Pamby Magicians


    4.7.4 • Public • Published

    ledgers.js by

    A free and open-sourced ecosystem of widgets, a front-end library, and back-end services — to make addition of "logins" and "in-app-purchases" (IAP) to your app as banal as possible.


    npm version CircleCI

    This repository (git|npm) is the distribution of the ledgers.js library (API) in support of ledger-based authorization.

    It's a suite of tools to make the authorization workflows part of your application.

    Figure 1: Where ledgers.js fits in.

    The ledgers.js library sits between the login page and the ledgers it abstracts.

    The library interacts with in-browser wallets for signing (authentication)--if available.

    The library makes sums of ledger transaction available to the login page for authorization criteria checks. Topping up payments requires transacting with ledgers which is done via linked Web sites and available in-browser wallets.

    The business logic does not leverage ledgers.js--the library is intended for login pages not service code. The business logic code interacts directly with remuneration APIs--discussed below.

    More Information

    For more information, videos, write-ups, please visit

    For help, reach out on r/overhide.

    Getting a Taste

    You can see ledgers.js live as embedded in this live API playground learning tool.

    This playground is hosted by this repo: it's available in this repo in the ./play folder. You can run your own local instance with npm run play and by directing your browser at http://localhost:8080/play/index.html.

    The playground showcases all library APIs as available to be used against ledgers.js test networks.

    You can use the playground with your web3.js enabled browser wallet such as If testing with Ethereum, just ensure to use the Rinkeby testnet.

    You can also see ledgers.js embedded in one of these "demo" tools:

    Getting Started


    This ledgers.js library is client-side and abstracts ledgers (see figure above). Before using ledgers.js in your product, ensure to onboard with the ledgers.

    overhide-ledger (dollars)

    • register through live app for production
    • register through test app for development and testing

    Ethereum (ethers)

    • generate a PKI pair on mainnet for production
    • generate a PKI pair on Rinkeby testnet for development and testing

    Bitcoin (bitcoins)

    • generate a PKI pair on mainnet for production
    • generate a PKI pair on testnet for development and testing


    Why is it so big?

    We depend on web3.js which has bloat issues:

    As soon as that gets resolved, this distro will be smaller.

    The ledgers.js library 'dist' folder contains the distributable artifact.

    You'll likely want to import the library along with its dependencies (web3.js).

    Within your front-end projects; using npm simply: npm install ledgers.js --save-prod.

    The ledgers.js library exports the oh$ object--it also sets a global oh$ object on window.

    To bring in the oh$ object into your code using import:

    import oh$ from "ledgers.js";
    oh$.onWalletChange = ...
    Enabling with Token

    APIs abstracted by ledgers.js require a bearer-token. The token (above) is passed in to enable the rest of the library's functionality. oh$.enable(..) can be called every so often with a refreshed token.

    A token can be retrieved with a GET /token call (see

    To retrieve tokens please first register for your own API key at


    You can include ledgers.js via CDN:


    For a specific version, e.g. version 2.1.4:

    The library can be loaded straight into your HTML and accessed by its oh$ property in the globals:

    <script src="``"></script>
      oh$.addEventListener('onWalletChange', ...);

    Keep in mind ledgers.js is meant to run with a DOM present--in a browser (not Node.js).


    ledger.js (source)(API) is part of a larger envisioned ecosystem called overhide. It works in tandem with the overhide Remuneration API.

    The overhide remuneration API is meant to enable "ledger-based authorization" with fiat currencies and cryptos.

    The ledgers.js library (source)(API) is an integral partner to the overhide Remuneration API, providing utilities and abstractions for for the browser-centric authentication and payment portions; to enable ledger-based authorization later in the service-code or backend.

    The figure shows the overhide Remuneration API landscape and highlights ledger.js (source)(API) helping a Web app orchestrate a login from within a browser--the red outgoing arrows--as it interacts with the service code and APIs in the cloud.

    Figure 2: Shows where ledgers.js fits within the overhide Remuneration API landscape.

    Remuneration API

    The overhide remuneration API is an API of two HTTP methods exposed by various ledgers (blockchain and otherwise):

    • /get-transactions/{from-address}/{to-address}
    • /is-signature-valid

    These API methods are used by the ledgers.js library and explicitly called by the Service Code.

    Test Environment APIs

    For testing the library interacts with the Rinkeby Ethereum testnet and the overhide-ledger test environment.

    The respective API instances used are the following test network nodes:

    Use a Rinkeby faucet to get "test" Ether for playing around with the ethers portion of the library.

    Use Stripe's "test" credit cards to play around with dollar transactions in the library.

    Use a Bitcoin testnet faucet to get "test" bitcoins for playing around with the bitcoins imparter in the library. You'll need to use a wallet and — for best results — configure it to not use "change" addresses.

    Production Environment APIs

    To interact with the Ethereum mainnet, user your wallet.

    To interact with the production overhide-ledger, visit

    To interact with the production Bitcoin mainnet, use the Electrum wallet and configure it not to use "change" addresses (works best for ledger-based authorizations).

    For production instances of all APIs see:

    Additional Notes on APIs

    The overhide-ledger Swagger documentation discusses some additional HTML/js getter endpoints particular to overhide-ledger and not part of the generic remuneration API. The ledger.js (source)(API) leverages these additional endpoints when it calls on overhide-ledger functionality. This is similar to how ledger.js (source)(API) leverages the web3.js library when working with ether.

    build notes: see ./build.txt


    npm i ledgers.js


    DownloadsWeekly Downloads






    Unpacked Size

    1.28 MB

    Total Files


    Last publish


    • overhide