API

The Venus Protocol API providing access to indexed protocol data.

Venus Protocol API provides two groups of endpoints

Market Data - Endpoints relating to lending markets

Activity - Endpoints relating to user interactions with markets

Governance - Endpoints providing information about proposals and voter activity

Base URL

The API is available without authentication for testnet and mainnet.

mainnet: https://api.venus.io testnet: https://testnetapi.venus.io

Versioning

Endpoints are versioned using the accept-version header. The values for this header can be stable or next. By default the stable version is returned. When a next version is available, a Warning - 299 header will be added to the stable version with a message of breaking changes. To receive this new version the accept-version header can be set to next.

When the latest next version is made stable and the previous stable version is deprecated, both values for accept-version will return the latest version. Using the next header at this point will add a Warning - 299 header alerting the client to remove accept-version: next to avoid receiving unexpected changes in the future.

Versioning Choreography

These steps describe the process of upgrading endpoints to new versions as they are released

1. A next version is made available, accessible with the accept-version: next header. A Warning - 299 header is added to the stable version with details about breaking changes.

2. Clients will be given adequate time to upgrade to use the next version.

3. The previous stable version will be deprecated, the next version becomes stable and using the accept-version: next header will add a warning to remove the header or use the stable version.

4. Clients remove the accept-version: next header to avoid receiving unexpected changes.

5. The endpoint is now ready to release another version.

Market Endpoints

Returns market data for listed markets, optionally filterable by asset address.

GET/markets/core-pool

Query parameters

Header parameters

Response

200400

Returns Market data for all listed markets.

Body

application/json

limit*number

page*number

total*number

result*array of Market (object)

Request

JavaScriptCurl

const response = await fetch('/markets/core-pool', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "limit": 0,
  "page": 0,
  "total": 0,
  "result": [
    {
      "address": "text",
      "symbol": "text",
      "name": "text",
      "underlyingAddress": "text",
      "underlyingName": "text",
      "underlyingSymbol": "text",
      "borrowerDailyXvsMantissa": "text",
      "supplierDailyXvsMantissa": "text",
      "venusBorrowIndex": "text",
      "venusSupplyIndex": "text",
      "borrowRatePerBlock": "text",
      "supplyRatePerBlock": "text",
      "exchangeRateMantissa": "text",
      "underlyingPriceMantissa": "text",
      "totalBorrowsMantissa": "text",
      "totalSupplyMantissa": "text",
      "cashMantissa": "text",
      "totalReservesMantissa": "text",
      "reserveFactorMantissa": "text",
      "collateralFactorMantissa": "text",
      "borrowApy": "text",
      "supplyApy": "text",
      "borrowXvsApy": "text",
      "supplyXvsApy": "text",
      "borrowXvsApr": "text",
      "supplyXvsApr": "text",
      "liquidityCents": "text",
      "tokenPriceCents": "text",
      "supplyCapsMantissa": "text",
      "borrowCapsMantissa": "text"
    }
  ]
}

Fetch an array of daily snapshots of supply and borrow totals and supply and borrow apy over the previous 365 days for a given asset.

GET/markets/history

Query parameters

Response

200400

Returns historical data for the requested asset.

Body

application/json

result*MarketGraphData (object)

Request

JavaScriptCurl

const response = await fetch('/markets/history', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "result": {
    "asset": "text",
    "updateAt": "text",
    "data": [
      {
        "supplyApy": "text",
        "borrowApy": "text",
        "totalSupplyCents": "text",
        "totalBorrowCents": "text"
      }
    ]
  }
}

Daily rate for XVS rewards

GET/markets/daily-xvs

Response

200400

Returns Daily rate for supply and borrow XVS rewards.

Body

application/json

number

Request

JavaScriptCurl

