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.

AccountService

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("API_BASE_URL/api/v2/account");
// Returns details for given account
fetch("API_BASE_URL/api/v2/account?addresses[]=0x00..");
account

AccountRequest

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
}
bytesaddresses
List of account addresses to filter on, e.g.: ["0x...", ,"0x..."] [Optional]
Precisemin_borrow_value_in_eth
Filter for accounts which total outstanding borrows exceeding given amount. [Optional]
Precisemax_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]
uint32block_number
If provided, API returns data for given block number from our historical data. Otherwise, API defaults to returning the latest information. [Optional]
uint32block_timestamp
If provided, API returns data for given timestamp from our historical data. Otherwise, API defaults to returning the latest information. [Optional]
uint32page_size
Number of accounts to include in the response, default is 10 e.g. page_size=10 [Optional]
uint32page_number
Pagination number for accounts in the response, default is 1 e.g. page_number=1 [Optional]

AccountResponse

The account API returns an overall picture of accounts matching the filters on Compound.
Errorerror
If set and non-zero, indicates an error returning data.
NO_ERROR = 0
INTERNAL_ERROR = 1
INVALID_PAGE_NUMBER = 2
INVALID_PAGE_SIZE = 3
AccountRequestrequest
The request parameters are echoed in the response.
PaginationSummarypagination_summary
For example
{
  "page_number": 1,
  "page_size": 100,
  "total_entries": 83,
  "total_pages": 1,
}
floatclose_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.
floatliquidation_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
Accountaccounts
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" }
}
bytesaddress
The public Ethereum address of the account
Precisetotal_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.
Precisetotal_borrow_value_in_eth
The value of all outstanding borrows with accumulated interest.
Precisehealth
total_collateral_value_in_eth / total_borrow_value_in_eth
. If this value is less than 1.0, the account is subject to liquidation.
int32block_updated
doc-false
AccountCTokentokens
A list of tokens held by this account, see AccountCToken below for details.

AccountCToken

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"}
}
bytesaddress
The address of the cToken
stringsymbol
The symbol of the cToken
Precisesupply_balance_underlying
The cToken balance converted to underlying tokens
cTokens held • exchange rate
Preciseborrow_balance_underlying
The borrow balance (this is denominated in the underlying token, not in cTokens)
Preciselifetime_supply_interest_accrued
The amount of supply interest accrued for the lifetime of this account-cToken pair.
Preciselifetime_borrow_interest_accrued
The amount of borrow interest accrued for the lifetime of this account-cToken pair.

CTokenService

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("API_BASE_URL/api/v2/ctoken");
// or return details for a single cToken
fetch("API_BASE_URL/api/v2/ctoken?addresses[]=0x00..");
ctoken

CTokenRequest

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
}
bytesaddresses
List of token addresses to filter on, e.g.: ["0x...", ,"0x..."] [Optional]
uint32block_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]
uint32block_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]

CTokenResponse

The cToken API returns an overall picture of cTokens matching the filter.
Errorerror
CTokenRequestrequest
The request parameters are echoed in the response.
CTokencToken
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
}
}
bytestoken_address
The public Ethereum address of the cToken
Precisetotal_supply
The number of cTokens in existence
Precisetotal_borrows
The amount of underlying tokens borrowed from the cToken
Precisereserves
The amount of underylying tokens held by reserves
Precisecash
The current liquidity of the cToken
Preciseexchange_rate
The cToken / underlying exchange rate. This rate increases over time as supply interest accrues.
Precisesupply_rate
The floating supply interest rate
Preciseborrow_rate
The floating borrow interest rate
Precisecollateral_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.
uint32number_of_suppliers
The number of accounts holding this cToken
uint32number_of_borrowers
The number of accounts with oustanding borrows
Preciseunderlying_price
The price of the underlying token in eth
bytesunderlying_address
The address of the underlying token
stringsymbol
The symbol of the ctoken
stringname
The name of the ctoken
stringunderlying_symbol
The symbol of the underlying token
stringunderlying_name
The name of the underlying token
bytesinterest_rate_model_address
The address of the interest rate model

MarketHistoryService

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("API_BASE_URL/api/v2/market_history/graph?asset=0xf5dce57282a584d2746faf1593d3121fcac444dc&min_block_timestamp=1556747900&max_block_timestamp=1559339900&num_buckets=10");
get_market_history_graph

MarketHistoryGraphRequest

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
}
bytesasset
The requested asset
uint32min_block_timestamp
Unix epoch time in seconds
uint32max_block_timestamp
Unix epoch time in seconds
uint32num_buckets
How many buckets to group data points in

MarketHistoryGraphResponse

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.
Errorerror
If set and non-zero, indicates an error returning data.
NO_ERROR = 0
INTERNAL_ERROR = 1
INVALID_REQUEST = 2
bytesasset
The asset in question
Ratesupply_rates
The historical interest rates for suppliers
Rateborrow_rates
The historical interest rates for borrowers
MarketTotaltotal_supply_history
The historical total supply amounts for the market
MarketTotaltotal_borrows_history
The historical total borrow amounts for the market

MarketTotal

uint32block_number
The block number of the data point
uint32block_timestamp
The timestamp of the block of the data point
Precisetotal
The total value of the asset in asset-WEI terms.

Rate

uint32block_number
The block number of the data point
uint32block_timestamp
The timestamp of the block of the data point
doublerate
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.

uint32page_number
The current page number
uint32page_size
The number of entries to show per page.
uint32total_entries
The number of items matching the request across all pages.
uint32total_pages
The number of pages need to show total_entries at the given page_size.

Precise

For non-negative numbers only.

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