App

Compound API

The Compound API input and output formats are specified by Protocol Buffers, known colloquially as protobufs. Unlike typical protobufs endpoints, the Compound endpoints support JSON for input and output in addition to the protobufs binary format. To use JSON in both the input and the output, specify the headers "Content-Type: application/json" and "Accept: application/json" in the request.

Please request an API key from Compound in the #development channel in our Discord. It should be included in the HTTP header compound-api-key. We require separate api keys for staging and production.

Account Service

The Account API retrieves information for various accounts which have interacted with Compound. You can use this API to pull data about a specific account by address, or alternatively, pull data for a list of unhealthy accounts (that is, accounts which are approaching under-collateralization).

// Retreives list of accounts and related supply and borrow balances.
fetch("https://api.compound.finance/api/v2/account");

// Returns details for given account
fetch("https://api.compound.finance/api/v2/account?addresses[]=0x00..");

Account Request

The request to the account API can specify a number filters, such as which addresses to retrieve information about or general health requirements. The following shows an example set of request parameters in JSON:

{
  "addresses": [] // returns all accounts if empty or not included
  "block_number": 0 // returns latest if given 0
  "max_health": { "value": "10.0" }
  "min_borrow_value_in_eth": { "value": "0.002" }
  "page_number": 1
  "page_size": 10
}

bytes addresses List of account addresses to filter on, e.g.: ["0x...", ,"0x..."] [Optional]
Precise min_borrow_value_in_eth Filter for accounts which total outstanding borrows exceeding given amount. [Optional]
Precise max_health Filter for accounts where outstanding borrows divided by collateral value is less than the provided amount. If returned value is less than 1.0, for instance, the account is subject to liquidation. If provided, should be given as `{ "value": "...string formatted number..." }` [Optional]
uint32 block_number If provided, API returns data for given block number from our historical data. Otherwise, API defaults to returning the latest information. [Optional]
uint32 block_timestamp If provided, API returns data for given timestamp from our historical data. Otherwise, API defaults to returning the latest information. [Optional]
uint32 page_size Number of accounts to include in the response, default is 10 e.g. page_size=10 [Optional]
uint32 page_number Pagination number for accounts in the response, default is 1 e.g. page_number=1 [Optional]

Account Response

The account API returns an overall picture of accounts matching the filters on Compound.

Error error If set and non-zero, indicates an error returning data. NO_ERROR = 0 INTERNAL_ERROR = 1 INVALID_PAGE_NUMBER = 2 INVALID_PAGE_SIZE = 3
AccountRequest request The request parameters are echoed in the response.
PaginationSummary pagination_summary For example { "page_number": 1, "page_size": 100, "total_entries": 83, "total_pages": 1, }
float close_factor The portion of an outstanding borrow that can be closed in a liquidation, which is a percentage of the total underlying borrow balance. For example if the close factor is 0.1, then an account in liqudation is liable to have 10% of its borrows liquidated.
float liquidation_incentive The amount of extra collateral that will be seized to incentivize liquidation. For example, an incentive of 1.05 implies that a liquidator will receive a 5% bonus on the exchange of collateral during a liquidation
Account accounts The list of accounts (see Account below) matching the requested filter, with the associated account and cToken data.

Account

This includes a list of cTokens contextualized to each account.

{
  "address": "0xbac065be2e8ca097e9ac924e94af000dd3a5663"
  "health": { "value": "1.07264275673050348990755599431194797431802239523113293682619605751591901" }
  "tokens": [
    {
      "address": "0xf5dce57282a584d2746faf1593d3121fcac444dc"
      "borrow_balance_underlying": {"value": "131.4682716123015"}
      "lifetime_borrow_interest_accrued": {"value": "0.44430505829286"}
      "lifetime_supply_interest_accrued": {"value": "0.0000021671829864899976"}
      "supply_balance_underlying": {"value": "0.0"}
    }
  ],
  "total_borrow_value_in_eth": {"value": "0.5100157047140227313856015174794473200000000000000000000000000000" }
  "total_collateral_value_in_eth": {"value": "0.54706465148029978664135447293587201124121731200000000000000000000000000" }
}