const response = await fetch('/markets/daily-xvs', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

0

Return total supply by token

GET/markets/{address}/cmc-total-supply

Query parameters

Response

200400500

Return total supply by token

Body

text/html

string

Request

JavaScriptCurl

const response = await fetch('/markets/{address}/cmc-total-supply', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

"text"

Return circulating supply by token

GET/markets/{address}/cmc-circulating-supply

Query parameters

Response

200400500

Return circulating supply by token

Body

text/html

string

Request

JavaScriptCurl

const response = await fetch('/markets/{address}/cmc-circulating-supply', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

"text"

Deprecated

Returns market data for listed markets, optionally filterable by asset address. Filtering by address will be deprecated and is not fully documented.

GET/api/governance/venus

Query parameters

Response

200400

Returns Market data for all listed markets.

Body

application/json

data*GetVenus (object)

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/governance/venus', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "dailyVenus": "text",
    "markets": [
      {
        "address": "text",
        "symbol": "text",
        "name": "text",
        "underlyingAddress": "text",
        "underlyingName": "text",
        "underlyingSymbol": "text",
        "borrowerDailyVenus": "text",
        "supplierDailyVenus": "text",
        "venusBorrowIndex": "text",
        "venusSupplyIndex": "text",
        "borrowRatePerBlock": "text",
        "exchangeRate": "text",
        "underlyingPrice": "text",
        "totalBorrows": "text",
        "totalBorrows2": "text",
        "totalBorrowsUsd": "text",
        "totalSupply": "text",
        "totalSupply2": "text",
        "totalSupplyUsd": "text",
        "cash": "text",
        "totalReserves": "text",
        "reserveFactor": "text",
        "collateralFactor": "text",
        "borrowApy": "text",
        "supplyApy": "text",
        "borrowVenusApy": "text",
        "supplyVenusApy": "text",
        "borrowVenusApr": "text",
        "supplyVenusApr": "text",
        "liquidity": "text",
        "tokenPrice": "text",
        "totalDistributed": "text",
        "totalDistributed2": "text",
        "supplyCaps": "text",
        "borrowCaps": "text"
      }
    ]
  },
  "status": false
}

Activity

Query and paginate transactions.

GET/activity/transactions

Query parameters

Header parameters

Response

200400

Returns paginated queried transactions.

Body

application/json

limit*integer

page*integer

total*integer

result*array of Transaction (object)

Request

JavaScriptCurl

const response = await fetch('/activity/transactions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "result": [
    {
      "category": "vtoken",
      "event": "text",
      "transactionHash": "text",
      "from": "text",
      "to": "text",
      "tokenAddress": "text",
      "blockNumber": "text",
      "timestamp": "text"
    }
  ]
}

Deprecated

Query and paginate transactions.

GET/api/transactions

Query parameters

Header parameters

Response

200400

Returns paginated queried transactions.

Body

application/json

data*object

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/transactions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "result": [
      {
        "category": "vtoken",
        "event": "text",
        "transactionHash": "text",
        "from": "text",
        "to": "text",
        "tokenAddress": "text",
        "blockNumber": "text",
        "timestamp": "text"
      }
    ]
  },
  "status": false
}

Governance Endpoints

Returns paginated array of proposals.

GET/governance/proposals

param

Query parameters

Header parameters

Response

200400

Returns an array of proposals.

Body

application/json

offsetnumber

limitnumber

totalnumber

resultarray of ProposalList (object)

Request

JavaScriptCurl

const response = await fetch('/governance/proposals', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "offset": 0,
  "limit": 0,
  "total": 0,
  "result": [
    {
      "description": "text",
      "createdTxHash": "text",
      "startTxHash": "text",
      "cancelTxHash": "text",
      "endTxHash": "text",
      "queuedTxHash": "text",
      "executedTxHash": "text",
      "proposer": "text",
      "forVotes": "text",
      "againstVotes": "text",
      "canceled": false,
      "executed": false,
      "abstainedVotes": "text",
      "governorName": "text"
    }
  ]
}

Returns paginated array of proposals. It takes an optional array of proposal ids to filter by.

