Multi Collateral Dai API

Welcome to Multi Collateral Dai API documentation. You'll find here all necessary informations that will allow you to pull data from MCD API endpoints.

INTRODUCTION

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

Currently API does not require any authorisation

API endpoints base: http://www.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

ENDPOINTS

get
/last_block

http://www.mcdstate.info/api/last_block
The endpoint takes no parameters and returns the number of the latest synchronised block. Sample request: http://www.mcdstate.info/api/last_block
Request
Response
Request
​
Response
200: OK
Here's how would look a response returned after sending proper request:
{
'Message': {
'last_block': 11077244
}
}

get
/last_time

http://www.mcdstate.info/api/last_time
​The endpoint takes no parameters and returns the timestamp of the latest synchronised block. Sample request: http://www.mcdstate.info/api/last_time
Request
Response
Request
​
Response
200: OK
Response contains the most recent date of dataset update
{
"Message":{
"last_time":"Wed, 04 Nov 2020 14:48:17 GMT"
}
}

get
/vault_history/:id

http://www.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 http://www.mcdstate.info/api/vault_history/1113?format=csv
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:
{
"Message": {
"events": [
{
"block": 8973403,
"block_timestamp": "Thu, 21 Nov 2019 08:30:07 GMT",
"tx_hash": "0x8677dc78bc15ba25990cde5ca9f307e8a98f0a5d7bc2518c55b0d14dd9946f2b",
"vault": "1113",
"ilk": "ETH-A",
"operation": "OPEN",
"collateral": 0.0,
"principal": 0.0,
"fees": 0.0,
"mkt_price": 174.82,
"osm_price": 174.623837,
"rate": 1000808028462588775090221787,
"ratio": 1.5
},
{
"block": 8973403,
"block_timestamp": "Thu, 21 Nov 2019 08:30:07 GMT",
"tx_hash": "0x8677dc78bc15ba25990cde5ca9f307e8a98f0a5d7bc2518c55b0d14dd9946f2b",
"vault": "1113",
"ilk": "ETH-A",
"operation": "DEPOSIT",
"collateral": 0.29,
"principal": 0.0,
"fees": 0.0,
"mkt_price": 174.82,
"osm_price": 174.623837,
"rate": 1000808028462588775090221787,
"ratio": 1.5
},
{
"block": 8973403,
"block_timestamp": "Thu, 21 Nov 2019 08:30:07 GMT",
"tx_hash": "0x8677dc78bc15ba25990cde5ca9f307e8a98f0a5d7bc2518c55b0d14dd9946f2b",
"vault": "1113",
"ilk": "ETH-A",
"operation": "GENERATE",
"collateral": 0.0,
"principal": 30.0,
"fees": 0.0,
"mkt_price": 174.82,
"osm_price": 174.623837,
"rate": 1000808028462588775090221787,
"ratio": 1.5
}

get
/vaults_list

http://www.mcdstate.info/api/vaults_list
The endpoint allows to pull filtered data about current state of all or selected vaults. '/vaults_list' endpoint is featured with simple query language that allows some flexibility with narrowing down the results. To filter data use 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 http://www.mcdstate.info/api/vaults_list?ilk[in]=COMP-A,KNC-A&debt[gt]=0
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":{
"vaults":[
{
"vault":"16021",
"ilk":"COMP-A",
"collateral":164.63643,
"principal":3500.0,
"paid_fees":0.0,
"debt":3503.894733,
"accrued_fees":3.8947330000000875,
"collateralization":395.0687,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":37.2445866492003,
"available_debt":4406.271975258281,
"available_collateral":91.70892528196828,
"owner":"0x2701d55527009a8a9cd706fa6277a8f5e29000c5"
},
{
"vault":"15380",
"ilk":"COMP-A",
"collateral":8.648877,
"principal":350.0,
"paid_fees":0.0,
"debt":350.983724,
"accrued_fees":0.9837239999999952,
"collateralization":207.1908,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":71.0174878195169,
"available_debt":64.56257343381071,
"available_collateral":1.34375822833902,
"owner":"0x646311e92a9d3cd4586d48d56b6ba6e3f19c0f2c"
},
{
"vault":"16354",
"ilk":"COMP-A",
"collateral":10.0,
"principal":300.0,
"paid_fees":0.0,
"debt":300.099383,
"accrued_fees":0.0993829999999889,
"collateralization":280.1771,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":52.51739202500001,
"available_debt":180.36333769057143,
"available_collateral":3.7539507213241077,
"owner":"0x5c118a353158d8a80f153e32163bf55421a3a462"
},
{
"vault":"15935",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":0.018095,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x25d38c668f01e23fdc5195e08a96afca770428c9"
},
{
"vault":"15454",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":0.0,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0xc99e96eeecc892919fa04d627a4aadd6f647eb5d"
},
{
"vault":"15717",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":0.182379,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x25a1ca1946b2302272ca2965587003224b6cf473"
},
{
"vault":"15445",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":0.0,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x8e8ea076df5cf7f8378259d597827d5cb47ec6cc"
},
{
"vault":"15404",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":0.0,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x494bea758b22e3fa87c525e99b47b870dedec744"
},
{
"vault":"15754",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":1.931816,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x7739da1d6a061a1cdcd4cc3f9dbb50fd1d996f6d"
},
{
"vault":"15835",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":0.035646,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x6280fbc65fd56d3c5a9dbf5ed04d1b07cca9348a"
},
{
"vault":"15362",
"ilk":"COMP-A",
"collateral":0.0,
"principal":0.0,
"paid_fees":0.0,
"debt":0.0,
"accrued_fees":0.0,
"collateralization":null,
"osm_price":84.08097612085,
"mkt_price":82.68,
"ratio":1.75,
"liquidation_price":null,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x415178e6c7642238d99f1ece35c4a2bf600e951b"
}
]
}
}

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

http://www.mcdstate.info/api/vault_state/:id
The endpoint allows to pull current state data of a single vault. Sample request: curl http://www.mcdstate.info/api/vault_state/1113
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":{
"status":{
"vault":"15117",
"ilk":"USDC-A",
"collateral":500000.0,
"principal":495049.50495,
"paid_fees":0.0,
"debt":497262.548567,
"accrued_fees":2213.0436170000467,
"collateralization":100.5505,
"osm_price":1.0,
"mkt_price":0.9992,
"ratio":1.01,
"liquidation_price":1.00447034810534,
"available_debt":0.0,
"available_collateral":0.0,
"owner":"0x0000000000000000000000000000000000000001"
}
}
}

