NAV Navbar
shell

Overview

Welcome to the Covalent API!

There are four main endpoints:

The most common query parameters:

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.
format optional One of csv, json. If not specified, use json
format-options optional noheader if you want to omit CSV headers

Introduction

The Covalent API is RESTful. The API is designed around the main resources that's available through the web interface. Sample API calls are provided next to each method using cURL.

URL Patterns

API Host

https://api.covalenthq.com/v1/

Some points to keep in mind:

Authentication

To access the Covalent API, you will need an API key. You can find your API key in the web interface. Various authentication mechanisms are available:

Query parameter

>>> curl -X GET https://api.covalenthq.com/v1/ENDPOINT/?key=API_KEY

Simply append key=API_KEY as a query parameter to all queries.

The main advantage of this method is to embed the API endpoints within applications that do not support more sophisticated auth mechanisms, like Google Sheets or as IFrames.

Basic Auth

>>> curl -X GET https://api.covalenthq.com/v1/ENDPOINT/ \
     -u API_KEY:
     -H 'Content-Type: application/json'
# The colon prevents curl from asking for a password.

Provide your API key as the basic auth username. You can find your API key in the web interface. You do not need to provide a password.

Response format

{
  "data": {...},
  "error": false,
  "error_message": null,
  "error_code": null
}

By default, we return JSON responses with the same shape for all endpoints. The main keys are data, error, error_message and error_code.

If you specify a CSV response using the format parameter – it's possible to toggle the headers on and off using the format-options=noheader parameter.

Client libraries

Though the Covalent REST API is idiomatic, for the best experience, we recommend using one of the client libraries.

Rate limiting

Not enforced at present. Please let us know before you melt our servers!

API Status

