The DeFi Score is a framework for evaluating DeFi protocols. Based on factors including smart contract risk, collateralization, and liquidity, the model outputs an easy to understand 0–10 rating.
With the DeFi Score API, developers can programmatically retrieve the individual scores and additional data points which can then be presented to users or integrated into other systems.
Scoring decentralized lending platforms is a continuous process that depends on many variables. This API will conveniently provide scores and metrics of every supported asset and platform. As new data comes online and our model grows, we will introduce new API endpoints allowing for different views of the scores over time and with different parameters.
The API is in an alpha state as we understand the usage statistics and the preferences of our clients. We will make changes accordingly to the feedback until we must respect backwards compatibility.
You can sign up for access to our API at our website.
The DeFi Score API is currently live at this location:
Environment | URL |
---|---|
Production | https://data.api.codefi.network/v0/defi-score |
Breaking changes are assumed at v0
so there is no need for a staging environment.
However, once v1
is available, a staging environment will be stood up to test future modules and interfaces.
Authentication is performed using the OAuth2 Client Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4). Once you have signed up, you will receive a client_id
and client_secret
. Always keep your client_secret
secure. These can be used to generate a bearer token that can be supplied in request headers to authenticate your requests to the API.
In order to generate a bearer token, you should following these steps within your implementation:
client_id
and client_secret
, fetch a bearer token from https://codefi-prod.eu.auth0.com/oauth/token
Authorization
request header to authenticate your requestsexport CLIENT_ID="xxx"
export CLIENT_SECRET="yyy"
# Fetch an access token
export ACCESS_TOKEN=$(curl -s --request POST --url 'https://codefi-prod.eu.auth0.com/oauth/token' --header 'content-type: application/x-www-form-urlencoded' --data "audience=https://api.codefi.network&grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" | python -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')
curl -s -X GET \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-iL \
https://data.api.codefi.network/v0/defi-score/scores
Requests to the API are rate limited to ensure fair usage. Current usage information is provided in response headers to indicate how close to your client is to hitting the rate limit.
Sample headers:
X-RateLimit-Limit-minute: 60
X-RateLimit-Remaining-minute: 39
The scores
resource is available at this location:
Environment | Location |
---|---|
Production | https://data.api.codefi.network/v0/defi-score |
A score contains fields relating to an asset by a platform.
The scores
resource is computed every 6
hours and is cached at 1
hour.
The shape of scores
will grow or shrink depending on the fields that need to be exposed.
We make use of HTTP status codes to communicate the result of the request. These status codes are currently supported:
Status Code | Description |
---|---|
200 |
The response was successful and there scores present. |
400 |
The request was invalid and did not map to our requirements. |
404 |
The resource that was requested was not found. |
429 |
The global rate limiter for the API has been reached, backoff strategy suggested. |
We try to keep the responses minimal, only serving the most important bits to keep response sizes small. The fields of a score are defined as follows:
Field | Description |
---|---|
id |
This is the UUID corresponding to the batch of scores. |
createdOn |
This is the ISO formatted date the scores were computed. |
asset |
This is the string name of asset, usually referred to as the ticker. |
platform |
This is the string name of the platform. |
score |
This is the number value of computed score for the asset on the platform. |
liquidityIndex |
This is the number value representative of the liquidity value. |
collateralIndex |
This is the number value representative of the collateral value. |
centralizationIndex |
This is the number value representative of the centralization weight. |
{
"asset": "string",
"platform": "string",
"metrics": {
"score": "number",
"liquidityIndex": "number",
"collateralIndex": "number"
}
}
Lists all current scores from the latest calcuation.
$ curl -X GET https://data.api.codefi.network/v0/defi-score
[
{
"asset": "{asset}",
"platform": "{platform}",
"metrics": {
"score": "{score}",
"liquidityIndex": "{liquidityIndex}",
"collateralIndex": "{collateralIndex}"
}
},
...
]
List scores by a given platform.
These are the following supported platform strings:
Platform | Description |
---|---|
compound |
https://compound.finance |
dydx |
https://dydx.exchange |
ddex |
https://ddex.io |
fulcrum |
https://fulcrum.trade |
nuo |
https://nuo.network |
curl -X GET https://data.api.codefi.network/v0/defi-score?groupByPlatform={platform}
[
{
"asset": "{asset}",
"platform": "{platform}",
"metrics": {
"score": "{score}",
"liquidityIndex": "{liquidityIndex}",
"collateralIndex": "{collateralIndex}"
}
},
...
]
List scores by a given asset.
These are the following supported asset strings:
Asset | Descriptions |
---|---|
eth |
https://ethereum.org |
dai |
https://makerdao.com |
sai |
https://makerdao.com |
usdc |
https://www.coinbase.com/usdc |
wbtc |
https://www.wbtc.network |
rep |
https://www.augur.net |
zrx |
https://0x.org |
bat |
https://basicattentiontoken.org |
tusd |
https://www.trusttoken.com/trueusd |
usdt |
https://tether.to |
curl -X GET https://data.api.codefi.network/v0/defi-score?groupByAsset={asset}
[
{
"asset": "{asset}",
"platform": "{platform}",
"metrics": {
"score": "{score}",
"liquidityIndex": "{liquidityIndex}",
"collateralIndex": "{collateralIndex}"
}
},
...
]
Retrieve the score of a single asset of a platform, if platform supports it. Simply combining both query parameters allow you to isolate a certain score. Refer to the tables above for supported assets and platforms.
curl https://data.api.codefi.network/v0/defi-score?groupByAsset={asset}&groupByPlatform={platform}
[
{
"asset": "{asset}",
"platform": "{platform}",
"metrics": {
"score": "{score}",
"liquidityIndex": "{liquidityIndex}",
"collateralIndex": "{collateralIndex}"
}
},
...
]
Codefi Inspect is an open source project dedicated to protocol transparency in DeFi.
The inspect
resource is available at this location:
Environment | Location |
---|---|
Production | https://data.api.codefi.network/v0/inspect |
A protocol contains fields relating to a protocol's configuration such as admin keys, governance, audits and oracles. The data is sourced from this Github repo.
The fields of a protocol are defined as follows:
Field | Description |
---|---|
machineName |
The name of the protocol without any formatting |
displayName |
The name of the protocol with formatting |
description |
A short description of the protocol |
audits |
A list of audits that the protocol has received with metadata |
adminTraits |
Information around admin keys such as address, timelock duration and whether the admin key uses a multisig |
Lists the data of all platforms currently supported by Inspect.
$ curl -X GET https://data.api.codefi.network/v0/inspect
[
{
"machineName": "{platform}",
"displayName": "{platform}",
"description": "string",
"audits": [{
"date": "number",
"auditor": "string",
"engineeringWeeks": "number | null",
"public": "boolean",
"notes": "string",
"link": "string",
}],
"adminTraits": [{
"timelockEnabled": "boolean",
"timelockHours": {
"hours": "number"
},
"multisigEnabled": "boolean",
"multisigOf": "string",
"opsecClaimed": "boolean",
"opsecClaimedNote": "string",
"opsecVerified": "boolean",
"opsecVerifiedNote": "string",
"address": "string"
}]
},
...
]