Multi Collateral Dai Vault Tracker API Documentation

Multi Collateral Dai Vault Tracker API documentation.

INTRODUCTION

Access to this version of the Multi Collateral Dai Vault Tracker is provided under a Beta Program which is described in the Welcome section of the documentation. Access to the Beta Program is under the Terms of Service described in the Legal section of the documentation.

Please read through all sections of the documentation before using the API. In particular we draw your attention to the following:

  • The Beta Program is of limited duration - it may be suspended or ended at any time, but we will endeavour to give registered participants of the Beta Program as much notice as is reasonably possible before the Beta Program is wound down;

  • As with all Betas, the API and underlying dataset and technology are still in development, therefore you can expect to experience bugs, errors, and partial or complete loss of service at any time during the Beta Program. As such you should treat the API and data as being in development and should not use them for any purpose other than testing and providing feedback during the Beta Program;

  • As described in the API documentation below, the data is not live to the latest block. Since the data is processed before it is made available via the API, the data is typically multiple blocks behind the actual latest block on the public Ethereum blockchain. Users of the API can identify the latest block in the dataset using /last_block and should verify this against the current latest block via their preferred means (block explorer, node etc.) to understand how far behind the tip of the chain the data via API is;

  • The dataset includes only information that has been drawn from the public Ethereum blockchain - no additional data is added - it is just processed for easier access. This means that data particularly in relation to recent blocks may be subject to change e.g. due to chain reorganizations.

API ENDPOINTS

API endpoints accept GET requests only. In the next sections of this documentation you will find all the details concerning pulling data from every available endpoint. Some endpoints may take Query String parameters or Path Parameters (or both).

API endpoints base: https://beta.mcdstate.info/api/​

All endpoints return JSON responses. Some endpoints may return response in CSV format. This feature is available for all endpoints that accept 'format' Query String parameter

AUTHORIZATION

Every request should be authorized with an access token. To get an access token, please complete the registration form here:

As explained in the Welcome section of this GitBook, in order to register for the Beta Program users must read and accept the Terms of Service and Privacy Policy and must enter their email address to receive their access token and also to receive technical updates and notice of the Beta Program’s wind-down.

There are two ways of authorizing requests.

The first method is to use bearer authentication. To authorize the request, pass the access token as 'Authorization' header value with 'Bearer' prefix.

curl -X GET https://beta.mcdstate.info/api/last_block -H 'Authorization: Bearer <access_token>'

The second way is to simply pass the authorization token as a value of 'access_token' query string parameter.

curl -X GET https://beta.mcdstate.info/api/last_block?access_token=<access_token>

RESPONSES

Properly sent GET request to any available endpoint will result in an HTTP 200 response containing 'message' and 'status' fields.

'Message' contains a key - value pair, which hopefully embodies a set of data that matches your request.

'Status' possible values are: 'success' and 'failure'. If 'success', then the data in 'message' is correct. Otherwise, there was a problem related to the database connection or the request was improperly configured. In the 'message' value you will find more details about the cause of the failure.

ENDPOINTS

get
/last_block

https://beta.mcdstate.info/api/last_block
The endpoint takes no parameters and returns the number of the latest synchronised block. Sample request: curl -X GET https://beta.mcdstate.info/api/last_block -H 'Authorization: Bearer <access_token>'
Request
Response
Request
​
Response
200: OK
Here's how would look a response returned after sending proper request:
{
"message": {
"last_block": 11366838
},
"status": "success"
}

get
/last_time

https://beta.mcdstate.info/api/last_time
​The endpoint takes no parameters and returns the timestamp of the latest synchronised block. Sample request: curl -X GET https://beta.mcdstate.info/api/last_time -H 'Authorization: Bearer <access_token>'
Request
Response
Request
​
Response
200: OK
Response contains the most recent date of dataset update
{
"message": {
"last_time": "Tue, 01 Dec 2020 13:05:46 GMT"
},
"status": "success"
}

get
/vault_history/:id