bytes address The public Ethereum address of the account
Precise total_collateral_value_in_eth The value of all collateral supplied by the account. Calculated as cTokens held • exchange rate • collateral factor. Note: assets can be supplied and gain interest without being counted as collateral.
Precise total_borrow_value_in_eth The value of all outstanding borrows with accumulated interest.
Precise health total_collateral_value_in_eth / total_borrow_value_in_eth. If this value is less than 1.0, the account is subject to liquidation.
AccountCToken tokens A list of tokens held by this account, see AccountCToken below for details.

Account CToken

An account's supply, borrow, and interest information for a particular cToken.

{
  "address": "0xf5dce57282a584d2746faf1593d3121fcac444dc"
  "borrow_balance_underlying": {"value": "131.4682716123015"}
  "lifetime_borrow_interest_accrued": {"value": "0.44430505829286"}
  "lifetime_supply_interest_accrued": {"value": "0.0000021671829864899976"}
  "supply_balance_underlying": {"value": "0.0"}
}

bytes address The address of the cToken
string symbol The symbol of the cToken
Precise supply_balance_underlying The cToken balance converted to underlying tokens cTokens held • exchange rate
Precise borrow_balance_underlying The borrow balance (this is denominated in the underlying token, not in cTokens)
Precise lifetime_supply_interest_accrued The amount of supply interest accrued for the lifetime of this account-cToken pair.
Precise lifetime_borrow_interest_accrued The amount of borrow interest accrued for the lifetime of this account-cToken pair.

CToken Service

Note: This service is experimental (alpha) and subject to change.

The CToken API retrieves information for all cTokens. You can use this API to pull data about all cTokens:
// Retreives list all cTokens
fetch("https://api.compound.finance/api/v2/ctoken");

// or return details for a single cToken
fetch("https://api.compound.finance/api/v2/ctoken?addresses[]=0x00..");

CToken Request

The request to the cToken API can specify a number filters, such as which tokens to retrieve information about or moment in time. The following shows an example set of request parameters in JSON:

{
  "addresses": [] // returns all tokens if empty or not included
  "block_timestamp": 0 // returns latest information if given 0
}

bytes addresses List of token addresses to filter on, e.g.: ["0x...", ,"0x..."] [Optional]
uint32 block_number Only one of block_number or block timestamp should be provided. If provided, API returns data for given block number from our historical data. Otherwise, API defaults to returning the latest information. [Optional]
uint32 block_timestamp Only one of block_number or block timestamp should be provided. If provided, API returns data for given block timestamp from our historical data. Otherwise, API defaults to returning the latest information. [Optional]

CToken Response

The cToken API returns an overall picture of cTokens matching the filter.

Error error If set and non-zero, indicates an error returning data. NO_ERROR = 0 INTERNAL_ERROR = 1
CTokenRequest request The request parameters are echoed in the response.
CToken cToken The list of cToken (see CToken below) matching the requested filter.

CToken

This includes a list of cTokens contextualized to the full market.

{
 "cToken": [{
   "borrow_rate": {"value": "0.051453109785093843"},
   "cash": {"value": "514.078443"},
   "collateral_factor": {"value": "0.80000000000000000"},
   "exchange_rate": {"value": "0.020024242770802729"},
   "interest_rate_model_address": "0x1a43bfd39b15dcf444e17ab408c4b5be32deb7f5",
   "name": "Compound USD Coin",
   "number_of_borrowers": 3,
   "number_of_suppliers": 34,
   "reserves": {"value": "0"},
   "supply_rate": {"value": "0.013237112532748109"},
   "symbol": "cUSDC",
   "token_address": "0x5b281a6dda0b271e91ae35de655ad301c976edb1",
   "total_borrows": {"value": "178.064546"},
   "total_supply": {"value": "34565.25157651"},
   "underlying_address": "0x4dbcdf9b62e891a7cec5a2568c3f4faf9e8abe2b",
   "underlying_name": "USD Coin",
   "underlying_price": {"value": "0.0041368287055953530000000000"},
   "underlying_symbol":"USDC"
  }],
 "error": null,
 "request": {
   "addresses": ["0x5b281a6dda0b271e91ae35de655ad301c976edb1"],
   "block_number": 4515576,
   "block_timestamp": 0
  }
}