GET/governance/proposals/:id

param

Header parameters

Response

200400

Returns an array of proposals.

Body

application/json

id*integer

description*string

createdBlock*integer

createdTxHash*string

createdTimestamp*integer

startBlock*integer

startTxHash*string

startTimestamp*integer

cancelBlock*integer

cancelTxHash*string

cancelTimestamp*integer

endBlock*integer

endTxHash*string

endTimestamp*integer

queuedBlock*integer

queuedTxHash*string

queuedTimestamp*integer

executedBlock*integer

executedTxHash*string

executedTimestamp*integer

proposer*string

eta*integer

forVotesstring

againstVotesstring

canceledboolean

executedboolean

state*integer

voterCountinteger

abstainedVotesstring

governorName*string

proposalTypeinteger

proposalActions*ProposalAction (object)

Request

JavaScriptCurl

const response = await fetch('/governance/proposals/:id', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "description": "text",
  "createdTxHash": "text",
  "startTxHash": "text",
  "cancelTxHash": "text",
  "endTxHash": "text",
  "queuedTxHash": "text",
  "executedTxHash": "text",
  "proposer": "text",
  "forVotes": "text",
  "againstVotes": "text",
  "canceled": false,
  "executed": false,
  "abstainedVotes": "text",
  "governorName": "text",
  "proposalActions": {
    "target": "text",
    "value": "text",
    "signature": "text",
    "calldata": "text"
  }
}

Get vote summary for a given proposal, includes sums of for, against, abstain and total votes.

GET/governance/proposals/:proposalId/voteSummary

param

Response

200400

Body

application/json

for*string

against*string

abstain*string

total*string

Request

JavaScriptCurl

const response = await fetch('/governance/proposals/:proposalId/voteSummary', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "for": "text",
  "against": "text",
  "abstain": "text",
  "total": "text"
}

Get voter details for a given proposal.

GET/governance/proposals/votes

param

Query parameters

Response

200400

Pagination object with paginated voter activity and a summary of proposal votes.

Body

application/json

offsetnumber

limitnumber

totalnumber

resultarray of Vote (object)

Request

JavaScriptCurl

const response = await fetch('/governance/proposals/votes', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "offset": 0,
  "limit": 0,
  "total": 0,
  "result": [
    {
      "id": "text",
      "address": "text",
      "support": "text",
      "blockNumber": "text",
      "blockTimestamp": "text",
      "votesMantissa": "text",
      "reason": "text"
    }
  ]
}

Query voter accounts ordered by votes.

GET/governance/voters

Query parameters

Response

200400

Returns an array of voter accounts ordered by votes

Body

application/json

offsetnumber

limitnumber

totalnumber

resultarray of VoterAccount (object)

Request

JavaScriptCurl

const response = await fetch('/governance/voters', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "offset": 0,
  "limit": 0,
  "total": 0,
  "result": [
    {
      "id": "text",
      "address": "text",
      "votesMantissa": "text",
      "stakedVotesMantissa": "text"
    }
  ]
}

Retrieve a summary of an account's voter profile.

GET/governance/voters/:address/summary

Query parameters

Header parameters

Response

200400

A summary of an account's voter profile including latest governance transactions.

Body

application/json

delegateCountnumber

votesstring

balancestring

delegatesstring

txsarray of Transaction (object)

Request

JavaScriptCurl

const response = await fetch('/governance/voters/:address/summary', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "delegateCount": 0,
  "votes": "text",
  "balance": "text",
  "delegates": "text",
  "txs": [
    {
      "category": "vtoken",
      "event": "text",
      "transactionHash": "text",
      "from": "text",
      "to": "text",
      "tokenAddress": "text",
      "blockNumber": "text",
      "timestamp": "text"
    }
  ]
}

Deprecated

Returns paginated array of proposals. It takes an optional array of proposal ids to filter by.

GET/api/proposals

Query parameters

Response

200400

Returns an array of proposals.

