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

addressstring

Pool address

namestring

Filter by pool name

addressstring

Price Oracle address

orderstring

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

limitinteger · default: 20

Limit used for pagination

pageinteger · default: 0

Page number to fetch

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/pools'

200

400

200

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

Returns Pool data for all listed pools.

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

addressstring

Filter by vToken address

symbolstring

Filter by asset symbol

namestring

Filter by asset name

underlyingAddressstring

Filter by underlying address

underlyingNamestring

Filter by underlying name

underlyingSymbolstring

Filter by underlying symbol

orderstring

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

limitinteger · default: 20

Limit used for pagination

pageinteger · default: 0

Page number to fetch

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/markets'

200

400

200

{
  "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
    }
  ]
}

Returns Market data for all listed markets.

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

assetstring

Filter by vToken address

periodstring · enum · default: year

Options: year, month, halfyear

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/markets/history'

200

400

200

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

Returns historical data for the requested asset.

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

proposalIdintegerrequired

Proposal Id for fetching a detailed proposal

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/governance/proposals/{proposalId}/voteSummary'

200

400

200

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

Proposal vote summary

Retrieve a summary of an account's voter profile.

get

/governance/voters/{address}/summary

Path parameters

addressstringrequired

Account address

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/governance/voters/{address}/summary'

200

400

200

{
  "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
    }
  ]
}

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

Retrieve the history of proposals a given account has voted on

get

/governance/voters/{address}/history

Path parameters

addressstringrequired

Account address

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/governance/voters/{address}/history'

200

400

200

{
  "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
    }
  ]
}

Array of proposals in which the given account has voted

Query voter accounts ordered by votes.

get

/governance/voters

Query parameters

limitinteger · default: 20

Limit used for pagination

pageinteger · default: 0

Page number to fetch

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/governance/voters'

200

400

200

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

Returns an array of voter accounts ordered by votes

Returns paginated array of proposals.

get

/governance/proposals

Query parameters

proposalIdinteger

Filter by proposal ID

statestring · enum

Filter by proposal state

Options: 0, 1, 2, 3, 4, 5, 6, 7

orderstring

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

limitinteger · default: 20

Limit used for pagination

pageinteger · default: 0

Page number to fetch

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/governance/proposals'

200

400

200

{
  "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
    }
  ]
}

Returns an array of proposals.

Get voter details for a given proposal.

get

/governance/proposals/votes

Query parameters

proposalIdinteger

Filter by proposal ID

addressstring

Account address

orderstring

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

limitinteger · default: 20

Limit used for pagination

pageinteger · default: 0

Page number to fetch

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/governance/proposals/votes'

200

400

200

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

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

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

get

/governance/proposals/{proposalId}

Path parameters

proposalIdintegerrequired

Proposal Id for fetching a detailed proposal

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/governance/proposals/{proposalId}'

200

400

200

{
  "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"
    }
  ]
}

Returns an array of proposals.