https://beta.mcdstate.info/api/vault_history/:id
The endpoint returns all events emitted for provided vault's <id>. Using 'format' Query String parameter and setting its value to 'csv' provides CSV encoded response. Sample request: curl -X GET https://beta.mcdstate.info/api/vault_history/1113?format=csv -H 'Authorization: Bearer <access_token>'
Request
Response
Request
Path Parameters
id
required
string
Vault's id (number in case of vaults created by MCD Manager, first 10 chars of urn id in case of other vaults, 'MIGRATION' in case of special SAI -> DAI migration vault)
Query Parameters
format
optional
string
If Query Parameter 'format' is provided and set to 'csv', the response will be returned in a CSV format
Response
200: OK
Response example:
​

get
/vaults_list

https://beta.mcdstate.info/api/vaults_list
The endpoint allows pulling of filtered data about current state of all or selected vaults. '/vaults_list' endpoint is featured with simple query language that allows some flexibility in narrowing down the results. To filter data use the following pattern to create multiple Query String parameters of request (all filters are joined with an AND logical operator): Pattern: dim[operator]=value Check out 'dimensions' table below to see available dimensions. Check out 'operators' table below to see available operators. Example No 1: ?debt[gt]=0 Example No 2: ?ilk[in]=COMP-A,ETH-A Sample request: curl -X GET https://beta.mcdstate.info/api/vaults_list?ilk[in]=COMP-A,KNC-A&debt[gt]=0 -H 'Authorization: Bearer <access_token>'
Request
Response
Request
Query Parameters
format
optional
string
If Query Parameter 'format' is provided and set to 'csv', the response will be returned in a CSV format.
dim[operator]
optional
string
Multiple filters.
Response
200: OK
In the response you'll find a list of vaults (in current state) that match given criteria
{
"message": {
"vault_history": [
{
"vault": "14267",
"ilk": "USDC-A",
"block": 10819483,
"timestamp": "Tue, 08 Sep 2020 06:53:31 GMT",
"tx_hash": "0xaf028ec4d05f4980bce7406374de0dedad5224e11fa5bc5d0d32e89efe184363",
"operation": "OPEN",
"dcollateral": 0.0,
"dprincipal": 0.0,
"dfees": 0.0,
"mkt_price": 1.0027,
"osm_price": 1.0,
"dart": 0,
"rate": 1020880755653663594957744796,
"ratio": 1.1
},
{
"vault": "14267",
"ilk": "USDC-A",
"block": 10819483,
"timestamp": "Tue, 08 Sep 2020 06:53:31 GMT",
"tx_hash": "0xaf028ec4d05f4980bce7406374de0dedad5224e11fa5bc5d0d32e89efe184363",
"operation": "DEPOSIT",
"dcollateral": 50000.0,
"dprincipal": 0.0,
"dfees": 0.0,
"mkt_price": 1.0027,
"osm_price": 1.0,
"dart": 0,
"rate": 1020880755653663594957744796,
"ratio": 1.1
}
]
},
"status": "success"
}

DIMENSIONS

Dimension

Type

Definition

vault

string

Vault id

urn

string

Vault urn handler

ilk

string

Collateral name

collateral

numeric

Collateral amount locked in contract

art

numeric

Total art value

debt

numeric

Total DAI debt

principal

numeric

Principal DAI debt (debt without fees)

accured_fees

numeric

Accrued DAI fees

paid_fees

numeric

Already paid fees (not included in debt)

collateralization

numeric

Current collateralization ratio

osm_price

numeric

Oracle Security Module collateral price (USD)

mkt_price

numeric

Collateral market price (USD)

ratio

numeric

Minimal collateralization ratio

liquidation_price

numeric

Collateral liquidation price

available_collateral

numeric

Collateral available to withdraw

available_debt

numeric

Debt available to generate (DAI)

owner

string

Owner's address

block_created

number

Vault's creation block

OPERATORS

Operator

Definition

Usage

gte

greater than or equal

collateral[gte]=5000

gt

greater than

debt[gt]=10000

eq

equal