Body

application/json

data*object

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/proposals', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "offset": 0,
    "limit": 0,
    "total": 0,
    "result": [
      {
        "description": "text",
        "actions": [],
        "createdTxHash": "text",
        "startTxHash": "text",
        "cancelTxHash": "text",
        "endTxHash": "text",
        "queuedTxHash": "text",
        "executedTxHash": "text",
        "proposer": "text",
        "forVotes": "text",
        "againstVotes": "text",
        "canceled": false,
        "executed": false,
        "state": "Pending",
        "abstainedVotes": "text",
        "governorName": "text",
        "proposalType": "Normal",
        "createdAt": "text",
        "updatedAt": "text"
      }
    ]
  },
  "status": false
}

Returns details for a single proposal.

GET/api/proposals/:id

param

Response

200400

Returns a detailed proposal.

Body

application/json

data*ProposalV1 (object)

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/proposals/:id', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "description": "text",
    "actions": [],
    "createdTxHash": "text",
    "startTxHash": "text",
    "cancelTxHash": "text",
    "endTxHash": "text",
    "queuedTxHash": "text",
    "executedTxHash": "text",
    "proposer": "text",
    "forVotes": "text",
    "againstVotes": "text",
    "canceled": false,
    "executed": false,
    "state": "Pending",
    "abstainedVotes": "text",
    "governorName": "text",
    "proposalType": "Normal",
    "createdAt": "text",
    "updatedAt": "text"
  },
  "status": false
}

Get voter details for a given proposal.

GET/api/voters/:id

param

Response

200400

Pagination object with paginated voter activity and a summary of proposal votes.

Body

application/json

data*object

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/voters/:id', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "offset": 0,
    "limit": 0,
    "total": 0,
    "result": [
      {
        "id": "text",
        "address": "text",
        "hasVoted": "text",
        "support": "text",
        "blockNumber": "text",
        "blockTimestamp": "text",
        "votes": "text",
        "reason": "text"
      }
    ],
    "sumVotes": {
      "for": "text",
      "against": "text",
      "abstain": "text",
      "total": "text"
    }
  },
  "status": false
}

Query voter accounts ordered by vote weight.

GET/api/voters/accounts

Query parameters

Response

200400

Returns an array of voter accounts ordered by vote weight

Body

application/json

data*object

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/voters/accounts', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "offset": 0,
    "limit": 0,
    "total": 0,
    "result": [
      {
        "address": "text",
        "createdAt": "text",
        "id": "text",
        "updatedAt": "text",
        "votes": "text",
        "votes2": "text"
      }
    ]
  },
  "status": false
}

Retrieve a summary of an account's voter profile.

GET/api/voters/accounts/:address

Query parameters

Response

200400

A summary of an account's voter profile including latest XVS transfers and governance transactions.

Body

application/json

data*object

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/voters/accounts/:address', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "delegateCount": 0,
    "votes": "text",
    "balance": "text",
    "delegates": "text",
    "txs": [
      {
        "id": "text",
        "from": "text",
        "to": "text",
        "amount": "text",
        "blockNumber": "text",
        "blockTimestamp": "text",
        "transactionHash": "text",
        "transactionIndex": "text",
        "logIndex": "text"
      }
    ]
  },
  "status": false
}

Returns an array of voter activity for a specified account.

GET/api/voters/history/:address

Query parameters

Response

200400

Paginated response of an account's voter history.

Body

application/json

data*object

status*boolean

Request

JavaScriptCurl

const response = await fetch('/api/voters/history/:address', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "data": {
    "offset": 0,
    "limit": 0,
    "total": 0,
    "result": [
      {
        "id": "text",
        "from": "text",
        "to": "text",
        "amount": "text",
        "blockNumber": "text",
        "blockTimestamp": "text",
        "transactionHash": "text",
        "transactionIndex": "text",
        "logIndex": "text"
      }
    ]
  },
  "status": false
}