Introduction
OverviewServiceAuthenticationRate Limits
API
ScoresInspect Data

Overview

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.

Service

Version Badge

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

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.

Generating a Bearer Token

In order to generate a bearer token, you should following these steps within your implementation:

  1. Using your client_id and client_secret, fetch a bearer token from https://codefi-prod.eu.auth0.com/oauth/token
  2. Store this token in memory, and for each request, check if it has expired, if so, repeat step 1
  3. Use the stored bearer token within the Authorization request header to authenticate your requests

Quickstart

export 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"])')

Access the Defi Score API

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

Rate Limits

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

Scores

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.

Score shape

{
  "asset": "string",
  "platform": "string",
  "metrics": {
    "score": "number",
    "liquidityIndex": "number",
    "collateralIndex": "number"
  }
}

List All Scores

Lists all current scores from the latest calcuation.

GET
/v0/scores

Example request

$ curl -X GET https://data.api.codefi.network/v0/defi-score

Example response

[
  {
    "asset": "{asset}",
    "platform": "{platform}",
    "metrics": {
      "score": "{score}",
      "liquidityIndex": "{liquidityIndex}",
      "collateralIndex": "{collateralIndex}"
    }
  },
  ...
]

List By Platform

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
GET
/v0/scores?groupByPlatform={platform}

Example request

curl -X GET https://data.api.codefi.network/v0/defi-score?groupByPlatform={platform}

Example response

[
  {
    "asset": "{asset}",
    "platform": "{platform}",
    "metrics": {
      "score": "{score}",
      "liquidityIndex": "{liquidityIndex}",
      "collateralIndex": "{collateralIndex}"
    }
  },
  ...
]

List By Asset

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
GET
/v0/scores?groupByAsset={asset}

Example request

curl -X GET https://data.api.codefi.network/v0/defi-score?groupByAsset={asset}

Example response

[
  {
    "asset": "{asset}",
    "platform": "{platform}",
    "metrics": {
      "score": "{score}",
      "liquidityIndex": "{liquidityIndex}",
      "collateralIndex": "{collateralIndex}"
    }
  },
  ...
]

Asset Of Platform

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.

GET
/v0/scores?groupByAsset={asset}&groupByPlatform={platform}

Example request

curl https://data.api.codefi.network/v0/defi-score?groupByAsset={asset}&groupByPlatform={platform}

Example response

[
  {
    "asset": "{asset}",
    "platform": "{platform}",
    "metrics": {
      "score": "{score}",
      "liquidityIndex": "{liquidityIndex}",
      "collateralIndex": "{collateralIndex}"
    }
  },
  ...
]

Inspect Data

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

List All Data

Lists the data of all platforms currently supported by Inspect.

GET
/v0/inspect

Example request

$ curl -X GET https://data.api.codefi.network/v0/inspect

Example response

[
  {
    "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"
    }]
  },
  ...
]
Show examples in:
cURL
DeFi Score API Documentation