bytes token_address The public Ethereum address of the cToken
Precise total_supply The number of cTokens in existence
Precise total_borrows The amount of underlying tokens borrowed from the cToken
Precise reserves The amount of underylying tokens held by reserves
Precise cash The current liquidity of the cToken
Precise exchange_rate The cToken / underlying exchange rate. This rate increases over time as supply interest accrues.
Precise supply_rate The floating supply interest rate
Precise borrow_rate The floating borrow interest rate
Precise collateral_factor The amount of the value of the underlying token that will count as collateral. eg. cEth with collataral factor 0.75 means 1 eth of supply allows 0.75 eth of borrowing.
uint32 number_of_suppliers The number of accounts holding this cToken
uint32 number_of_borrowers The number of accounts with oustanding borrows
Precise underlying_price The price of the underlying token in eth
bytes underlying_address The address of the underlying token
string symbol The symbol of the ctoken
string name The name of the ctoken
string underlying_symbol The symbol of the underlying token
string underlying_name The name of the underlying token
bytes interest_rate_model_address The address of the interest rate model

Market History Service

The market history service retrieves historical information about a market. You can use this API to find out the values of interest rates at a certain point in time. Its especially useful for making charts and graphs of the time-series values.

// Returns 10 buckets of market data
fetch("https://api.compound.finance/api/v2/market_history/graph?asset=0xf5dce57282a584d2746faf1593d3121fcac444dc&min_block_timestamp=1556747900&max_block_timestamp=1559339900&num_buckets=10");

Market History Graph Request

The market history graph API returns information about a market between two timestamps. The requestor can choose the asset and number of buckets to return within the range. For example:

{
 "asset": "0xf5dce57282a584d2746faf1593d3121fcac444dc",
 "min_block_timestamp": 1556747900,
 "max_block_timestamp": 1559339900,
 "num_buckets": 10
}

bytes asset The requested asset
uint32 min_block_timestamp Unix epoch time in seconds
uint32 max_block_timestamp Unix epoch time in seconds
uint32 num_buckets How many buckets to group data points in

Market History Graph Response

The market history graph API response contains the rates for both suppliers and borrowers, as well as the sequence of total supply and borrows for the given market.

Error error If set and non-zero, indicates an error returning data. NO_ERROR = 0 INTERNAL_ERROR = 1 INVALID_REQUEST = 2
bytes asset The asset in question
Rate supply_rates The historical interest rates for suppliers
Rate borrow_rates The historical interest rates for borrowers
MarketTotal total_supply_history The historical total supply amounts for the market
MarketTotal total_borrows_history The historical total borrow amounts for the market

Market Total

uint32 block_number The block number of the data point
uint32 block_timestamp The timestamp of the block of the data point
Precise total The total value of the asset in asset-WEI terms.

Rate

uint32 block_number The block number of the data point
uint32 block_timestamp The timestamp of the block of the data point
double rate The rate as a value between 0 and 1

Shared Data Types

Custom data types that are shared between services.

Pagination Summary

Used for paginating results.

uint32 page_number The current page number
uint32 page_size The number of entries to show per page.
uint32 total_entries The number of items matching the request across all pages.
uint32 total_pages The number of pages need to show total_entries at the given page_size.

Precise

For non-negative numbers only.

string value The full UNSIGNED number in string form. max value is 2^257 - 1, aka 231584178474632390847141970017375815706539969331281128078915168015826259279871