ilk[eq]=ETH-A

neq

not equal

ilk[neq]=ETH-A

lt

lower than

collateralization[lt]=150

lte

lower than or equal

collateralization[lte]=150

in

in

ilk[in]=ETH-A,COMP-A

get
/vault_state/:id

https://beta.mcdstate.info/api/vault_state/:id
The endpoint allows you to pull current state data of a single vault. Sample request: curl -X GET https://beta.mcdstate.info/api/vault_state/1113 -H 'Authorization: Bearer <access_token>'
Request
Response
Request
Path Parameters
id
required
string
Vault's id
Response
200: OK
Response contains all vaults parameters and their up to date values
{
"message": {
"vault_state": {
"vault": "14267",
"urn": "0xd8c92e30a89352947a852b01225e7b59d11edc49",
"ilk": "USDC-A",
"collateral": 45185149.730555,
"principal": 44725450.20639,
"paid_fees": 0.0,
"art": 43795495390730982824136689,
"debt": 45090222.424174,
"accrued_fees": 364772.2177840024,
"collateralization": 100.2105,
"osm_price": 1.0,
"mkt_price": 1.001,
"ratio": 1.01,
"liquidation_price": 1.007878139609661,
"available_debt": 0.0,
"available_collateral": 0.0,
"owner": "0xfab90d837b82ec306257115c022a624049d2ec21",
"block_created": 10819483
}
},
"status": "success"
}

get
/collaterals

