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.

Pool Endpoints

Returns pool data for all listed pools, optionally filterable by the pool's comptroller address.

GET/pools

Path parameters

chainIdinteger

Blockchain Id used to filter results to a specific chain

Query parameters

Response

200400

Returns Pool data for all listed pools.

Body

application/json

limit*number

page*number

total*number

result*array of object

Request

JavaScriptCurlPython

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

Response

200400

{
  "limit": 0,
  "page": 0,
  "total": 0,
  "result": [
    {
      "chainId": "text",
      "address": "text",
      "name": "text",
      "description": "text",
      "priceOracleAddress": "text",
      "closeFactorMantissa": "text",
      "liquidationIncentiveMantissa": "text",
      "minLiquidatableCollateralMantissa": "text"
    }
  ]
}

Market Endpoints

Returns market data for listed markets, optionally filterable by asset address, name, symbol, underlying address, underlying name or underlying symbol.

GET/markets

Path parameters

chainIdinteger

Blockchain Id used to filter results to a specific chain

Query parameters

Response

200400

Returns Market data for all listed markets.

Body

application/json

limit*number

page*number

total*number

result*array of object

Request

JavaScriptCurlPython

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

Response

200400

{
  "limit": 0,
  "page": 0,
  "total": 0,
  "result": [
    {
      "address": "text",
      "symbol": "text",
      "name": "text",
      "underlyingAddress": "text",
      "underlyingName": "text",
      "underlyingSymbol": "text",
      "underlyingDecimal": 0,
      "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",
      "borrowerCount": 0,
      "supplierCount": 0
    }
  ]
}

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

Path parameters

chainIdinteger

Blockchain Id used to filter results to a specific chain

Query parameters

Response

200400

Returns historical data for the requested asset.

Body

application/json

result*object

Request

JavaScriptCurlPython

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

Response

200400

{
  "result": {
    "asset": "text",
    "updateAt": "text",
    "data": [
      {
        "blockNumber": 0,
        "blockTimestamp": 0,
        "supplyApy": "text",
        "borrowApy": "text",
        "totalSupplyUsd": "text",
        "totalBorrowUsd": "text"
      }
    ]
  }
}

Governance Endpoints

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

GET/governance/proposals/{proposalId}/voteSummary

Path parameters

proposalId*integer

Proposal Id for fetching a detailed proposal

Response

200400

Proposal vote summary

Body

application/json

for*string

against*string

abstain*string

total*string

Request

JavaScriptCurlPython

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

Response

200400

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

Retrieve a summary of an account's voter profile.

GET/governance/voters/{address}/summary

Path parameters

address*string

Account address

Response

200400

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

Body

application/json

delegateCountnumber

votesstring

balancestring

delegatesstring

txsarray of object

Request

JavaScriptCurlPython

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

Response

200400

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

Retrieve the history of proposals a given account has voted on

GET/governance/voters/{address}/history

Path parameters

address*string

Account address

Response

200400

Array of proposals in which the given account has voted

Body

application/json

pagenumber

limitnumber

totalnumber

resultarray of object

Request

JavaScriptCurlPython

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

Response

200400

{
  "page": 0,
  "limit": 0,
  "total": 0,
  "result": [
    {
      "proposalId": 0,
      "description": "text",
      "createdBlock": 0,
      "createdTxHash": "text",
      "createdTimestamp": 0,
      "startBlock": 0,
      "startTimestamp": 0,
      "cancelBlock": 0,
      "cancelTxHash": "text",
      "cancelTimestamp": 0,
      "endBlock": 0,
      "endTimestamp": 0,
      "queuedBlock": 0,
      "queuedTxHash": "text",
      "queuedTimestamp": 0,
      "executedBlock": 0,
      "executedTxHash": "text",
      "executedTimestamp": 0,
      "proposer": "text",
      "eta": 0,
      "forVotes": "text",
      "againstVotes": "text",
      "canceled": false,
      "executed": false,
      "state": 0,
      "voterCount": 0,
      "abstainedVotes": "text",
      "governorName": "text",
      "proposalType": 0
    }
  ]
}

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 object

Request

JavaScriptCurlPython

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

Response

200400

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

Returns paginated array of proposals.

GET/governance/proposals

Query parameters

Response

200400

Returns an array of proposals.

Body

application/json

offsetnumber

limitnumber

totalnumber

resultarray of object

Request

JavaScriptCurlPython

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

Response

200400

{
  "offset": 0,
  "limit": 0,
  "total": 0,
  "result": [
    {
      "proposalId": 0,
      "description": "text",
      "createdBlock": 0,
      "createdTxHash": "text",
      "createdTimestamp": 0,
      "startBlock": 0,
      "startTimestamp": 0,
      "cancelBlock": 0,
      "cancelTxHash": "text",
      "cancelTimestamp": 0,
      "endBlock": 0,
      "endTimestamp": 0,
      "queuedBlock": 0,
      "queuedTxHash": "text",
      "queuedTimestamp": 0,
      "executedBlock": 0,
      "executedTxHash": "text",
      "executedTimestamp": 0,
      "proposer": "text",
      "eta": 0,
      "forVotes": "text",
      "againstVotes": "text",
      "canceled": false,
      "executed": false,
      "state": 0,
      "voterCount": 0,
      "abstainedVotes": "text",
      "governorName": "text",
      "proposalType": 0
    }
  ]
}

Get voter details for a given proposal.

GET/governance/proposals/votes

Query parameters

Response

200400

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

Body

application/json

offsetnumber

limitnumber

totalnumber

resultarray of object

Request

JavaScriptCurlPython

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

Response

200400

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

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

GET/governance/proposals/{proposalId}

Path parameters

proposalId*integer

Proposal Id for fetching a detailed proposal

Response

200400

Returns an array of proposals.

Body

application/json

proposalId*integer

description*string

createdBlock*integer

createdTxHash*string

createdTimestamp*integer

startBlock*integer

startTimestamp*integer

cancelBlock*nullable integer

cancelTxHash*nullable string

cancelTimestamp*nullable integer

endBlock*integer

endTimestamp*integer

queuedBlock*nullable integer

queuedTxHash*nullable string

queuedTimestamp*nullable integer

executedBlock*nullable integer

executedTxHash*nullable string

executedTimestamp*nullable integer

proposer*string

eta*integer

forVotesstring

againstVotesstring

canceledboolean

executedboolean

state*integer

voterCountinteger

abstainedVotesstring

governorName*string

proposalTypeinteger

proposalActions*array of object

Request

JavaScriptCurlPython

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

Response

200400

{
  "proposalId": 0,
  "description": "text",
  "createdBlock": 0,
  "createdTxHash": "text",
  "createdTimestamp": 0,
  "startBlock": 0,
  "startTimestamp": 0,
  "cancelBlock": 0,
  "cancelTxHash": "text",
  "cancelTimestamp": 0,
  "endBlock": 0,
  "endTimestamp": 0,
  "queuedBlock": 0,
  "queuedTxHash": "text",
  "queuedTimestamp": 0,
  "executedBlock": 0,
  "executedTxHash": "text",
  "executedTimestamp": 0,
  "proposer": "text",
  "eta": 0,
  "forVotes": "text",
  "againstVotes": "text",
  "canceled": false,
  "executed": false,
  "state": 0,
  "voterCount": 0,
  "abstainedVotes": "text",
  "governorName": "text",
  "proposalType": 0,
  "proposalActions": [
    {
      "proposalId": 0,
      "actionIndex": 0,
      "target": "text",
      "value": "text",
      "signature": "text",
      "calldata": "text"
    }
  ]
}