Oikos JS Library - access Oikos smart contracts from browser and Node.js

npm install @oikos/oikos-js-bsc@0.2.68


OikosJs library

CircleCI npm version Discord Twitter Follow

The Oikos-JS Library provides a simple pre-packaged API to communicate with Oikos on BSC. You can use it to contribute to DeFi's growing synthetic asset ecosystem.

This is particularly useful for hackathon teams to quickly npm install oikos-js and start building in just a few minutes.

Under the hood, OikosJs uses ethers.js library and its concept of providers and transaction signers.

Install via npm

npm install oikos-js-bsc

Developer Docs


Example for getting the total oUSD stablecoin in circulation

const { OikosJs } = require('oikos-js-bsc');
const oksjs = new OikosJs(); //uses default ContractSettings - ethers.js default provider, mainnet
(async function() {
  const totalOUSD = await oksjs.oUSD.totalSupply();
  const totalOUSDSupply = oksjs.utils.formatEther(totalSUSD);
  console.log('oUSDTotalSupply', totalOUSDSupply);

Default settings don't use any signer. That means that constants can be viewed from the contract but executing a transaction will fail. To execute transactions, set up signer.

4 signers are included in the library - Metamask (compatible with Dapp browsers), Trezor, Ledger and PrivateKey. Custom ethers.js compatible signers can be used too.

Example using a metamask signer

const { OikosJs } = require('oikos-js-bsc');
const metaMaskSigner = new OikosJs.signers.Metamask();
const oksjs = new OikosJs({ signer: metaMaskSigner }); //uses Metamask signer and default infura.io provider on mainnet

Example of minting stablecoin(oUSD) with private key signer

const { OikosJs } = require('oikos-js-bsc');
//parameters: default provider, default networkId, private key as a string
const signer = new OikosJs.signers.PrivateKey(
const oksjs = new OikosJs({ signer });

async function run() {
  const totalSupply = await oksjs.Oikos.totalSupply();
  const oksTotalSupply = oksjs.utils.formatEther(totalSupply);
  console.log('oksTotalSupply', oksTotalSupply);

  //issue 100 synths (will throw if insufficient funds for gas)
  try {
    const txObj = await oksjs.Oikos.issueSynths(oksjs.util.parseEther('100')); //execute transaction (requires gas)
    console.log('transaction hash', txObj.hash);
  } catch (e) {


Live examples

  • Get total synth supply Get total supply
  • Get collateralized state image

Got any questions?

Join our dev community on Discord: Discord