https://beta.mcdstate.info/api/collaterals
Endpoints returns current state summary for every available collateral. The response returns a list of records representing a summary for every collateral. See the table below to check the definitions of all dimensions. Set 'format' Query Parameter to 'csv' if you'd like to receive CSV encoded response Sample request: curl https://beta.mcdstate.info/api/collaterals CSV encoded response: curl -X GET https://beta.mcdstate.info/api/collaterals?format=csv -H 'Authorization: Bearer <access_token>'
Request
Response
Request
Query Parameters
format
optional
string
If Query Parameter is provided and set to 'csv', the response will be returned in a CSV format.
Response
200: OK
In the response you'll find a list of records containing detailed data for every collateral
{
"message": {
"collaterals": [
{
"collateral": "ETH-B",
"active_vaults": 104,
"total_vaults": 152,
"locked_value": 20990422.25138308,
"total_debt": 9439819.905101996,
"available_debt": 6706658.74980806,
"available_collateral": 14087.570286723772,
"collateralization": 2.2236041007560177
},
{
"collateral": "SAI",
"active_vaults": 0,
"total_vaults": 1,
"locked_value": 0.0,
"total_debt": 0.0,
"available_debt": 0,
"available_collateral": 0.0,
"collateralization": null
},
{
"collateral": "BAT-A",
"active_vaults": 117,
"total_vaults": 726,
"locked_value": 9144169.504828904,
"total_debt": 2942114.0802200027,
"available_debt": 3153998.922999265,
"available_collateral": 18904826.11628261,
"collateralization": 3.10802683223797
},
{
"collateral": "ETH-A",
"active_vaults": 4305,
"total_vaults": 14262,
"locked_value": 1545164288.732074,
"total_debt": 405205900.4256772,
"available_debt": 624908137.0558647,
"available_collateral": 1514586.122871281,
"collateralization": 3.813281808356806
},
{
"collateral": "PAXUSD-A",
"active_vaults": 11,
"total_vaults": 24,
"locked_value": 20346930.687059,
"total_debt": 20260273.446426,
"available_debt": 24319.21443083193,
"available_collateral": 24562.406575140005,
"collateralization": 1.004277199953009
},
{
"collateral": "TUSD-A",
"active_vaults": 37,
"total_vaults": 55,
"locked_value": 51338253.29073598,
"total_debt": 51206348.87672198,
"available_debt": 68.13019234653464,
"available_collateral": 68.81149427000003,
"collateralization": 1.0025759386659565
},
{
"collateral": "USDC-A",
"active_vaults": 342,
"total_vaults": 1194,
"locked_value": 416138574.2347536,
"total_debt": 414070945.1285502,
"available_debt": 473253.68895994045,
"available_collateral": 477986.2258495414,
"collateralization": 1.0049934175061752
},
{
"collateral": "LINK-A",
"active_vaults": 96,
"total_vaults": 141,
"locked_value": 22060141.081834346,
"total_debt": 5673949.3143770015,
"available_debt": 6931845.589528339,
"available_collateral": 836959.06023877,
"collateralization": 3.8879693595318177
},
{
"collateral": "LRC-A",
"active_vaults": 33,
"total_vaults": 49,
"locked_value": 2632399.9618963134,
"total_debt": 605293.1154440001,
"available_debt": 898935.4342110361,
"available_collateral": 7892726.431846063,
"collateralization": 4.348967293251587
},
{
"collateral": "COMP-A",
"active_vaults": 7,
"total_vaults": 16,
"locked_value": 32617.738548579,
"total_debt": 12554.616909000002,
"available_debt": 6084.090833045138,
"available_collateral": 93.52737728586182,
"collateralization": 2.598067211847491
},
{
"collateral": "MANA-A",
"active_vaults": 11,
"total_vaults": 29,
"locked_value": 1371484.0625326468,
"total_debt": 371613.24614400003,
"available_debt": 412091.93244608387,
"available_collateral": 8098500.11157936,
"collateralization": 3.690622109851265
},
{
"collateral": "YFI-A",
"active_vaults": 97,
"total_vaults": 102,
"locked_value": 55912785.74470478,
"total_debt": 19999489.538003013,
"available_debt": 11950673.744685436,
"available_collateral": 779.713360107258,
"collateralization": 2.795710642437116
},
{
"collateral": "BAL-A",
"active_vaults": 4,
"total_vaults": 8,
"locked_value": 160408.88970529338,
"total_debt": 53136.586758000005,
"available_debt": 38525.63593073908,
"available_collateral": 4586.565854335833,
"collateralization": 3.018803041223624
},
{
"collateral": "GUSD-A",
"active_vaults": 1,
"total_vaults": 2,
"locked_value": 700.0,
"total_debt": 550.016247,
"available_debt": 143.05305993069305,
"available_collateral": 144.48359053000001,
"collateralization": 1.2726896774742
},
{
"collateral": "ZRX-A",
"active_vaults": 29,
"total_vaults": 56,
"locked_value": 292636.8578237236,
"total_debt": 92502.21999,
"available_debt": 74718.8416235563,
"available_collateral": 301284.34445316717,
"collateralization": 3.163565780965681
},
{
"collateral": "WBTC-A",
"active_vaults": 454,
"total_vaults": 904,
"locked_value": 343753911.6722163,
"total_debt": 125121382.11710489,
"available_debt": 104047892.33103958,
"available_collateral": 7993.994893704936,
"collateralization": 2.7473634470444597
},
{
"collateral": "USDT-A",
"active_vaults": 8,
"total_vaults": 26,
"locked_value": 2326.5254529999997,
"total_debt": 1086.607436,
"available_debt": 464.40953266666656,
"available_collateral": 696.6142989999998,
"collateralization": 2.1410910471626847
},
{
"collateral": "KNC-A",
"active_vaults": 20,
"total_vaults": 110,
"locked_value": 479949.85310443427,
"total_debt": 127458.19213899999,
"available_debt": 146798.86677781964,
"available_collateral": 245089.53273526736,
"collateralization": 3.76554731437759
},
{
"collateral": "USDC-B",
"active_vaults": 3,
"total_vaults": 30,
"locked_value": 462.0,
"total_debt": 331.490505,
"available_debt": 57.776693333333334,
"available_collateral": 69.332032,
"collateralization": 1.393705077616024
}
]
},
"status": "success"
}

PROVIDING FEEDBACK

We welcome feedback from users on this Beta product. We will occasionally request feedback from all registered participants of the Beta Program, and you can contact us directly at info@tokenflow.live.

​