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

get

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

Path parameters

chainIdintegerOptional

Blockchain Id used to filter results to a specific chain

Query parameters

addressstringOptional

Pool address

namestringOptional

Filter by pool name

addressstringOptional

Price Oracle address

orderstringOptional

Array of columns to order results. Default sort is descending. If '+' is prepended to a column it will be sorted ascending.

limitintegerOptional

Limit used for pagination

Default: 20

pageintegerOptional

Page number to fetch

Default: 0

Responses

200

Returns Pool data for all listed pools.

application/json

400

Malformed Query

application/json

get

HTTPcURLJavaScriptPython

GET /pools HTTP/1.1
Host: 
Accept: */*

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

Market Endpoints

get

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

Path parameters

chainIdintegerOptional

Blockchain Id used to filter results to a specific chain

Query parameters

addressstringOptional

Filter by vToken address

symbolstringOptional

Filter by asset symbol

namestringOptional

Filter by asset name

underlyingAddressstringOptional

Filter by underlying address

underlyingNamestringOptional

Filter by underlying name

underlyingSymbolstringOptional

Filter by underlying symbol

orderstringOptional

Array of columns to order results. Default sort is descending. If '+' is prepended to a column it will be sorted ascending.

limitintegerOptional

Limit used for pagination

Default: 20

pageintegerOptional

Page number to fetch

Default: 0

Responses

200

Returns Market data for all listed markets.

application/json

400

Malformed Query

application/json

get

HTTPcURLJavaScriptPython

GET /markets HTTP/1.1
Host: 
Accept: */*

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

get

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.

Path parameters

chainIdintegerOptional

Blockchain Id used to filter results to a specific chain

Query parameters

assetstringOptional

Filter by vToken address

periodstring · enumOptionalDefault: yearPossible values:

Responses

200

Returns historical data for the requested asset.

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /markets/history HTTP/1.1
Host: 
Accept: */*

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

Governance Endpoints

get

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

Path parameters

proposalIdintegerRequired

Proposal Id for fetching a detailed proposal

Responses

200

Proposal vote summary

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /governance/proposals/{proposalId}/voteSummary HTTP/1.1
Host: 
Accept: */*

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

get

Retrieve a summary of an account's voter profile.

Path parameters

addressstringRequired

Account address

Responses

200

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

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /governance/voters/{address}/summary HTTP/1.1
Host: 
Accept: */*

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

get

Retrieve the history of proposals a given account has voted on

Path parameters

addressstringRequired

Account address

Responses

200

Array of proposals in which the given account has voted

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /governance/voters/{address}/history HTTP/1.1
Host: 
Accept: */*

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

get

Query voter accounts ordered by votes.

Query parameters

limitintegerOptional

Limit used for pagination

Default: 20

pageintegerOptional

Page number to fetch

Default: 0

Responses

200

Returns an array of voter accounts ordered by votes

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /governance/voters HTTP/1.1
Host: 
Accept: */*

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

get

Returns paginated array of proposals.

Query parameters

proposalIdintegerOptional

Filter by proposal ID

statestring · enumOptional

Filter by proposal state

Possible values:

orderstringOptional

Array of columns to order results. Default sort is descending. If '+' is prepended to a column it will be sorted ascending.

limitintegerOptional

Limit used for pagination

Default: 20

pageintegerOptional

Page number to fetch

Default: 0

Responses

200

Returns an array of proposals.

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /governance/proposals HTTP/1.1
Host: 
Accept: */*

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

get

Get voter details for a given proposal.

Query parameters

proposalIdintegerOptional

Filter by proposal ID

addressstringOptional

Account address

orderstringOptional

Array of columns to order results. Default sort is descending. If '+' is prepended to a column it will be sorted ascending.

limitintegerOptional

Limit used for pagination

Default: 20

pageintegerOptional

Page number to fetch

Default: 0

Responses

200

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

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /governance/proposals/votes HTTP/1.1
Host: 
Accept: */*

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

get

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

Path parameters

proposalIdintegerRequired

Proposal Id for fetching a detailed proposal

Responses

200

Returns an array of proposals.

application/json

400

Unexpected error

application/json

get

HTTPcURLJavaScriptPython

GET /governance/proposals/{proposalId} HTTP/1.1
Host: 
Accept: */*

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