>>> curl "https://api.covalenthq.com/v1/status/" 
{
  "data": {
    "1": {
      "name": "Ethereum.Foundation",
      "latest_block": {
        "signed_at": "2019-04-03T00:05:06",
        "age_seconds": 28.898127,
        "height": 7492053,
        "hash": "0xd460470b3ff6dd53691b98eb97f907c055b82d474c6464c8aed2b4e04309e351"
      },
      "latest_enriched_block": {
        "block_signed_at": "2019-04-02T23:37:34",
        "age_seconds": 1680.898127,
        "block_height": 7491932
      }
    },
    "market_data_update": {
      "updated_at": "2019-04-02T23:45:48.173706",
      "age": 1187
    }
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

The API Status endpoint tells you how recently the on-chain and off-chain data was refreshed.

HTTP request

GET https://api.covalenthq.com/v1/status/

Crypto Prices

Get spot prices

>>> curl "https://api.covalenthq.com/v1/ticker/" 
{
  "data": {
    "quote_currencies": [
      {
        "name": "US Dollars",
        "ticker": "USD",
        "symbol": "$"
      },
      {
        "name": "Japanese Yen",
        "ticker": "JPY",
        "symbol": "¥"
      },
      ...
    ],
    "ticker": [
      {
        "ticker_symbol": "ETH",
        "quote_rate": 148.66,
        "decimals": 18,
        "address": null,
        "name": "Ether",
        "logo_url": "https://logos.covalenthq.com/tokens/0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee.png"
      },
      {
        "ticker_symbol": "FUN",
        "quote_rate": 0.00587787,
        "decimals": 8,
        "address": "0x419d0d8bdd9af5e606ae2232ed285aff190e711b",
        "name": "FunFair",
        "logo_url": "https://logos.covalenthq.com/tokens/0x419d0d8bdd9af5e606ae2232ed285aff190e711b.png"
      },
      {
        "ticker_symbol": "MATIC",
        "quote_rate": 0.03920658,
        "decimals": 18,
        "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
        "name": "Matic Token",
        "logo_url": "https://logos.covalenthq.com/tokens/0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0.png"
      },
      {
        ...
      }
    ]
  }
}

Get the supported currencies and the current spot prices in the quote-currency.

Currently supported currencies:

Currency Symbol Key
US Dollars $ USD
Canadian Dollars $ CAD
Euros EUR
Singapore Dollars $ SGD
Indian Rupees INR
Japanese Yen ¥ JPY
Vietnamese đồng VND
Chinese Yuan ¥ CNY
Russian Ruble RUB
South Korean Won KRW
Turkish Lira TRY

JSON Schema

TickerCurrencySymbolItem

{
  "title": "TickerCurrencySymbolItem",
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "ticker": {
      "title": "Ticker",
      "type": "string"
    },
    "symbol": {
      "title": "Symbol",
      "type": "string"
    }
  },
  "required": [
    "name",
    "ticker",
    "symbol"
  ]
}

TickerPriceItem

{
  "title": "TickerPriceItem",
  "type": "object",
  "properties": {
    "ticker_symbol": {
      "title": "Ticker Symbol",
      "type": "string"
    },
    "quote_rate": {
      "title": "Quote Rate",
      "type": "number"
    },
    "decimals": {
      "title": "Decimals",
      "type": "integer"
    },
    "address": {
      "title": "Address",
      "type": "string"
    },
    "name": {
      "title": "Name",
      "type": "string"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    }
  },
  "required": [
    "ticker_symbol",
    "quote_rate",
    "decimals",
    "address",
    "name",
    "logo_url"
  ]
}

TickerResponse

{
  "title": "TickerResponse",
  "type": "object",
  "properties": {
    "quote_currencies": {
      "title": "Quote Currencies",
      "type": "array",
      "items": {
        "$ref": "#/definitions/TickerCurrencySymbolItem"
      }
    },
    "ticker": {
      "title": "Ticker",
      "type": "array",
      "items": {
        "$ref": "#/definitions/TickerPriceItem"
      }
    }
  },
  "required": [
    "quote_currencies",
    "ticker"
  ]
}

HTTP request

GET https://api.covalenthq.com/v1/ticker/

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

Get historical prices

>>> curl "https://api.covalenthq.com/v1/prices/<quote_currency>/<ticker_symbol>/" 
{
  "data": {
    "quote_currency": "USD",
    "ticker_symbol": "BAT",
    "prices": [
      [
        [
          "2019-01-01",
          "0.12990789493630076"
        ]
      ]
    ]
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Get historical crypto currency prices in any of the supported quote-currencies. Additional GET parameters include:

Parameter Default Description
from None Start date of range
to None End date of range

Examples:

Get current spot price of BAT token in USD:

Get historical prices on YYYY-MM-DD:

Get historical prices from YYYY-MM-DD to ZZZZ-NN-EE:

Blocks

Get block

>>> curl "https://api.covalenthq.com/v1/1/block/6207112/" 
{
  "data": {
    "block": {
      "id": 1306258158258674000,
      "hash": "0xc90b63603a0b270576766e5f3a3b26290a4fb753622587f5faa93e5ac3f6d956",
      "version": 1702127665,
      "size": 38793,
      "signed_at": "2018-08-24T20:43:52",
      "parent_hash": "0x40533a67315a6c01633f7bf8044291daaadcdfbc8b16e4c54313011613af698c",
      "height": 6207112,
      "transactions_root": null,
      "uncles_root": null,
      "state_root": null,
      "receipts_root": null,
      "uncles": [],
      "extra_data": "0x65746865726d696e652d657534",
      "miner": "0xea674fdde714fd979de3edf0f56aa9716b898ec8",
      "mining_cost": 3476235820253555,
      "seal": [],
      "gas_limit": 8000029,
      "gas_used": 7979963,
      "observed_mediantime": null,
      "observed_difficulty": null,
      "confirmations_at_insertion": null,
      "miner_label": "Ethermine"
    },
    "transactions": [
      {
        "block_id": 1306258158258674000,
        "tx_offset": 0,
        "hash": "0xbda472257f4b997bf5b56b4d6d740b25a1856835cf697f9ca23c258a3b1ca5b7",
        "successful": true,
        "version": 1702127665,
        "size": 56,
        "mining_cost": 21000,
        "from": "0xea674fdde714fd979de3edf0f56aa9716b898ec8",
        "to": "0xa7ab4d96da92a2f51327ae4369292cc3986e16f7",
        "creates": null,
        "value": "60214405555576377",
        "eth_quote_rate": 275.80838507029057,
        "value_quote": 16.607637954251054,
        "payload_size": 0,
        "contract_input": null,
        "gas_offered": 50000,
        "gas_spent": 21000,
        "gas_price": 1000000000,
        "bitcoin_vins": null,
        "bitcoin_vouts": null,
        "block_signed_at": "2018-08-24T20:43:52",
        "block_height": 6207112,
        "to_label": null,
        "from_label": "Ethermine"
      },
      {...}
    ]
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Get a specific block with its transactions. We support lookups by both height as well as block hash.

HTTP request

GET https://api.covalenthq.com/v1/1/block/latest/

GET https://api.covalenthq.com/v1/1/block/HEIGHT/

GET https://api.covalenthq.com/v1/1/block/0xHASH/

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

Transactions

Get transaction

>>> curl "https://api.covalenthq.com/v1/1/transaction/0x4959b4636961c4a17f55f99afbaab76435b228d481aec68b3aa12e96fbe130d4/" 
{
  "data": {
    "transactions": [
      {
        "block_id": 1306258158258674000,
        "tx_offset": 42,
        "hash": "0x4959b4636961c4a17f55f99afbaab76435b228d481aec68b3aa12e96fbe130d4",
        "successful": true,
        "version": 1702127665,
        "size": 48,
        "mining_cost": 21000,
        "from": "0xddca59f0f2d0362043549e9b2a779cc1db9e99a8",
        "to": "0x11372a7418d58b162d1120e9e65e5aa74936ed71",
        "creates": null,
        "value": "1",
        "payload_size": 0,
        "contract_input": null,
        "gas_offered": 37500,
        "gas_spent": 21000,
        "gas_price": 2100000000,
        "bitcoin_vins": null,
        "bitcoin_vouts": null,
        "eth_quote_rate": 275.80838507029057,
        "value_quote": 2.7580838507029055e-16,
        "to_label": "BlockchainCuties_Wallet",
        "from_label": null,
        "block_signed_at": "2018-08-24T20:43:52",
        "block_height": 6207112
      }
    ],
    "block": {
      "id": 1306258158258674000,
      "hash": "0xc90b63603a0b270576766e5f3a3b26290a4fb753622587f5faa93e5ac3f6d956",
      "version": 1702127665,
      "size": 38793,
      "signed_at": "2018-08-24T20:43:52",
      "parent_hash": "0x40533a67315a6c01633f7bf8044291daaadcdfbc8b16e4c54313011613af698c",
      "height": 6207112,
      "transactions_root": null,
      "uncles_root": null,
      "state_root": null,
      "receipts_root": null,
      "uncles": [],
      "extra_data": "0x65746865726d696e652d657534",
      "miner": "0xea674fdde714fd979de3edf0f56aa9716b898ec8",
      "mining_cost": 3476235820253555,
      "seal": [],
      "gas_limit": 8000029,
      "gas_used": 7979963,
      "observed_mediantime": null,
      "observed_difficulty": null,
      "confirmations_at_insertion": null,
      "miner_label": "Ethermine"
    }
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Get a specific transaction by hash.

HTTP request

GET https://api.covalenthq.com/v1/1/transaction/0xHASH/

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

Get event logs

>>> curl "https://api.covalenthq.com/v1/1/transaction/0x4959b4636961c4a17f55f99afbaab76435b228d481aec68b3aa12e96fbe130d4/logs/" 
{
  "data": {
    "items": [
      {
        "log_offset": 66,
        "raw_log_topics": [
          "0xfcfff16f00000000000000000000000000000000000000000000000000000000",
          "0x000000000000000000000000381c2293585ee86a9f104a4896a140a8c1030cc2",
          "0x0000000000000000000000000000000000000000000000000000000000000000",
          "0x0000000000000000000000000000000000000000000000000000000000000000"
        ],
        "raw_log_data": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000004fcfff16f",
        "sender_address": "0x448a5065aebb8e423f0896e6c5d525c040f59af3"
      },
      {
        "log_offset": 67,
        "raw_log_topics": [
          "0x89b8893b806db50897c8e2362c71571cfaeb9761ee40727f683f1793cda9df16",
          "0x000000000000000000000000381c2293585ee86a9f104a4896a140a8c1030cc2"
        ],
        "raw_log_data": "0x0000000000000000000000000000000000000000000000000000000000000134",
        "sender_address": "0x448a5065aebb8e423f0896e6c5d525c040f59af3"
      }
    ]
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Get event logs for a specific transaction.

HTTP request

GET https://api.covalenthq.com/v1/1/transaction/0xHASH/logs/

Ethereum Name Service

The ENS endpoint supports lookups and makes suggestions for autocomplete.

>>> curl "https://api.covalenthq.com/v1/1/ens/?name=ganesh" 
{
  "data": {
    "item": {
      "match": null,
      "autocomplete": [
        {
          "name": "ganeshswami.eth"
        }
      ]
    },
    "updated_at": "2019-07-23T01:38:24.871309+00:00"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

HTTP request

GET https://api.covalenthq.com/v1/1/ens/?name=${NAME}

Addresses

The address endpoints support both lookups by hash as well as by ENS (Ethereum Name Service) names.

Get address token balances

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/balances/" 
{
  "data": {
    "balances": [
      {
        "contract_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "balance": "2349416542132499968",
        "quote_rate_24h": "154.26019001704213",
        "quote_rate": "159.26154203702",
        "quote": "374.17170138730535",
        "quote_pct_change_24h": 1.032421534158783,
        "contract_name": "Ether",
        "contract_ticker_symbol": "ETH",
        "contract_decimals": 18,
        "type": "cryptocurrency",
        "logo_url": "https://logos...png"
      },
      {
        "contract_address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
        "balance": "200405005017460015104",
        "quote_rate_24h": "0.9892345464742915",
        "quote_rate": "0.990828328985026",
        "quote": "198.5669562416857",
        "quote_pct_change_24h": 1.001611127023834,        
        "contract_name": "DAI",
        "contract_ticker_symbol": "DAI",
        "contract_decimals": 18,
        "type": "stablecoin",
        "logo_url": "https://logos...png"
      },
      {...},
    ],
    "source": "gnosis-safe",
    "address": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638",
    "updated_at": "2019-07-08T21:02:04.147343+00:00"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return the user's token balances.

JSON Schema

TokenBalance

{
  "title": "TokenBalance",
  "type": "object",
  "properties": {
    "contract_address": {
      "title": "Contract Address",
      "type": "string"
    },
    "balance": {
      "title": "Balance",
      "type": "string"
    },
    "quote_rate_24h": {
      "title": "Quote Rate 24H",
      "type": "string"
    },
    "quote_rate": {
      "title": "Quote Rate",
      "type": "string"
    },
    "quote": {
      "title": "Quote",
      "type": "string"
    },
    "quote_pct_change_24h": {
      "title": "Quote Pct Change 24H",
      "type": "number"
    },
    "contract_name": {
      "title": "Contract Name",
      "type": "string"
    },
    "contract_ticker_symbol": {
      "title": "Contract Ticker Symbol",
      "type": "string"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    },
    "type": {
      "title": "Type",
      "type": "string"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    }
  },
  "required": [
    "contract_address",
    "balance",
    "quote_rate_24h",
    "quote_rate",
    "quote",
    "quote_pct_change_24h",
    "contract_name",
    "contract_ticker_symbol",
    "contract_decimals",
    "type",
    "logo_url"
  ]
}

TokenBalanceResponse

{
  "title": "TokenBalanceResponse",
  "type": "object",
  "properties": {
    "address": {
      "title": "Address",
      "type": "string"
    },
    "updated_at": {
      "title": "Updated At",
      "type": "string",
      "format": "date-time"
    },
    "balances": {
      "title": "Balances",
      "type": "array",
      "items": {
        "$ref": "#/definitions/TokenBalance"
      }
    },
    "source": {
      "title": "Source",
      "type": "string"
    }
  },
  "required": [
    "address",
    "updated_at",
    "balances",
    "source"
  ]
}
Field Description
contract_address Address of token
contract_name Name of token
contract_ticker_symbol Ticker symbol of token
contract_decimals Decimals of token
balance Balance of token
quote_rate Quote rate of token in quote-currency
quote_rate_24h Quote rate of token in quote-currency 24 hours ago
quote Quote of token balance in quote-currency
quote_pct_change_24h 24 hour percentage change of quote
type One of stablecoin, cryptocurrency or dust
logo_url Logo of token

The response additionally returns a source field which detects the smart contract wallet if possible. Valid values are instadapp, gnosis-safe, argent, dapper, etc.

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/balances/?quote-currency=cad

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.
contract-address optional Only return balances for this contract address.

Get address transactions

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/tx/?contract-address=0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359" 
{
  "data": {
    "items": [
      {
        "block_id": 1395612332474740700,
        "tx_offset": 37,
        "hash": "0xd9a4e98c9f12f9261a3b99aa332624732400a17edeba3b35a50e28b5b67a2f9a",
        "successful": true,
        "version": 1702127665,
        "size": 117,
        "mining_cost": 37362,
        "from": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638",
        "to": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
        "creates": null,
        "value": "0",
        "payload_size": 68,
        "contract_input": null,
        "gas_offered": 56043,
        "gas_spent": 37362,
        "gas_price": 6000000000,
        "bitcoin_vins": null,
        "bitcoin_vouts": null,
        "block_signed_at": "2019-04-22T15:43:42",
        "block_height": 7618314,
        "to_label": "Dai Stablecoin",
        "from_label": null
      },
      {
        "block_id": 1393358501355809500,
        "tx_offset": 76,
        "hash": "0xe6625a2e37c38987a9926d46797d1f23754ec6b237465e1d6c72d4d79dff7ba6",
        "successful": true,
        "version": 1702127665,
        "size": 118,
        "mining_cost": 52298,
        "from": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638",
        "to": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
        "creates": null,
        "value": "0",
        "payload_size": 68,
        "contract_input": null,
        "gas_offered": 78447,
        "gas_spent": 52298,
        "gas_price": 7000000000,
        "bitcoin_vins": null,
        "bitcoin_vouts": null,
        "block_signed_at": "2019-04-16T13:57:41",
        "block_height": 7579317,
        "to_label": "Dai Stablecoin",
        "from_label": null, 
        "transfers": {
          "erc20": [
            {
              "contract_address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
              "contract_name": "Dai Stablecoin v1.0",
              "contract_ticker_symbol": "DAI",
              "contract_decimals": 18,
              "value": 5
            }
          ]
        }
      }
    ],
    "address": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/tx/

GET parameters

Parameter Default Description
contract-address optional Additionally filter transactions from or to this contract address.

Get address token transfers

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/transfers/" 
{
  "data": {
    "transfers": {
      "erc20": [
        {
          "tx_hash": "0xd51e71e093135b28f38c24dbd3710af02a58021e6ffaed72aa4057dce01f6515",
          "block_signed_at": "2019-03-17T11:08:23",
          "block_height": 7386097,
          "address_from": "0xbc33a1f908612640f2849b56b67a4de4d179c151",
          "address_to": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638",
          "value": 628502862143447000,
          "contract_address": "0xdd974d5c2e2928dea5f71b9825b8b646686bd200",
          "contract_name": null,
          "contract_ticker_symbol": null,
          "contract_decimals": null,
          "address_to_label": null,
          "address_from_label": null,
          "contract_address_label": "KyberNetwork",
          "transfer_type": "IN"
        },
        {...}
      ]
    },
    "address": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/transfers/

Parameter Default Description
tx optional Additionally filter transfers belong to a particular transaction

Get address stacks – MakerDAO

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/makerdao/" 
{
  "data": {
    "makerdao": {
      "sum_ink": "221577.06181019504",
      "sum_art": "12273400.0",
      "count_cups": 1,
      "count_vaults": 1,
      "dai_quote_rate": "0.983693408067103",
      "sum_art_quote": "12073262.674570782",
      "ink_quote_rate": "179.96915565990184",
      "sum_ink_quote": "39877036.727582686",
      "breakdown_cup": [
        {
          "id": 5199,
          "ink": "221577.06181019504",
          "per": "1.0408845013394263",
          "art": "12273400",
          "eth": "0.030000015988725908",
          "ratio": "2.625743973666703",
          "eth_quote_rate": "176.8",
          "eth_quote": "5.304002826806741",
          "liq_price": "100.99994617131814",
          "outstanding_fee_dai": "0.15430253655944356",
          "stability_fee_annual": "0.09500000040404544",
          "cdp_source": "InstaDApp",
          "sum_locked": "238958.79551649716",
          "sum_freed": "17381.73370630222",
          "sum_minted": "13775100.0",
          "sum_wiped": "1501700.0",
          "dai_quote_rate": "0.983693408067103",
          "art_quote": "12073262.674570782",
          "ink_quote_rate": "179.96915565990184",
          "ink_quote": "39877036.727582686",
          "count_acts": 214,
          "breakdown_acts": [
            {
              "act_at": "2019-04-30T04:02:06+00:00",
              "act": "GIVE",
              "arg": "0xe1d2829198616b784cd01dbf5cd808c5c111e8af",
              "ink": "0.028815338653603955",
              "art": "2",
              "description": "Transfer CDP"              
            },
            {
              "act_at": "2019-04-30T04:02:06+00:00",
              "act": "DRAW",
              "arg": "2",
              "ink": "0.028815338653603955",
              "art": "2",
              "description": "Borrowed 2.00 DAI"
            },
            {
              "act_at": "2019-04-30T04:02:06+00:00",
              "act": "LOCK",
              "arg": "0.028815338653603955",
              "ink": "0.028815338653603955",
              "art": "2",
              "description": "Deposited 0.03 ETH"
            },
            {
              "act_at": "2019-04-30T04:02:06+00:00",
              "act": "OPEN",
              "arg": "-",
              "ink": "0",
              "art": "0",
              "description": "Opened CDP"
            }
          ]
        }
      ],
      "breakdown_vault": [
        {
          "id": 327,
          "owner": "0xd2a3334183fb61c3770e3658d7127b410768a210",
          "ilk": "ETH",
          "ink": "350000000000000000",
          "art": "19989506213587448767",
          "art_contract_decimals": 18,
          "ink_contract_decimals": 18,
          "debt": "20069641597402298800",
          "debt_quote_rate": 0.995949,
          "debt_quote": 19.988426411791945,
          "stability_fee_annual": "0.040000001890788006",
          "collateral_quote_rate": 128.261472585,
          "collateral_quote": 44.89151540475,
          "collateral_logo_url": "https://logos.covalenthq.com/tokens/0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee.png",
          "urn": "0x06b115b7fD3233847c419A4EF559ECC32f89Ace5",
          "vault_source": "maker",
          "ratio": "2.2367870989066643",
          "liq_price": "86.0127",
          "breakdown_acts": [
            {
              "act_at": "2019-11-18T17:05:57",
              "act": "GENERATE",
              "description": "Generated 20.0000 DAI",
              "tx_hash": "0xb55a4d23962d89e48e215a82d7e2faa3e6577a5dd74859c226dc3bf5219a4379",
              "amount": "20000000000000000000",
              "ticker_symbol": "DAI",
              "quote_rate": 1.000650588888066,
              "contract_decimals": 18
            },
            ...
          ]
        },
        ...
      ]
    },
    "address": "0x5e90bdc06e1af172ce97fa8a029d0587ece6a831"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user activity in the MakerDAO protocol.

For Vaults (to generate DAI)

Field Description
id ID of the Vault
ilk The collateral type, either ETH, BAT, or another asset
ink Collateral amount
art Outstanding debt in DAI
debt Outstanding debt in DAI including fees
debt_quote_rate Quote rate of DAI in quote-currency
debt_quote Outstanding debt in quote-currency including fees
art_contract_decimals Decimals of DAI contract
ink_contract_decimals Decimals of collateral contract
stability_fee_annual Annual stability fee (%)
collateral_quote_rate Quote rate of collateral
collateral_quote Quote of collateral
collateral_logo_url Logo of collateral
vault_source Source of Vault – maker, instadapp, etc.
ratio Current Collateralization Ratio
liq_price Liquidation Price

For CDPs (to generate SAI)

Field Description
id ID of the CUP
ink Collateral in PETH
per Exchange rate of PETH to ETH
art Outstanding debt in SAI
eth Collateral Amount in ETH
ratio Current Collateralization Ratio
eth_quote_rate ETH spot quote rate
eth_quote ETH value in quote currency
liq_price Liquidation Price
outstanding_fee_dai Outstanding fee in DAI
stability_fee_annual Annual stability fee (%)
cdp_source Source of CDP – maker, instadapp, etc.
sum_locked Volume of collateral locked
sum_freed Volume on collateral freed
sum_minted Volume of DAI minted
sum_wiped Volume of DAI wiped
dai_quote_rate Exchange rate of DAI in quote-currency
art_quote Quote of outstanding debt converted to quote-currency
ink_quote_rate Exchange rate of collateral in quote-currency
ink_quote Ouote of collateral converted to quote-currency
count_acts Total number of actions performed against this CUP
breakdown_acts Action breakdown

Each CDP is further broken down by actions:

Field Description
act_at When the action was performed
act The action: OPEN, LOCK, DRAW, CLOSE, WIPE, etc.
arg Argument
ink Collateral in ETH
art Outstanding debt in DAI
description Human readable text of the action

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/makerdao/

JSON Schema

Vault

{
  "title": "Vault",
  "type": "object",
  "properties": {
    "id": {
      "title": "Id",
      "type": "integer"
    },
    "owner": {
      "title": "Owner",
      "type": "string"
    },
    "ilk": {
      "title": "Ilk",
      "type": "string"
    },
    "ink": {
      "title": "Ink",
      "type": "number"
    },
    "art": {
      "title": "Art",
      "type": "number"
    },
    "art_contract_decimals": {
      "title": "Art Contract Decimals",
      "type": "integer"
    },
    "ink_contract_decimals": {
      "title": "Ink Contract Decimals",
      "type": "integer"
    },
    "debt": {
      "title": "Debt",
      "type": "number"
    },
    "debt_quote_rate": {
      "title": "Debt Quote Rate",
      "type": "number"
    },
    "debt_quote": {
      "title": "Debt Quote",
      "type": "number"
    },
    "stability_fee_annual": {
      "title": "Stability Fee Annual",
      "type": "string"
    },
    "collateral_quote_rate": {
      "title": "Collateral Quote Rate",
      "type": "number"
    },
    "collateral_quote": {
      "title": "Collateral Quote",
      "type": "number"
    },
    "collateral_logo_url": {
      "title": "Collateral Logo Url",
      "type": "string"
    },
    "urn": {
      "title": "Urn",
      "type": "string"
    },
    "vault_source": {
      "title": "Vault Source",
      "type": "string"
    },
    "ratio": {
      "title": "Ratio",
      "type": "string"
    },
    "liq_price": {
      "title": "Liq Price",
      "type": "string"
    },
    "liq_penalty": {
      "title": "Liq Penalty",
      "type": "number"
    },
    "min_liq_ratio": {
      "title": "Min Liq Ratio",
      "type": "number"
    },
    "breakdown_acts": {
      "title": "Breakdown Acts",
      "type": "array",
      "items": {
        "$ref": "#/definitions/VaultAct"
      }
    }
  },
  "required": [
    "id",
    "owner",
    "ilk",
    "ink",
    "art",
    "art_contract_decimals",
    "ink_contract_decimals",
    "debt",
    "debt_quote_rate",
    "debt_quote",
    "stability_fee_annual",
    "collateral_quote_rate",
    "collateral_quote",
    "collateral_logo_url",
    "urn",
    "vault_source",
    "ratio",
    "liq_price",
    "liq_penalty",
    "min_liq_ratio",
    "breakdown_acts"
  ]
}

VaultAct

{
  "title": "VaultAct",
  "type": "object",
  "properties": {
    "act_at": {
      "title": "Act At",
      "type": "string",
      "format": "date-time"
    },
    "act": {
      "title": "Act",
      "type": "string"
    },
    "description": {
      "title": "Description",
      "type": "string"
    },
    "tx_hash": {
      "title": "Tx Hash",
      "type": "string"
    },
    "amount": {
      "title": "Amount",
      "type": "number"
    },
    "ticker_symbol": {
      "title": "Ticker Symbol",
      "type": "string"
    },
    "quote_rate": {
      "title": "Quote Rate",
      "type": "number"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    }
  },
  "required": [
    "act_at",
    "act",
    "description",
    "tx_hash",
    "amount",
    "ticker_symbol",
    "quote_rate",
    "contract_decimals"
  ]
}

Get address stacks – DAI Savings Rate

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/dsr/"
{
  "data": {
    "dsr": [{
      "owner": "0xHASH",
      "balance_dai": "250520868160474808320",
      "balance_dai_quote": 249.50686239687485,
      "dsr": "0.04000000189078800616471198736689984798431396484375",
      "earnings_dai": "20627576588463555222",
      "earnings_dai_quote": 519.0477097995415,
      "dai_quote_rate": 0.995949,
      "acts": [
        {
          "act_at": "2019-11-19T11:11:30",
          "tx_hash": "0x605999197a9de66d8cb4f6e966b94c850dcc3426cb33120b8390d86c44ad7e89",
          "amount": "639958088808202200",
          "act": "DEPOSIT",
          "description": "Deposited 0.6400 DAI."
        },
        {
          "act_at": "2019-11-19T11:20:24",
          "tx_hash": "0xd38b9adecf97ce25828c4426cb9852e57f7f8f45b159f530e78150c57cd3cb82",
          "amount": "118543697061094480",
          "description": "Withdrew 0.1185 DAI."
        },
        ...
      ]
    }],
    "address": "0x94730d96a3ebf6ec576c4b4d0c35ff8d8c9b74ca"
  },
  "error": false,
  "error_message": null,
  "error_code": null    
  }
}

Return user activity in the Maker DAI Savings Rate contracts.

Field Description
balance_dai Current DAI balance locked
balance_dai_quote Current DAI balance locked in quote-currency
dsr Savings Rate in percentage (so 0.0199 is 1.99%)
earnings_dai Earnings to date in DAI
earnings_dai_quote Earnings to date in quote-currency
dai_quote_rate DAI price in quote-currency
acts List of deposits and withdrawls from the DSR contract

JSON Schema

DsrBalance

{
  "title": "DsrBalance",
  "type": "object",
  "properties": {
    "owner": {
      "title": "Owner",
      "type": "string"
    },
    "balance_dai": {
      "title": "Balance Dai",
      "type": "number"
    },
    "balance_dai_quote": {
      "title": "Balance Dai Quote",
      "type": "number"
    },
    "dsr": {
      "title": "Dsr",
      "type": "number"
    },
    "earnings_dai": {
      "title": "Earnings Dai",
      "type": "number"
    },
    "earnings_dai_quote": {
      "title": "Earnings Dai Quote",
      "type": "number"
    },
    "dai_quote_rate": {
      "title": "Dai Quote Rate",
      "type": "number"
    },
    "acts": {
      "title": "Acts",
      "type": "array",
      "items": {
        "$ref": "#/definitions/DsrAct"
      }
    }
  },
  "required": [
    "owner",
    "balance_dai",
    "balance_dai_quote",
    "dsr",
    "earnings_dai",
    "earnings_dai_quote",
    "dai_quote_rate",
    "acts"
  ]
}

DsrAct

{
  "title": "DsrAct",
  "type": "object",
  "properties": {
    "act_at": {
      "title": "Act At",
      "type": "string",
      "format": "date-time"
    },
    "tx_hash": {
      "title": "Tx Hash",
      "type": "string"
    },
    "amount": {
      "title": "Amount",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "number"
        }
      ]
    },
    "act": {
      "title": "Act",
      "type": "string"
    },
    "description": {
      "title": "Description",
      "type": "string"
    }
  },
  "required": [
    "act_at",
    "tx_hash",
    "amount",
    "act",
    "description"
  ]
}

Get address stacks – Compound Finance

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/compoundfinance/" 
{
  "data": {
    "address": "0xb5c0f0ff448c4891e04fd88ff77e634e8c9d6e7b",
    "compoundfinance_v2": [{
      "total_supply_eth": "2858463990539173",
      "total_supply_eth_quote": 1.008203117175091,
      "total_borrow_eth": "1455428872332676",
      "total_borrow_eth_quote": 0.5133414067027136,
      "total_collateral_eth": "2145442351402070",
      "total_collateral_eth_quote": 0.7567146808783214,
      "total_borrowing_power_eth": "688419120571704",
      "total_borrowing_power_eth_quote": 0.24281093117860464,
      "supply_tokens": [
        {
          "borrow_balance": "0",
          "borrow_balance_quote": 0,
          "borrow_interest_accrued": "0",
          "borrow_interest_accrued_quote": 0,
          "supply_balance": "1008203117175090944",
          "supply_balance_quote": 1.008203117175091,
          "supply_interest_accrued": "8203117175091000.0",
          "supply_interest_accrued_quote": 0.008203117175091,
          "quote_rate": 1,
          "apr": 9.82043672333472,
          "contract_address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
          "contract_decimals": 18,
          "contract_name": "Dai Stablecoin v1.0",
          "contract_ticker_symbol": "DAI"
        }
      ],
      "borrow_tokens": [
        {
          "borrow_balance": "1002283968530055",
          "borrow_balance_quote": 0.35351357397229893,
          "borrow_interest_accrued": "2283968530055.7",
          "borrow_interest_accrued_quote": 0.0008055739722988859,
          "supply_balance": "0",
          "supply_balance_quote": 0,
          "supply_interest_accrued": "0",
          "supply_interest_accrued_quote": 0,
          "quote_rate": 352.708,
          "apr": 2.29265778524256,
          "contract_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
          "contract_decimals": 18,
          "contract_name": "Ether",
          "contract_ticker_symbol": "ETH"
        },
        {
          "borrow_balance": "501895243546390016",
          "borrow_balance_quote": 0.1651882796131798,
          "borrow_interest_accrued": "1895243546390000.0",
          "borrow_interest_accrued_quote": 0.0006237796131797944,
          "supply_balance": "0",
          "supply_balance_quote": 0,
          "supply_interest_accrued": "0",
          "supply_interest_accrued_quote": 0,
          "quote_rate": 0.329129,
          "apr": 4.43485942130016,
          "contract_address": "0x0d8775f648430679a709e98d2b0cb6250d2887ef",
          "contract_decimals": 18,
          "contract_name": "Basic Attention Token",
          "contract_ticker_symbol": "BAT"
        }
      ],
      "breakdown_acts": [{
        "act_at": "2019-05-28T16:56:57",
        "act": "BORROW",
        "description": "Borrowed 0.5 cBAT",
        "tx_hash": "0xHASH"
      }, {
        "act_at": "2019-05-28T00:19:19",
        "act": "BORROW",
        "description": "Borrowed 0.001 cETH",
        "tx_hash": "0xHASH"
      }, {
        "act_at": "2019-05-27T23:30:46",
        "act": "MINT",
        "description": "Supplied 1.0 DAI",
        "tx_hash": "0xHASH"
      }],
      "quote_currency": "USD",
      "account_address": "0xb5c0f0ff448c4891e04fd88ff77e634e8c9d6e7b"
    }],
    "compoundfinance": {
      "account_liquidity": "158726896205301538",
      "account_liquidity_quote_rate": "221.325",
      "account_liquidity_quote": "35.13023030263836",
      "lending_asset": [
        {
          "balance": "100009363149677292862",
          "balance_quote": "30",
          "balance_quote_rate": "0.309481",
          "contract_address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
          "contract_name": "0x Token",
          "contract_ticker_symbol": "ZRX",
          "contract_decimals": 18,
          "apr": "0.70942354877376"
        },
        {
          "balance": "53915901007077004496",
          "balance_quote": "19",
          "balance_quote_rate": "0.3632",
          "contract_address": "0x0d8775f648430679a709e98d2b0cb6250d2887ef",
          "contract_name": "Basic Attention Token",
          "contract_ticker_symbol": "BAT",
          "contract_decimals": 18,
          "apr": "0.12226194972576"
        }
      ],
      "borrowing_asset": [
        {
          "balance": "11471701669091759871",
          "balance_quote": "11",
          "balance_quote_rate": "0.998097",
          "contract_address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
          "contract_name": "Dai Stablecoin v1.0",
          "contract_ticker_symbol": "DAI",
          "contract_decimals": 18,
          "apr": "16.34087066707872"
        }
      ]
    }
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user activity in the Compound Finance protocol.

Field Description
contract_address Address of ERC20 token
contract_name Name of ERC20 token
contract_ticker_symbol Ticker symbol of ERC20 token
contract_decimals Decimals of ERC20 token

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/compoundfinance/

JSON Schema

CompoundAct

{
  "title": "CompoundAct",
  "type": "object",
  "properties": {
    "act_at": {
      "title": "Act At",
      "type": "string",
      "format": "date-time"
    },
    "act": {
      "title": "Act",
      "type": "string"
    },
    "description": {
      "title": "Description",
      "type": "string"
    },
    "tx_hash": {
      "title": "Tx Hash",
      "type": "string"
    },
    "amount": {
      "title": "Amount",
      "type": "number"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    },
    "contract_ticker_symbol": {
      "title": "Contract Ticker Symbol",
      "type": "string"
    },
    "quote_rate": {
      "title": "Quote Rate",
      "type": "number"
    },
    "quote": {
      "title": "Quote",
      "type": "number"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    }
  },
  "required": [
    "act_at",
    "act",
    "description",
    "tx_hash",
    "amount",
    "contract_decimals",
    "contract_ticker_symbol",
    "quote_rate",
    "quote",
    "logo_url"
  ]
}

Get address stacks – Synthetix

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/synthetix/" 
{
  "data": {
    "synthetix": {
      "balances": [
        {
          "contract_ticker_symbol": "sUSD",
          "balance": "280012531710191410812",
          "balance_quote": 280.0125317101914,
          "contract_decimals": 18,
          "logo_url": "https://www.covalenthq.com/static/images/safekeep/logos/synthetix.png"
        },
        {
          "contract_ticker_symbol": "sEUR",
          "balance": "173817935074215469836",
          "balance_quote": 193.69923048800422,
          "contract_decimals": 18,
          "logo_url": "https://www.covalenthq.com/static/images/safekeep/logos/synthetix.png"
        },
        {
          "contract_ticker_symbol": "sDEFI",
          "balance": "49445086009557249",
          "balance_quote": 40.20556409176934,
          "contract_decimals": 18,
          "logo_url": "https://www.covalenthq.com/static/images/safekeep/logos/synthetix.png"
        },
        {
          "contract_ticker_symbol": "sETH",
          "balance": "26395386556416243",
          "balance_quote": 3.7806111161115714,
          "contract_decimals": 18,
          "logo_url": "https://www.covalenthq.com/static/images/safekeep/logos/synthetix.png"
        }
      ],
      "summary": {
        "collateral": "4747526149082719465263",
        "collateral_decimals": 18,
        "collateral_quote": 4804.169301491594,
        "debt_susd": "779941373548972090981",
        "debt_susd_quote": 779.9413735489721,
        "debt_susd_decimals": 18,
        "susd_balance": "280012531710191410812",
        "susd_balance_decimals": 18,
        "collateralisation_ratio": 6,
        "fees_available": "0",
        "fees_available_decimals": 18,
        "rewards_available": "0",
        "rewards_available_decimals": 18
      }
    },
    "address": "..."
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user activity in the Synthetix protocol.

Field Description
collateral Total collateral
collateral_decimals Decimal to format collateral
collateral_quote Value of collateral in quote-currency
debt_susd Debt in sUSD
debt_susd_quote Debt in sUSD in quote-currency
debt_susd_decimals Decimals to format debt
susd_balance sUSD balance
susd_balance_decimals Decimals to format sUSD balance
collateralisation_ratio Current collateralisation ratio percentage (so 5 is 500%)
fees_available Fees available
fees_available_decimals Decimals to format fees
rewards_available Rewards available
rewards_available_decimals Decimals to format rewards

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/synthetix/

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

JSON Schema

SynthetixBalance

{
  "title": "SynthetixBalance",
  "type": "object",
  "properties": {
    "contract_ticker_symbol": {
      "title": "Contract Ticker Symbol",
      "type": "string"
    },
    "balance": {
      "title": "Balance",
      "type": "number"
    },
    "balance_quote": {
      "title": "Balance Quote",
      "type": "number"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    }
  },
  "required": [
    "contract_ticker_symbol",
    "balance",
    "balance_quote",
    "contract_decimals",
    "logo_url"
  ]
}

SynthetixSummary

{
  "title": "SynthetixSummary",
  "type": "object",
  "properties": {
    "collateral": {
      "title": "Collateral",
      "type": "number"
    },
    "collateral_decimals": {
      "title": "Collateral Decimals",
      "type": "integer"
    },
    "collateral_quote": {
      "title": "Collateral Quote",
      "type": "number"
    },
    "debt_susd": {
      "title": "Debt Susd",
      "type": "number"
    },
    "debt_susd_quote": {
      "title": "Debt Susd Quote",
      "type": "number"
    },
    "debt_susd_decimals": {
      "title": "Debt Susd Decimals",
      "type": "integer"
    },
    "susd_balance": {
      "title": "Susd Balance",
      "type": "number"
    },
    "susd_balance_decimals": {
      "title": "Susd Balance Decimals",
      "type": "integer"
    },
    "collateralisation_ratio": {
      "title": "Collateralisation Ratio",
      "type": "number"
    },
    "fees_available": {
      "title": "Fees Available",
      "type": "number"
    },
    "fees_available_decimals": {
      "title": "Fees Available Decimals",
      "type": "integer"
    },
    "rewards_available": {
      "title": "Rewards Available",
      "type": "number"
    },
    "rewards_available_decimals": {
      "title": "Rewards Available Decimals",
      "type": "integer"
    }
  },
  "required": [
    "collateral",
    "collateral_decimals",
    "collateral_quote",
    "debt_susd",
    "debt_susd_quote",
    "debt_susd_decimals",
    "susd_balance",
    "susd_balance_decimals",
    "collateralisation_ratio",
    "fees_available",
    "fees_available_decimals",
    "rewards_available",
    "rewards_available_decimals"
  ]
}

SynthetixResponse

{
  "title": "SynthetixResponse",
  "type": "object",
  "properties": {
    "balances": {
      "title": "Balances",
      "type": "array",
      "items": {
        "$ref": "#/definitions/SynthetixBalance"
      }
    },
    "summary": {
      "$ref": "#/definitions/SynthetixSummary"
    }
  },
  "required": [
    "balances",
    "summary"
  ]
}

Get address stacks – Uniswap

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/uniswap/" 
{
  "data": {
    "uniswap": {
      "sum_pool_share_eth_quote": "403293.42387581285",
      "sum_pool_share_token_quote": "401829.6454741491",
      "pool_exchange": [
        {
            "contract_address": "0x8dd5fbce2f6a956c3022ba3663759011dd51e73e",
            "contract_decimals": 18,
            "contract_name": "TrueUSD",
            "contract_ticker_symbol": "TUSD",
            "eth_quote_rate": "166.69459545068",
            "exchange": "0x4F30E682D0541eAC91748bd38A648d759261b8f3",
            "pool_liquidity_token": "1615432946624674066697",
            "pool_liquidity_total_supply": "1706601949533051511590",
            "pool_share_eth": "1487539156149097988096",
            "pool_share_eth_quote": "247964.73785131978",
            "pool_share_percentage": 0.9465786366098302,
            "pool_share_token": "246465172542910478942208",
            "pool_share_token_quote": "248237.61236379898",
            "pool_total_eth_reserve": "1571490311123772197006",
            "pool_total_token_reserve": "260374746492932770606433",
            "token_quote_rate": "1.00719144130021"
        },
        {
            "contract_address": "0x3772f9716cf6d7a09ede3587738aa2af5577483a",
            "contract_decimals": 18,
            "contract_name": "Synthetix Network Token",
            "contract_ticker_symbol": "SNX",
            "eth_quote_rate": "166.69459545068",
            "exchange": "0x5d8888a212d033cff5F2e0AC24ad91A5495bAD62",
            "pool_liquidity_token": "555358711767179189745",
            "pool_liquidity_total_supply": "565358711905343825164",
            "pool_share_eth": "578962414766028029952",
            "pool_share_eth_quote": "96509.90551057184",
            "pool_share_percentage": 0.9823121145432373,
            "pool_share_token": "1338702205009926887047168",
            "pool_share_token_quote": "93599.96559325476",
            "pool_total_eth_reserve": "589387432155652673374",
            "pool_total_token_reserve": "1362807385952281029606437",
            "token_quote_rate": "0.0699184368584503"
        },
        {...}
      ]
    },
    "address": "0xf6b6f07862a02c85628b3a9688beae07fea9c863"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user activity in the Uniswap protocol.

Field Description
contract_address Address of ERC20 token
contract_name Name of ERC20 token
contract_ticker_symbol Ticker symbol of ERC20 token
contract_decimals Decimals of ERC20 token
eth_quote_rate Spot ETH price in quote-currency
exchange Exchange address
pool_liquidity_token Current liquidity tokens
pool_liquidity_total_supply Total liquidity tokens
pool_share_percentage Percentage of liquidity pool (pool_liquidity_token / pool_liquidity_total_supply)
pool_share_eth Share of ETH liquidity
pool_share_eth_quote Share of ETH liquidity in quote-currency
pool_share_token Share of token liquidity
pool_share_token_quote Share of token liquidity in quote-currency
pool_total_eth_reserve Total ETH in reserve
pool_total_token_reserve Total tokens in reserve
token_quote_rate Spot token price in quote-currency

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/uniswap/

Get address stacks – Uniswap Liquidity Provider ROI

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/uniswap/roi/" 
{
  "data": {
    "items": [
      {
        "exchange": "0xae76c84c9262cdb9abc0c2c8888e62db8e22a0bf",
        "token": "0xe41d2489571d322189246dafa5ebde1f4699f498",
        "logo_url": "https://logos.covalenthq.com/tokens/0xe41d2489571d322189246dafa5ebde1f4699f498.png",
        "contract_address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
        "contract_name": "0x Token",
        "contract_ticker_symbol": "ZRX",
        "contract_decimals": 18,
        "eth_reserve": "882708977664139626578",
        "token_reserve": "633937288228397645129590",
        "liquidity_supply": "1391627356250971352330",
        "series": [
          {
            "block_signed_at": "2020-01-22T06:58:04",
            "eth_amount": "73830166037573107712",
            "eth_amount_quote": 12510.521635066763,
            "eth_quote_rate": 169.45,
            "token_amount": "51644515104637067460608",
            "token_amount_quote": 12488.986509693965,
            "token_quote_rate": 0.241826,
            "kind": "CurrentLiquidity",
            "liquidity_balance": "114863424222852195168",
            "liquidity_supply": "1492932990325184863463",
            "pool_share_percentage": 0.07693809766896041,
            "pool_total_eth_reserve": "959604776754947599981",
            "pool_total_token_reserve": "671247622040859440223459",
            "provider": "0x145b8d0fe270b7bc4c362ecfa12e5f97e6788c48",
            "liquidity_delta": "114863424222852195168",
            "initial_quote": 0,
            "initial_token_quote_rate": 0,
            "initial_eth_quote_rate": 0,
            "hodl_quote": 0,
            "roi_net": 0,
            "roi_price": 0,
            "roi_uniswap": 0
          }
        ],
        "transfers": []
      },
      ...
    }
  }
}

Return ROI of user positions in Uniswap pools.

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/uniswap/roi/

JSON Schema

UniswapLiquidityActionWithRoi

{
  "title": "UniswapLiquidityActionWithRoi",
  "type": "object",
  "properties": {
    "block_signed_at": {
      "title": "Block Signed At",
      "type": "string",
      "format": "date-time"
    },
    "eth_amount": {
      "title": "Eth Amount",
      "type": "string"
    },
    "eth_amount_quote": {
      "title": "Eth Amount Quote",
      "type": "number"
    },
    "eth_quote_rate": {
      "title": "Eth Quote Rate",
      "type": "number"
    },
    "token_amount": {
      "title": "Token Amount",
      "type": "string"
    },
    "token_amount_quote": {
      "title": "Token Amount Quote",
      "type": "number"
    },
    "token_quote_rate": {
      "title": "Token Quote Rate",
      "type": "number"
    },
    "kind": {
      "title": "Kind",
      "type": "string"
    },
    "liquidity_balance": {
      "title": "Liquidity Balance",
      "type": "string"
    },
    "liquidity_supply": {
      "title": "Liquidity Supply",
      "type": "string"
    },
    "pool_share_percentage": {
      "title": "Pool Share Percentage",
      "type": "number"
    },
    "pool_total_eth_reserve": {
      "title": "Pool Total Eth Reserve",
      "type": "string"
    },
    "pool_total_token_reserve": {
      "title": "Pool Total Token Reserve",
      "type": "string"
    },
    "provider": {
      "title": "Provider",
      "type": "string"
    },
    "liquidity_delta": {
      "title": "Liquidity Delta",
      "type": "string"
    },
    "initial_quote": {
      "title": "Initial Quote",
      "type": "number"
    },
    "initial_token_quote_rate": {
      "title": "Initial Token Quote Rate",
      "type": "number"
    },
    "initial_eth_quote_rate": {
      "title": "Initial Eth Quote Rate",
      "type": "number"
    },
    "hodl_quote": {
      "title": "Hodl Quote",
      "type": "number"
    },
    "roi_net": {
      "title": "Roi Net",
      "type": "number"
    },
    "roi_price": {
      "title": "Roi Price",
      "type": "number"
    },
    "roi_uniswap": {
      "title": "Roi Uniswap",
      "type": "number"
    }
  },
  "required": [
    "block_signed_at",
    "eth_amount",
    "eth_amount_quote",
    "eth_quote_rate",
    "token_amount",
    "token_amount_quote",
    "token_quote_rate",
    "kind",
    "liquidity_balance",
    "liquidity_supply",
    "pool_share_percentage",
    "pool_total_eth_reserve",
    "pool_total_token_reserve",
    "provider",
    "liquidity_delta",
    "initial_quote",
    "initial_token_quote_rate",
    "initial_eth_quote_rate",
    "hodl_quote",
    "roi_net",
    "roi_price",
    "roi_uniswap"
  ]
}

UniswapLiquidityTokenTransfer

{
  "title": "UniswapLiquidityTokenTransfer",
  "type": "object",
  "properties": {
    "block_signed_at": {
      "title": "Block Signed At",
      "type": "string",
      "format": "date-time"
    },
    "block_height": {
      "title": "Block Height",
      "type": "integer"
    },
    "tx_hash": {
      "title": "Tx Hash",
      "type": "string"
    },
    "src": {
      "title": "Src",
      "type": "string"
    },
    "dst": {
      "title": "Dst",
      "type": "string"
    },
    "wad": {
      "title": "Wad",
      "type": "string"
    }
  },
  "required": [
    "block_signed_at",
    "block_height",
    "tx_hash",
    "src",
    "dst",
    "wad"
  ]
}

UniswapExchangeProvider

{
  "title": "UniswapExchangeProvider",
  "type": "object",
  "properties": {
    "exchange": {
      "title": "Exchange",
      "type": "string"
    },
    "token": {
      "title": "Token",
      "type": "string"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    },
    "contract_address": {
      "title": "Contract Address",
      "type": "string"
    },
    "contract_name": {
      "title": "Contract Name",
      "type": "string"
    },
    "contract_ticker_symbol": {
      "title": "Contract Ticker Symbol",
      "type": "string"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    },
    "eth_reserve": {
      "title": "Eth Reserve",
      "type": "string"
    },
    "token_reserve": {
      "title": "Token Reserve",
      "type": "string"
    },
    "liquidity_supply": {
      "title": "Liquidity Supply",
      "type": "string"
    },
    "series": {
      "title": "Series",
      "type": "array",
      "items": {
        "$ref": "#/definitions/UniswapLiquidityActionWithRoi"
      }
    },
    "transfers": {
      "title": "Transfers",
      "type": "array",
      "items": {
        "$ref": "#/definitions/UniswapLiquidityTokenTransfer"
      }
    }
  },
  "required": [
    "exchange",
    "token",
    "logo_url",
    "contract_address",
    "contract_name",
    "contract_ticker_symbol",
    "contract_decimals",
    "eth_reserve",
    "token_reserve",
    "liquidity_supply",
    "series",
    "transfers"
  ]
}

Get address stacks – dYdX

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/dydx/" 
{
  "data": {
    "dydx": {
      "accounts": [
        {
          "balances": [
            {
              "wei_balance": "20558084935214293.665406257049992528",
              "expires_at": null,
              "wei_quote_rate": 176.8,
              "wei_quote": 3.6346694165458873,
              "contract_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
              "contract_decimals": 18,
              "contract_name": "Ether",
              "contract_ticker_symbol": "ETH",
              "contract_logo_url": "https://logos.covalenthq.com/..../png"
            },
            {
              "wei_balance": "422153408639230072.128765557677510047",
              "expires_at": null,
              "wei_quote_rate": 1.01,
              "wei_quote": 0.4263749427256224,
              "contract_address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
              "contract_decimals": 18,
              "contract_name": "Dai Stablecoin v1.0",
              "contract_ticker_symbol": "DAI",
              "contract_logo_url": "https://logos.covalenthq.com/..../png"
            },
            {
              "wei_balance": "0",
              "expires_at": null,
              "wei_quote_rate": 1,
              "wei_quote": 0,
              "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
              "contract_decimals": 6,
              "contract_name": "USD Coin",
              "contract_ticker_symbol": "USDC",
              "contract_logo_url": "https://logos.covalenthq.com/..../png"
            }
          ]
        }
      ],
      "positions": [
        {
          "id": "0x5a6d3b6bf795a3160dc7c139dee9f60ce0f00cae-26311444941918392798411899699370080167007542401238594283409684256768330988469-1",
          "type": "LONG",
          "amount": "3184802762600924",
          "market": "WETH-DAI",
          "taker_market": "DAI",
          "maker_market": "WETH",
          "margin_deposit": "1665990374801355",
          "open_price": "257.33226735383846",
          "leverage": "3.000811879678947",
          "status": "Expired",
          "opened_at": "2019-05-16T23:11:40",
          "expiry_at": "2019-06-13T23:11:17"
        },
        {
          "id": "0x5a6d3b6bf795a3160dc7c139dee9f60ce0f00cae-109499526429114585681599801135456175318897947446045676840707596559038451568607-0",
          "type": "SHORT",
          "amount": "1999138630631862",
          "market": "WETH-DAI",
          "taker_market": "WETH",
          "maker_market": "DAI",
          "margin_deposit": "450322038762202537",
          "open_price": "227.5",
          "leverage": "2.010388035306146",
          "status": "Expired",
          "opened_at": "2019-05-17T17:54:18",
          "expiry_at": "2019-06-14T17:54:38"
        }
      ]
    },
    "address": "0x5a6d3b6bf795a3160dc7c139dee9f60ce0f00cae"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user balances and positions on dYdX protocol.

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

Get address stacks – Token Sets

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/tokensets/" 
{
  "data": {
    "tokensets": [
      {
        "contract_address": "0x9ea463ec4ce9e9e5bc9cfd0187c4ac3a70dd951d",
        "contract_name": "ETH 20 Day Moving Avg Set",
        "contract_symbol": "ETH20SMACO",
        "contract_decimals": 18,
        "logo_url": "https://.../average-set.svg",
        "balance": "1014001389336027000000",
        "quote": "226152.20988370164",
        "quote_rate": "223.0294872"
      },
      {...}
    ],
    "address": "0x91b867638d0e62d4e76273212ca15202b054d9f0"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user positions on Set protocol.

Field Description
contract_address Address of Token Set
contract_name Name of Token Set
contract_ticker_symbol Ticker symbol of Token Set
contract_decimals Decimals of Token Set
logo_url Logo of Token Set
balance User balance of Token Set
quote Current value of Token Set
quote_rate Spot price of Token Set

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/tokensets/

JSON Schema

SetPosition

{
  "title": "SetPosition",
  "type": "object",
  "properties": {
    "contract_address": {
      "title": "Contract Address",
      "type": "string"
    },
    "contract_name": {
      "title": "Contract Name",
      "type": "string"
    },
    "contract_symbol": {
      "title": "Contract Symbol",
      "type": "string"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    },
    "balance": {
      "title": "Balance",
      "type": "string"
    },
    "quote": {
      "title": "Quote",
      "type": "string"
    },
    "quote_rate": {
      "title": "Quote Rate",
      "type": "string"
    },
    "rebalance_criteria_price": {
      "title": "Rebalance Criteria Price",
      "type": "array",
      "items": {
        "$ref": "#/definitions/SetRebalancePriceCriteria"
      }
    }
  },
  "required": [
    "contract_address",
    "contract_name",
    "contract_symbol",
    "contract_decimals",
    "logo_url",
    "balance",
    "quote",
    "quote_rate",
    "rebalance_criteria_price"
  ]
}

SetRebalancePriceCriteria

{
  "title": "SetRebalancePriceCriteria",
  "type": "object",
  "properties": {
    "direction": {
      "title": "Direction",
      "type": "string"
    },
    "value": {
      "title": "Value",
      "type": "string"
    },
    "current": {
      "title": "Current",
      "type": "string"
    },
    "requirement": {
      "title": "Requirement",
      "type": "string"
    }
  },
  "required": [
    "direction",
    "value",
    "current",
    "requirement"
  ]
}

SetAct

{
  "title": "SetAct",
  "type": "object",
  "properties": {
    "act_at": {
      "title": "Act At",
      "type": "string",
      "format": "date-time"
    },
    "act": {
      "title": "Act",
      "type": "string"
    },
    "description": {
      "title": "Description",
      "type": "string"
    },
    "set_token": {
      "title": "Set Token",
      "type": "string"
    },
    "set_token_symbol": {
      "title": "Set Token Symbol",
      "type": "string"
    },
    "set_token_name": {
      "title": "Set Token Name",
      "type": "string"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    },
    "tx_hash": {
      "title": "Tx Hash",
      "type": "string"
    },
    "quote_rate": {
      "title": "Quote Rate",
      "type": "number"
    },
    "quote": {
      "title": "Quote",
      "type": "number"
    },
    "arg1": {
      "title": "Arg1",
      "type": "number"
    },
    "arg2": {
      "title": "Arg2",
      "type": "number"
    }
  },
  "required": [
    "act_at",
    "act",
    "description",
    "set_token",
    "set_token_symbol",
    "set_token_name",
    "logo_url",
    "tx_hash",
    "quote_rate",
    "quote",
    "arg1",
    "arg2"
  ]
}

SetResponse

{
  "title": "SetResponse",
  "type": "object",
  "properties": {
    "address": {
      "title": "Address",
      "type": "string"
    },
    "updated_at": {
      "title": "Updated At",
      "type": "string",
      "format": "date-time"
    },
    "tokensets": {
      "title": "Tokensets",
      "type": "array",
      "items": {
        "$ref": "#/definitions/SetPosition"
      }
    },
    "actions": {
      "title": "Actions",
      "type": "array",
      "items": {
        "$ref": "#/definitions/SetAct"
      }
    }
  },
  "required": [
    "address",
    "updated_at",
    "tokensets",
    "actions"
  ]
}

Get address stacks – Nuo

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/nuo/" 
{
  "data": {
    "nuo": {
      "accounts": [
        {
          "created_at": "2019-10-24T23:23:29",
          "address": "0xWALLET_ADDRESS",
          "balances": [
            {
              "contract_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
              "contract_decimals": 18,
              "contract_name": "Wrapper Ether",
              "contract_ticker_symbol": "WETH",
              "logo_url": "https://logos.covalen...png",
              "balance": "5000000000000000",
              "balance_quote": 0.884,
              "quote_rate": 176.8
            },
            ...
          ]
        }
      ]
    },
    "address": "0xHASH"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user balances on Nuo network.

Field Description
contract_address Address of ERC20 token
contract_name Name of ERC20 token
contract_ticker_symbol Ticker symbol of ERC20 token
contract_decimals Decimals of ERC20 token
logo_url Logo of token
balance_quote Quote of balance in quote-currency units
quote_rate Spot quote rate of token in quote-currency

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

Get address stacks – bZx

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/bzx/" 
{
  "data": {
    "bzx": {
      "balances": [
        {
          "token_address": "0x14094949152eddbfcd073717200da82fed8dc960",
          "token_name": "bZx DAI iToken",
          "token_ticker_symbol": "iDAI",
          "token_decimals": 18,
          "token_balance": "21484570855641261",
          "token_logo_url": "https://www.covalenthq.com/static/images/safekeep/logos/bzx/itokens/itoken_circle_dai.svg",
          "supply_interest_rate": "3.068768612605598189446709511685185134410858154296875",
          "borrow_interest_rate": "11.154626145957575289457963663153350353240966796875",
          "asset_address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
          "asset_name": "Dai Stablecoin v1.0",
          "asset_ticker_symbol": "DAI",
          "asset_decimals": "18",
          "asset_logo_url": "https://logos.covalenthq.com/tokens/0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359.png",
          "token_price": "1.025677211590895421267077836091630160808563232421875",
          "checkpoint_token_price": "1.0255210599100512691705944234854541718959808349609375",
          "asset_balance": "22036234727441149",
          "asset_quote_rate": 1.01,
          "asset_quote": 0.02225659707471556,
          "token_pnl": 3.3548518513238357e-06,
          "asset_pnl": 3.388400369837074e-06
        }
      ]
    },
    "address": "0x5a6d3b6bf795a3160dc7c139dee9f60ce0f00cae"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

Return user positions on bZx protocol.

Field Description
token_address Address of bZx iToken
token_name Name of bZx iToken
token_ticker_symbol Ticker symbol of bZx iToken
token_decimals Decimals of bZx iToken
token_balance Balance of bZx iToken
supply_interest_rate Supply interest rate of bZx iToken
borrow_interest_rate Borrow interest rate of bZx iToken
asset_address Address of underlying asset
asset_name Name of underlying asset
asset_ticker_symbol Ticker Symbol of underlying asset
asset_decimals Decimals of underlying asset
asset_logo_url Logo URL of underlying asset
token_price Current spot price iToken->Asset
checkpoint_token_price Price of iToken at previous balance change
asset_balance Balance in units of asset
asset_quote_rate Spot price of asset balance in quote-currency
asset_quote Value of asset balance in quote-currency
token_pnl Profit and Loss in Token units
asset_pnl Profit and Loss in Asset units

Profit and Loss is calculated as (token_price - checkpoint_token_price(user)) * token_balance and scaled with the appropriate decimals of the iToken and the underlying asset.

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

Get address stacks – iEarn

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/iearn/" 
{
  "data": {
    "balances": [
      {
        "contract_name": "",
        "contract_ticker_symbol": "yBTC",
        "contract_decimals": 8,
        "contract_address": "0x04aa51bbcb46541455ccf1b8bef2ebc5d3787ec9",
        "balance": "20100039",
        "price_per_full_share": "1000779050474924404",
        "logo_url": "https://logos.covalenthq.com/tokens/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599.png",
        "logo_url_secondary": "https://www.covalenthq.com/static/images/safekeep/logos/iearn.png",
        "quote": 1758.1039541076118,
        "quote_rate": 8746.768869988819
      },
      ...
    ]
  }
}

Return user positions on iEarn protocol.

GET parameters

Parameter Default Description
quote-currency optional One of usd, cad, inr, eth, eur. If not specified, use usd.

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/iearn/

JSON Schema

IEarnAct

{
  "title": "IEarnAct",
  "type": "object",
  "properties": {
    "act_at": {
      "title": "Act At",
      "type": "string",
      "format": "date-time"
    },
    "act": {
      "title": "Act",
      "type": "string"
    },
    "amount": {
      "title": "Amount",
      "type": "number"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    },
    "logo_url_secondary": {
      "title": "Logo Url Secondary",
      "type": "string"
    },
    "tx_hash": {
      "title": "Tx Hash",
      "type": "string"
    },
    "contract_address": {
      "title": "Contract Address",
      "type": "string"
    },
    "contract_ticker_symbol": {
      "title": "Contract Ticker Symbol",
      "type": "string"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    },
    "contract_name": {
      "title": "Contract Name",
      "type": "string"
    },
    "description": {
      "title": "Description",
      "type": "string"
    },
    "price_per_full_share": {
      "title": "Price Per Full Share",
      "type": "number"
    },
    "underlying_symbol": {
      "title": "Underlying Symbol",
      "type": "string"
    }
  },
  "required": [
    "act_at",
    "act",
    "amount",
    "logo_url",
    "logo_url_secondary",
    "tx_hash",
    "contract_address",
    "contract_ticker_symbol",
    "contract_decimals",
    "contract_name",
    "description",
    "price_per_full_share",
    "underlying_symbol"
  ]
}

IEarnApr

{
  "title": "IEarnApr",
  "type": "object",
  "properties": {
    "uniapr": {
      "title": "Uniapr",
      "type": "string"
    },
    "capr": {
      "title": "Capr",
      "type": "string"
    },
    "unicapr": {
      "title": "Unicapr",
      "type": "string"
    },
    "iapr": {
      "title": "Iapr",
      "type": "string"
    },
    "uniiapr": {
      "title": "Uniiapr",
      "type": "string"
    },
    "aapr": {
      "title": "Aapr",
      "type": "string"
    },
    "uniaapr": {
      "title": "Uniaapr",
      "type": "string"
    },
    "dapr": {
      "title": "Dapr",
      "type": "string"
    }
  },
  "required": [
    "uniapr",
    "capr",
    "unicapr",
    "iapr",
    "uniiapr",
    "aapr",
    "uniaapr",
    "dapr"
  ]
}

IEarnBalance

{
  "title": "IEarnBalance",
  "type": "object",
  "properties": {
    "contract_name": {
      "title": "Contract Name",
      "type": "string"
    },
    "contract_ticker_symbol": {
      "title": "Contract Ticker Symbol",
      "type": "string"
    },
    "contract_decimals": {
      "title": "Contract Decimals",
      "type": "integer"
    },
    "contract_address": {
      "title": "Contract Address",
      "type": "string"
    },
    "balance": {
      "title": "Balance",
      "type": "string"
    },
    "price_per_full_share": {
      "title": "Price Per Full Share",
      "type": "string"
    },
    "logo_url": {
      "title": "Logo Url",
      "type": "string"
    },
    "logo_url_secondary": {
      "title": "Logo Url Secondary",
      "type": "string"
    },
    "quote": {
      "title": "Quote",
      "type": "number"
    },
    "quote_rate": {
      "title": "Quote Rate",
      "type": "number"
    },
    "apr": {
      "$ref": "#/definitions/IEarnApr"
    },
    "roi_percent": {
      "title": "Roi Percent",
      "type": "number"
    },
    "profit_quote": {
      "title": "Profit Quote",
      "type": "number"
    },
    "underlying_symbol": {
      "title": "Underlying Symbol",
      "type": "string"
    }
  },
  "required": [
    "contract_name",
    "contract_ticker_symbol",
    "contract_decimals",
    "contract_address",
    "balance",
    "price_per_full_share",
    "logo_url",
    "logo_url_secondary",
    "quote",
    "quote_rate",
    "apr",
    "roi_percent",
    "profit_quote",
    "underlying_symbol"
  ]
}

IEarnResponse

{
  "title": "IEarnResponse",
  "type": "object",
  "properties": {
    "balances": {
      "title": "Balances",
      "type": "array",
      "items": {
        "$ref": "#/definitions/IEarnBalance"
      }
    },
    "actions": {
      "title": "Actions",
      "type": "array",
      "items": {
        "$ref": "#/definitions/IEarnAct"
      }
    }
  },
  "required": [
    "balances",
    "actions"
  ]
}

Get address stacks – Aave

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/aave/balances/" 
{
  "data": {
    "address": "0xbdb1be928730dc4dedef5fa4a4b874fc6124f979",
    "updated_at": "2020-03-22T17:10:44.768Z",
    "next_update_at": "2020-03-22T17:15:44.768Z",
    "quote_currency": "USD",
    "aave": {
      "balances": [
        {
          "atoken_contract_address": "0xfc1e690f61efd961294b3e1ce3313fbd8aa4f85d",
          "atoken_contract_ticker_symbol": "aDAI",
          "atoken_contract_name": "Aave Interest bearing DAI",
          "atoken_contract_decimals": 18,
          "atoken_balance": "0",
          "borrow_balance": "11554958043430728",
          "borrow_rate": 0.052609079554348966,
          "liquidity_rate": 0.03934825393976917,
          "origination_fee": "0",
          "peg_contract_decimals": 18,
          "peg_contract_address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
          "peg_contract_ticker_symbol": "DAI",
          "logo_url": "https://www.covalenthq.com/static/images/safekeep/logos/aave/aDAI.svg",
          "quote_rate": 0.997693,
          "quote": 0
        },
        ...
      ]
    }
  }
}

Return user balances on Aave protocol.

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/aave/balances/

Get address stacks – Nexus Mutual

>>> curl "https://api.covalenthq.com/v1/1/address/0xHASH/stacks/nexusmutual/" 
{
  "data": {
    "address": "0xHASH",
    "nexusmutual": {
      "covers": [
        {
          "cid": "21",
          "sc_address": "0x802275979B020F0ec871c5eC1db6e412b72fF20b",
          "sc_name": "Nuo Network",
          "currency_code": "ETH",
          "sum_assured": "30",
          "premium_nxm": "33889831265043490000",
          "cover_period": 365,
          "valid_until": "2020-07-27T21:11:29"
        },
        ...
      ]
    }
  }
}

Return user covers on Nexus Mutual protocol.

HTTP request

GET https://api.covalenthq.com/v1/1/address/0xHASH/stacks/nexusmutual/

JSON Schema

NexusMutualCoverData

{
  "title": "NexusMutualCoverData",
  "type": "object",
  "properties": {
    "cid": {
      "title": "Cid",
      "type": "number"
    },
    "sc_address": {
      "title": "Sc Address",
      "type": "string"
    },
    "sc_name": {
      "title": "Sc Name",
      "type": "string"
    },
    "currency_code": {
      "title": "Currency Code",
      "type": "string"
    },
    "sum_assured": {
      "title": "Sum Assured",
      "type": "number"
    },
    "premium_nxm": {
      "title": "Premium Nxm",
      "type": "number"
    },
    "cover_period": {
      "title": "Cover Period",
      "type": "integer"
    },
    "valid_until": {
      "title": "Valid Until",
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "cid",
    "sc_address",
    "sc_name",
    "currency_code",
    "sum_assured",
    "premium_nxm",
    "cover_period",
    "valid_until"
  ]
}

Historical rates

Get historical DAI/SAI stability fees

>>> curl "https://api.covalenthq.com/v1/1/rates/maker/dai/" 
>>> curl "https://api.covalenthq.com/v1/1/rates/maker/sai/" 
{
  "data": {
    "items": [
      {
        "block_signed_at": "2018-08-30T20:15:01",
        "block_height": 6242497,
        "y": 0.024999994685107794
      },
      ...
    ]
  }
}

Return DAI/SAI stability fees

HTTP request

GET https://api.covalenthq.com/v1/1/rates/maker/dai/

JSON Schema

RateItem

{
  "title": "RateItem",
  "type": "object",
  "properties": {
    "block_signed_at": {
      "title": "Block Signed At",
      "type": "string",
      "format": "date-time"
    },
    "block_height": {
      "title": "Block Height",
      "type": "integer"
    },
    "y": {
      "title": "Y",
      "type": "number"
    }
  },
  "required": [
    "block_signed_at",
    "block_height",
    "y"
  ]
}

Get historical DAI Savings Rate (DSR)

>>> curl "https://api.covalenthq.com/v1/1/rates/maker/dsr/" 
{
  "data": {
    "items": [
      {
        "block_signed_at": "2018-08-30T20:15:01",
        "block_height": 6242497,
        "y": 0.024999994685107794
      },
      ...
    ]
  }
}

Return DAI Savings rate

HTTP request

GET https://api.covalenthq.com/v1/1/rates/maker/dsr/

JSON Schema

RateItem

{
  "title": "RateItem",
  "type": "object",
  "properties": {
    "block_signed_at": {
      "title": "Block Signed At",
      "type": "string",
      "format": "date-time"
    },
    "block_height": {
      "title": "Block Height",
      "type": "integer"
    },
    "y": {
      "title": "Y",
      "type": "number"
    }
  },
  "required": [
    "block_signed_at",
    "block_height",
    "y"
  ]
}

Event log subscriptions

Get event logs by topic(s)

>>> curl "https://api.covalenthq.com/v1/1/subscription/topic/0x454b0172f64812df0cd504c2bd7df7aab8ff328a54d946b4bd0fa7c527adf9cc/" 
{
  "data": {
    "items": [
      {
        "block_signed_at": "2019-04-07T20:42:52",
        "block_height": 7523238,
        "tx_hash": "0x317b302cc3aa6732a11b3dfbd401ec5a6afb5c52b26dee7381b7d92f8cdfaee7",
        "tx_offset": 62,
        "log_offset": 29,
        "raw_log_topics": [
          "0x454b0172f64812df0cd504c2bd7df7aab8ff328a54d946b4bd0fa7c527adf9cc",
          "0x0000000000000000000000007284a8451d9a0e7dc62b3a71c0593ea2ec5c5638",
          "0x0000000000000000000000007284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
        ],
        "raw_log_data": "0x0000000000000000000000005d4a945271fb3e16481bf6ce0bad5f6b2e9d13db",
        "sender_address": "0x498b3bfabe9f73db90d252bcd4fa9548cd0fd981",
        "sender_address_label": null,
        "to_address_label": null,
        "decoded": {
          "name": "Created",
          "data": [
            {
              "name": "sender",
              "type": "address",
              "value": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
            },
            {
              "name": "owner",
              "type": "address",
              "value": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
            },
            {
              "name": "proxy",
              "type": "address",
              "value": "0x5d4a945271fb3e16481bf6ce0bad5f6b2e9d13db"
            }
          ]
        },
        "decoded_contract": {
          "address": "InstaDapp_v2"
        }
      },
      {...}
    ]
  }
}

HTTP request

GET https://api.covalenthq.com/v1/1/subscription/topic/0xTOPICHASH_1,0xTOPICHASH_2/

where you can specify a comma delimited list of event log topics.

GET parameters

Parameter Default Description
starting-block optional Block height to start results. Defaults to genesis block.
ending-block optional Block height to end results. Defaults to the latest available block.
sender-address optional Filter by sender address. Defaults to returning all senders.

Get event logs by address(s)

>>> curl "https://api.covalenthq.com/v1/1/subscription/address/0x498b3bfabe9f73db90d252bcd4fa9548cd0fd981/" 
{
  "data": {
    "items": [
      {
        "block_signed_at": "2019-04-07T20:42:52",
        "block_height": 7523238,
        "tx_hash": "0x317b302cc3aa6732a11b3dfbd401ec5a6afb5c52b26dee7381b7d92f8cdfaee7",
        "tx_offset": 62,
        "log_offset": 29,
        "raw_log_topics": [
          "0x454b0172f64812df0cd504c2bd7df7aab8ff328a54d946b4bd0fa7c527adf9cc",
          "0x0000000000000000000000007284a8451d9a0e7dc62b3a71c0593ea2ec5c5638",
          "0x0000000000000000000000007284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
        ],
        "raw_log_data": "0x0000000000000000000000005d4a945271fb3e16481bf6ce0bad5f6b2e9d13db",
        "sender_address": "0x498b3bfabe9f73db90d252bcd4fa9548cd0fd981",
        "sender_address_label": null,
        "to_address_label": null,
        "decoded": {
          "name": "Created",
          "data": [
            {
              "name": "sender",
              "type": "address",
              "value": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
            },
            {
              "name": "owner",
              "type": "address",
              "value": "0x7284a8451d9a0e7dc62b3a71c0593ea2ec5c5638"
            },
            {
              "name": "proxy",
              "type": "address",
              "value": "0x5d4a945271fb3e16481bf6ce0bad5f6b2e9d13db"
            }
          ]
        },
        "decoded_contract": {
          "address": "InstaDapp_v2"
        }
      },
      {...}
    ]
  }
}

HTTP request

GET https://api.covalenthq.com/v1/1/subscription/address/0xADDRESS_1,0x_ADDRESS_2/

where you can specify a comma delimited list of contract addresses.

GET parameters

Parameter Default Description
starting-block optional Block height to start results. Defaults to genesis block.
ending-block optional Block height or latest to end results. Defaults to the latest available block.
sender-address optional Filter by sender address. Defaults to returning all senders.

Mock Staking Service

URL structure:

Get network info

>>> curl "https://api.covalenthq.com/v1/1/networks/mock/" 

MockNetworkInfo

Field Description
total_staked Total staked tokens (self + delegated)
total_staked_contract_decimals Decimals of staked tokens
current_epoch Current epoch no.
next_epoch Next epoch no.
current_epoch_start_at Current epoch started at
next_epoch_start_at Next epoch starts at
stake_multipliers Stake Multipliers
delegations List of Delegations
schains_count Count of SChains
schains List of SChains
nodes_count Count of nodes
nodes List of Nodes

MockNetworkInfo

{
  "title": "MockNetworkInfo",
  "type": "object",
  "properties": {
    "total_staked": {
      "type": "string"
    },
    "total_staked_contract_decimals": {
      "type": "integer"
    },
    "current_epoch": {
      "type": "integer"
    },
    "next_epoch": {
      "type": "integer"
    },
    "current_epoch_start_at": {
      "type": "string",
      "format": "date-time"
    },
    "next_epoch_start_at": {
      "type": "string",
      "format": "date-time"
    },
    "stake_multipliers": {
      "type": "array",
      "items": {
        "type": "object",
        "id": "urn:jsonschema:com:covalenthq:scout:services:impl:MockStakingService:StakeMultiplier",
        "properties": {
          "months_count": {
            "type": "integer"
          },
          "stake_multiplier": {
            "type": "integer"
          }
        }
      }
    },
    "delegations": {
      "type": "array",
      "items": {
        "type": "object",
        "id": "urn:jsonschema:com:covalenthq:scout:services:impl:MockStakingService:MockDelegationItem",
        "properties": {
          "holder_address": {
            "type": "string",
            "description": "Address of token owner"
          },
          "validator_address": {
            "type": "string",
            "description": "Address of validator"
          },
          "amount": {
            "type": "string",
            "description": "Amount delegated"
          },
          "delegation_period": {
            "type": "integer",
            "description": "Delegation period"
          },
          "created_at": {
            "type": "string",
            "description": "Time of creation",
            "format": "date-time"
          },
          "started_at": {
            "type": "string",
            "description": "Month when a delegation becomes active",
            "format": "date-time"
          },
          "finished_at": {
            "type": "string",
            "description": "First month after a delegation ends",
            "format": "date-time"
          },
          "info": {
            "type": "string",
            "description": "Info"
          }
        }
      }
    },
    "schains_count": {
      "type": "integer"
    },
    "schains": {
      "type": "array",
      "items": {
        "type": "object",
        "id": "urn:jsonschema:com:covalenthq:scout:services:impl:MockStakingService:SChain",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name"
          },
          "owner_address": {
            "type": "string",
            "description": "Owner Address"
          },
          "lifetime": {
            "type": "integer",
            "description": "Lifetime"
          },
          "start_date": {
            "type": "string",
            "description": "Start date",
            "format": "date-time"
          },
          "start_block": {
            "type": "integer",
            "description": "Start block"
          },
          "deposit": {
            "type": "string",
            "description": "Deposit amount"
          }
        }
      }
    },
    "nodes_count": {
      "type": "integer"
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "id": "urn:jsonschema:com:covalenthq:scout:services:impl:MockStakingService:Node",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name"
          },
          "start_block": {
            "type": "integer",
            "description": "Start block"
          },
          "last_reward_date": {
            "type": "string",
            "description": "Last reward date",
            "format": "date-time"
          },
          "validator_id": {
            "type": "integer",
            "description": "Validator ID"
          },
          "status": {
            "type": "string",
            "description": "Status",
            "enum": [
              "ACTIVE",
              "LEAVING",
              "LEFT"
            ]
          }
        }
      }
    }
  }
}

Get all validators

>>> curl "https://api.covalenthq.com/v1/1/networks/mock/staking/validators/" 

MockValidatorItem

{
  "title": "MockValidatorItem",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "required": true
    },
    "address": {
      "type": "string",
      "required": true
    },
    "name": {
      "type": "string",
      "required": true
    },
    "logo_url": {
      "type": "string"
    },
    "description_moniker": {
      "type": "string"
    },
    "description_identity": {
      "type": "string"
    },
    "description_website": {
      "type": "string"
    },
    "description_security_contact": {
      "type": "string"
    },
    "description_details": {
      "type": "string",
      "required": true
    },
    "fee_rate": {
      "type": "number",
      "required": true
    },
    "fee_max_rate": {
      "type": "string"
    },
    "fee_updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "minimum_delegation_amount": {
      "type": "string"
    },
    "delegation_contract_decimals": {
      "type": "integer"
    },
    "accept_new_requests": {
      "type": "boolean"
    },
    "trusted": {
      "type": "boolean"
    },
    "registration_time": {
      "type": "string",
      "format": "date-time"
    },
    "total_staked": {
      "type": "string"
    },
    "total_staked_contract_decimals": {
      "type": "integer"
    }
  }
}

MockValidatorItem

Field Description
id Validator ID
address Validator address
name Validator name
logo_url Validator logo URL
description_moniker Validator description (moniker)
description_identity Validator description (identity)
description_website Validator description (website)
description_security_contact Validator description (security_contact)
description_details Validator description (details)
fee_rate Validator current fee rate (commission)
fee_max_rate Validator max fee rate
fee_updated_at Validator fee updated at
minimum_delegation_amount Minimum delegation amount
delegation_contract_decimals Decimals of delegation token
accept_new_requests Is the Validator accepting new requests?
trusted Is the Validator trusted?
registration_time Validator registration time
total_staked Total validator staked balance (self + delegated)
total_staked_contract_decimals Decimals to format staked balance

Get validator delegations

>>> curl "https://api.covalenthq.com/v1/1/networks/mock/staking/validators/<validator>/delegations/" 

MockDelegationItem

{
  "title": "MockDelegationItem",
  "type": "object",
  "properties": {
    "holder_address": {
      "type": "string"
    },
    "validator_address": {
      "type": "string"
    },
    "amount": {
      "type": "string"
    },
    "delegation_period": {
      "type": "integer"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "type": "string",
      "format": "date-time"
    },
    "finished_at": {
      "type": "string",
      "format": "date-time"
    },
    "info": {
      "type": "string"
    }
  }
}

MockDelegationItem

Field Description
holder_address Address of token owner
validator_address Address of validator
amount Amount delegated
delegation_period Delegation period
created_at Time of creation
started_at Month when a delegation becomes active
finished_at First month after a delegation ends
info Info

Get validator activity

>>> curl "https://api.covalenthq.com/v1/1/networks/mock/staking/validators/<validator>/activity/" 

MockActivityItem

{
  "title": "MockActivityItem",
  "type": "object",
  "properties": {
    "act_at": {
      "type": "string",
      "required": true,
      "format": "date-time"
    },
    "act": {
      "type": "string",
      "required": true,
      "enum": [
        "VALIDATOR_SLASHED",
        "VALIDATOR_REGISTERED",
        "VALIDATOR_WITHDREW_BOUNTY",
        "VALIDATOR_WITHDREW_FEE",
        "VALIDATOR_PAID_BOUNTY",
        "DELEGATOR_LOCKED",
        "DELEGATOR_UNLOCKED",
        "DELEGATION_PROPOSED",
        "DELEGATION_ACCEPTED",
        "UNDELEGATION_REQUESTED",
        "DELEGATION_REQUEST_CANCELED"
      ]
    },
    "description": {
      "type": "string",
      "required": true
    },
    "tx_hash": {
      "type": "string",
      "required": true
    },
    "amount": {
      "type": "string"
    },
    "contract_ticker_symbol": {
      "type": "string"
    },
    "contract_name": {
      "type": "string"
    },
    "contract_decimals": {
      "type": "integer"
    },
    "contract_logo_url": {
      "type": "string"
    },
    "quote_rate": {
      "type": "number"
    },
    "amount_quote": {
      "type": "number"
    }
  }
}

MockActivityItem

Field Description
act_at Timestamp
act Activity
description Activity description
tx_hash Transaction hash
amount Transaction amount (if available)
contract_ticker_symbol Token ticker symbol
contract_name Token name
contract_decimals Token decimals
contract_logo_url Token logo
quote_rate Quote rate of token to fiat
amount_quote Transaction amount, in fiat

Get staking address balances

>>> curl "https://api.covalenthq.com/v1/1/address/<address>/stacks/mock/balances/" 

TokenBalanceItem

{
  "title": "TokenBalanceItem",
  "type": "object",
  "properties": {
    "balance": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "AVAILABLE",
        "DELEGATED",
        "UNBONDING",
        "REWARD",
        "COMMISSION"
      ]
    },
    "balance_quote": {
      "type": "number"
    },
    "quote_rate": {
      "type": "number"
    },
    "contract_decimals": {
      "type": "integer"
    },
    "contract_ticker_symbol": {
      "type": "string"
    },
    "contract_name": {
      "type": "string"
    },
    "logo_url": {
      "type": "string"
    }
  }
}

TokenBalanceItem

Field Description
balance Balance
type Balance type
balance_quote Balance amount, in fiat
quote_rate Quote rate of token to fiat
contract_decimals Number of decimals to format balance
contract_ticker_symbol Token ticker symbol
contract_name Token name
logo_url Token logo URL

Get staking address delegations

>>> curl "https://api.covalenthq.com/v1/1/address/<address>/stacks/mock/delegations/" 

MockDelegationItem

{
  "title": "MockDelegationItem",
  "type": "object",
  "properties": {
    "holder_address": {
      "type": "string"
    },
    "validator_address": {
      "type": "string"
    },
    "amount": {
      "type": "string"
    },
    "delegation_period": {
      "type": "integer"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "type": "string",
      "format": "date-time"
    },
    "finished_at": {
      "type": "string",
      "format": "date-time"
    },
    "info": {
      "type": "string"
    }
  }
}

MockDelegationItem

Field Description
holder_address Address of token owner
validator_address Address of validator
amount Amount delegated
delegation_period Delegation period
created_at Time of creation
started_at Month when a delegation becomes active
finished_at First month after a delegation ends
info Info

Get staking address activity

>>> curl "https://api.covalenthq.com/v1/1/address/<address>/stacks/mock/activity/" 

MockActivityItem

{
  "title": "MockActivityItem",
  "type": "object",
  "properties": {
    "act_at": {
      "type": "string",
      "required": true,
      "format": "date-time"
    },
    "act": {
      "type": "string",
      "required": true,
      "enum": [
        "VALIDATOR_SLASHED",
        "VALIDATOR_REGISTERED",
        "VALIDATOR_WITHDREW_BOUNTY",
        "VALIDATOR_WITHDREW_FEE",
        "VALIDATOR_PAID_BOUNTY",
        "DELEGATOR_LOCKED",
        "DELEGATOR_UNLOCKED",
        "DELEGATION_PROPOSED",
        "DELEGATION_ACCEPTED",
        "UNDELEGATION_REQUESTED",
        "DELEGATION_REQUEST_CANCELED"
      ]
    },
    "description": {
      "type": "string",
      "required": true
    },
    "tx_hash": {
      "type": "string",
      "required": true
    },
    "amount": {
      "type": "string"
    },
    "contract_ticker_symbol": {
      "type": "string"
    },
    "contract_name": {
      "type": "string"
    },
    "contract_decimals": {
      "type": "integer"
    },
    "contract_logo_url": {
      "type": "string"
    },
    "quote_rate": {
      "type": "number"
    },
    "amount_quote": {
      "type": "number"
    }
  }
}

MockActivityItem

Field Description
act_at Timestamp
act Activity
description Activity description
tx_hash Transaction hash
amount Transaction amount (if available)
contract_ticker_symbol Token ticker symbol
contract_name Token name
contract_decimals Token decimals
contract_logo_url Token logo
quote_rate Quote rate of token to fiat
amount_quote Transaction amount, in fiat

Cryptotoken Logos API

We provide a free cryptocurrency logos API for use within your applications. To use it, you simply have to specify the token address (in lowercase) as a path to the Logos API.

Token Name Token Address Image
DAI 0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359
Kyber Network Crystal 0xdd974d5c2e2928dea5f71b9825b8b646686bd200
Bloom 0x107c4504cd79c5d2696ea0030a8dd4e92601b82e
Livepeer Token 0x58b6a8a3302369daec383334672404ee733ab239
Maker 0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2
Wrapped Ether 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2

HTTP request

GET https://logos.covalenthq.com/tokens/<token_address>.png

Errors

The Covalent API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The information requested is hidden for administrators only.
404 Not Found -- The specified information could not be found.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Release Notes

June 2020

Updates

May 2020

Updates

Apr 2020

Updates

Mar 2020

Updates

New integrations

Feb 2020

New integrations

Updates

Jan 2020

New integrations

Updates