Introduction

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("https://api.compound.finance/api/v2/account");
// Returns details for given account
fetch("https://api.compound.finance/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
}
TypeKeyDescription
bytesaddresses

List of account addresses to filter on, e.g.: ["0x...", ,"0x..."]

Precisemin_borrow_value_in_eth

Filter for accounts which total outstanding borrows exceeding given amount.

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..." }`

uint32block_number

If provided, API returns data for given block number from our historical data. Otherwise, API defaults to returning the latest information.

uint32block_timestamp

If provided, API returns data for given timestamp from our historical data. Otherwise, API defaults to returning the latest information.

uint32page_size

Number of accounts to include in the response, default is 10 e.g. page_size=10

uint32page_number

Pagination number for accounts in the response, default is 1 e.g. page_number=1

AccountResponse

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

TypeKeyDescription
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" }
}
TypeKeyDescription
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"}
}
TypeKeyDescription
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("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

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
}
TypeKeyDescription
bytesaddresses

List of token addresses to filter on, e.g.: ["0x...", ,"0x..."]

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.

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.

CTokenResponse

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

TypeKeyDescription
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
}
}
TypeKeyDescription
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("https://api.compound.finance/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
}
TypeKeyDescription
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.

TypeKeyDescription
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

Rateexchange_rates

The historical exchange rate

MarketTotal

TypeKeyDescription
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

TypeKeyDescription
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.

TypeKeyDescription
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.

TypeKeyDescription
stringvalue

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