get
/collaterals

http://www.mcdstate.info/collaterals
Endpoints returns current state summary for every available collateral. Response returns a list of records representing summary for every collateral. See table below to check definitions of all dimensions. Set 'format' Query Parameter to 'csv' if you'd like to receive CSV encoded response Sample request: curl http://www.mcdstate.info/collaterals CSV encoded response: curl http://www.mcdstate.info/collaterals?format=csv
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":26,
"total_vaults":36,
"locked_value":990908.3442640199,
"total_debt":524954.49745,
"available_debt":237282.6904454,
"available_collateral":763.3255736780083,
"collateralization":1.8876080671323332
},
{
"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":118,
"total_vaults":721,
"locked_value":7699925.711541224,
"total_debt":3383845.2871899973,
"available_debt":1749438.520504148,
"available_collateral":14084137.16793441,
"collateralization":2.2754957919294747
},
{
"collateral":"ETH-A",
"active_vaults":4336,
"total_vaults":13618,
"locked_value":1031831279.0069588,
"total_debt":344202018.6614709,
"available_debt":343685561.5337007,
"available_collateral":1275712.905645862,
"collateralization":2.9977490632377264
},
{
"collateral":"PAXUSD-A",
"active_vaults":12,
"total_vaults":24,
"locked_value":25124130.687059,
"total_debt":23023878.642306,
"available_debt":1938463.7084709804,
"available_collateral":1957848.3455556901,
"collateralization":1.0912206008979661
},
{
"collateral":"TUSD-A",
"active_vaults":46,
"total_vaults":55,
"locked_value":57045045.95539999,
"total_debt":56716217.728875,
"available_debt":172.15831304950498,
"available_collateral":173.87989618,
"collateralization":1.0057977812994674
},
{
"collateral":"USDC-A",
"active_vaults":364,
"total_vaults":1148,
"locked_value":404148003.8086094,
"total_debt":401176070.96796864,
"available_debt":521541.1925310505,
"available_collateral":526756.6044563605,
"collateralization":1.0074080511169823
},
{
"collateral":"LINK-A",
"active_vaults":62,
"total_vaults":85,
"locked_value":13877616.18010229,
"total_debt":4813958.918719002,
"available_debt":3116107.4699108806,
"available_collateral":518438.26528546435,
"collateralization":2.8827865826065535
},
{
"collateral":"LRC-A",
"active_vaults":34,
"total_vaults":45,
"locked_value":1969607.3561810646,
"total_debt":522935.7031480001,
"available_debt":602623.9906561762,
"available_collateral":8364810.072765971,
"collateralization":3.7664426894631644
},
{
"collateral":"COMP-A",
"active_vaults":3,
"total_vaults":11,
"locked_value":15924.400131852382,
"total_debt":5605.242539999999,
"available_debt":3494.414678201362,
"available_collateral":70.38450479193315,
"collateralization":2.8409832434926865
},
{
"collateral":"MANA-A",
"active_vaults":12,
"total_vaults":28,
"locked_value":997193.4101624131,
"total_debt":358908.042861,
"available_debt":210916.76294609316,
"available_collateral":5706302.263582714,
"collateralization":2.7784092053590785
},
{
"collateral":"ZRX-A",
"active_vaults":25,
"total_vaults":51,
"locked_value":201983.98827451593,
"total_debt":81266.178227,
"available_debt":34153.243644151946,
"available_collateral":184752.2050734581,
"collateralization":2.485461881944492
},
{
"collateral":"WBTC-A",
"active_vaults":402,
"total_vaults":746,
"locked_value":219716967.1417537,
"total_debt":106720895.83132903,
"available_debt":39757082.26317345,
"available_collateral":4159.56632674342,
"collateralization":2.0587998763523636
},
{
"collateral":"USDT-A",
"active_vaults":6,
"total_vaults":18,
"locked_value":1176.525453,
"total_debt":691.803371,
"available_debt":93.03352500000001,
"available_collateral":139.55028750000005,
"collateralization":1.7006645274065888
},
{
"collateral":"KNC-A",
"active_vaults":21,
"total_vaults":107,
"locked_value":223866.35345425707,
"total_debt":78428.91791600002,
"available_debt":49494.712629289716,
"available_collateral":119141.33026307705,
"collateralization":2.854385339015201
},
{
"collateral":"USDC-B",
"active_vaults":2,
"total_vaults":24,
"locked_value":227.0,
"total_debt":127.71059100000001,
"available_debt":61.45607566666667,
"available_collateral":73.7472908,
"collateralization":1.7774563426771706
}
]
}
}