DeFi SDK Makes Money Lego Work

starsStars 346
forksForks 86
watchersWatchers 346
current-versionCurrent version v2.1.0
total-releasesTotal releases 7
open_issues_countOpen issues 23
dateFirst release 2020-03-23
dateLatest release 2020-04-23
updateLast update 2020-12-23

DeFi SDK is an open-source system of smart contracts designed for precise DeFi portfolio accounting. To put it simply, DeFi SDK is the on-chain balanceOf for DeFi protocols.

If you have any questions about DeFi SDK, feel free to reach out to us on our Discord server.


What’s next for DeFi SDK

Table of Contents


Find more examples of defi-sdk usage here (web3js, ethers.js).

Fetch Compound debt and collateral

As of now, to get all cTokens along with a user's debt on Compound you need to perform over 10 calls to the Ethereum node to different contracts or rely on a centralized API. With DeFi SDK, you can call

getProtocolBalances('0xdead...beef', ['Compound'])

on the api.zerion.eth smart contract and get all borrowed and supplied tokens

  metadata: {
    name: 'Compound',
    description: 'Decentralized Lending & Borrowing Protocol',
    websiteURL: '',
    iconURL: '',
    version: '0'
  adapterBalances: [{
    metadata: {
      adapterAddress: '0x90F0Ed76cfCf75Ccab31A9b4E51782F230aA0747',
      adapterType: 'Asset'
    balances: [{
      base: {
        metadata: {
          token: '0x6C8c6b02E7b2BE14d4fA6022Dfd6d75921D90E4E',
          name: 'Compound Basic Attention Token',
          symbol: 'cBAT',
          decimals: '8'
        amount: '314159265'
      underlying: [{
        metadata: {
          token: '0x0D8775F648430679A709E98d2b0Cb6250d2887EF',
          name: 'Basic Attention Token',
          symbol: 'BAT',
          decimals: '18'
        amount: '6626070040000000000'
      metadata: {
        adapterAddress: '0xD0646777520Aff625F976a8D81b95B5B42cDa1B9',
        adapterType: 'Debt'
      balances: [{
        base: {
          metadata: {
            token: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
            name: 'Dai Stablecoin',
            symbol: 'DAI',
            decimals: '18'
          amount: '1971081500000000000'
        underlying: []

Make sense of tokens like UNI-V1 ETH-cDAI

Sometimes, a DeFi token contains several other tokens, and to calculate their price, you need to know their underlying assets. For example, a Uniswap V1 cDAI pool consists of ETH and cDAI. cDAI, in turn, has DAI as an underlying token. With DeFi SDK you can call

// Uniswap V1 cDAI pool
getFinalFullTokenBalance("Uniswap V1 pool token", 0x34E89740adF97C3A9D3f63Cc2cE4a914382c230b)

and fetch the decomposition of UNI-token into ERC20 tokens, like ETH and DAI

0.98 ETH
215.6 DAI

Get account balances across all supported DeFi protocols

In case you want to get account balances across all supported DeFi protocols, you can call

// bankless.zerion.eth portfolio 

and obtain all balances for a given account. The response from the smart-contract will contain information about each of the protocols

100 DAI // collateral on Compound
0.1 ETH // debt on Compound
100 USDC // locked in PoolTogether
213 TUSD + 201 USDC + 82 USDT + 11 DAI // Curve Y pool

Get account balances across DeFi protocols that uses liquidity pools

For the protocols that uses a lot of liquidity pools (Bancor, Balancer, Uniswap) balances are not available by default in getBalances() function. Balances for such protocols must be fetched by getAdapterBalance() function with a list of pools passed as a function parameter. If you call

    0x42b9dF65B219B3dD36FF330A4dD8f327A6Ada990, // account address
    0x581Ae5AF7afa6f8171Bbf40d1981779F168A9523, // balancer adapter address
        0x987D7Cc04652710b74Fff380403f5c02f82e290a] // balancer pools addresses 

you will obtain Balancer balances for given pools. The response from the smart-contract will contain information about each of the pools

1.3 ETH + 552.4 DAI // 30% WETH + 70% DAI pool
4.2 MKR + 2.5 WETH // 75% MKR + 25% WETH pool

DeFi SDK Architecture

  • ProtocolAdapter is a special contract for every protocol. Its main purpose is to wrap all the protocol interactions. There are different types of protocol adapters: "Asset" adapter returns the amount of the account's tokens held on the protocol and the "Debt" adapter returns the amount of the account's debt to the protocol. Some protocols do not use "simple" ERC20 tokens but instead have complex derivatives, for example the Compound protocol has CTokens. The ProtocolAdapter contract also provides information about the type of tokens used within it.
  • TokenAdapter is a contract for every derivative token type (e.g cTokens, aTokens, yTokens, etc.) Its main purpose is to provide ERC20-style token metadata as well as information about the underlying ERC20 tokens (like DAI for cDAI). Namely, it provides addresses, types and rates of underlying tokens.
  • AdapterRegistry is a contract that a) maintains a list of ProtocolAdapters and TokenAdapters and b) is called to fetch user balances.

More detailed documentation about contracts can be found in AdapterRegistry documentation.


AdapterRegistry contract's mainnet address is 0x06FE76B2f432fdfEcAEf1a7d4f6C3d41B5861672. Its source code is verified on etherscan.

All the deployed contracts' addresses are available here.

Supported Protocols

Protocol Name Description Protocol Adapters Token Adapters
Aave Decentralized lending & borrowing protocol. Aave market. Debt adapter
Aave β€’ Uniswap Market Decentralized lending & borrowing protocol. Uniswap market. Debt adapter
Ampleforth An adaptive money built on sound economics. Asset adapter β€”
Aragon ANT staking rewards. Staking adapter β€”
Balancer Non-custodial portfolio manager, liquidity provider, and price sensor. Asset adapter supports all Balancer pools
Bancor Automated liquidity protocol. Asset adapter supports Bancor pools starting from version 11
Compound Decentralized lending & borrowing protocol. Governance adapter
C.R.E.A.M. A lending platform based on Compound Finance and exchange platform based on Balancer Labs. Staking adapter β€”
Curve Exchange liquidity pool for stablecoin trading. Vesting adapter
DDEX β€’ Lending Decentralized lending and borrowing Asset adapter β€”
DDEX β€’ Margin Decentralized margin trading Debt adapter β€”
DDEX β€’ Spot Decentralized trading Asset adapter β€”
DeFi Money Market Crypto through revenue-producing real world assets. Asset adapter
DODO Your on-chain liquidity provider. Staking adapter
dYdX Decentralized trading platform. All 4 markets (WETH, SAI, USDC, DAI) are supported. Debt adapter β€”
Idle Yield aggregator for lending platforms. Asset adapter (v2/v3) Yield aggregator for lending platforms. Protocol adapter is duplicated for v2 and v3 versions of protocol. Asset adapter
Harvest Your hard work is about to become easier with Harvest. Staking adapter β€”
KeeperDAO An on-chain liquidity underwriter for DeFi. Asset adapter
KIMCHI Farm KIMCHI by staking LP tokens. Staking adapter β€”
KyberDAO Platform that allows KNC token holders to participate in governance. Asset adapter β€”
Chai A simple ERC20 wrapper over the Dai Savings Protocol. Asset adapter
Dai Savings Protocol Decentralized lending protocol. Asset adapter β€”
Maker Governance MKR tokens locked on the MakerDAO governance contracts. Asset adapter β€”
Multi-Collateral Dai Collateralized loans on Maker. Debt adapter β€”
Matic A scaling solution for public blockchains. Staking adapter β€”
Melon A protocol for decentralized on-chain asset management. Asset adapter
mStable mStable unifies stablecoins, lending and swapping into one standard. Staking adapter
Nexus Mutual A people-powered alternative to insurance. Staking adapter β€”
Pickle Finance Off peg bad, on peg good. Staking adapter V2
PieDAO The Asset Allocation DAO. Staking adapter
PoolTogether Decentralized no-loss lottery. Supports SAI, DAI, and USDC pools. Asset adapter
SashimiSwap Earn SASHIMI tokens by staking Uniswap V2 LP Tokens. Staking adapter β€”
SushiSwap Stake Uniswap LP tokens to claim your very own yummy SUSHI! Staking adapter β€”
Swerve A fork that's 100% community owned and governed. Staking adapter
Synthetix Synthetic assets protocol. Asset adapter returns amount of SNX locked as collateral. Debt adapter β€”
TokenSets Automated asset management strategies. Asset adapter V2
Uniswap V1 Automated liquidity protocol. Asset adapter supports all Uniswap V1 pools
Uniswap V2 Automated liquidity protocol. Asset adapter supports all Uniswap V2 pools
0x Staking Liquidity rewards for staking ZRX. Asset adapter β€”

How to Add Your Adapter

The full instructions on how to add a custom adapter to the AdapterRegistry contract may be found in our wiki.

If you have questions and/or want to add your adapter to Zerion reach out to us on our Discord server. All security vulnerabilities will be promptly addressed.

Dev Notes

This project uses Truffle and web3js for all Ethereum interactions and testing.

Compile contracts

npm run compile

Run tests

npm run test

Run Solidity code coverage

npm run coverage

Currently, unsupported files are ignored.

Run Solidity and JS linters

npm run lint

Currently, unsupported files are ignored.

Run all the migrations scripts

npm run deploy:network, network is either development or mainnet


All smart contracts are released under GNU LGPLv3.