API

The Venus Protocol API providing access to indexed protocol data.

Venus Protocol API provides three 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

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.
Clients will be given adequate time to upgrade to use the next version.
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.
Clients remove the accept-version: next header to avoid receiving unexpected changes.
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.

Versioning (controlled via accept-version header):

stable (default): chainId is required. Returns a paginated list of pools with embedded markets (filtered to isListed: true) and a top-level tokens array of TokenMetadata.
next: chainId is optional; accepts a JSON array string for multi-chain queries (e.g. ["56","1"]). Returns pools grouped by chainId alongside a separately paginated markets list with underlyingTokenMetadata embedded in each market. No top-level tokens field.

Query parameters

addressstringOptional

[both] Filter by pool comptroller address.

namestringOptional

[both] Filter by pool name.

priceOracleAddressstringOptional

[both] Filter by price oracle address.

chainIdstringOptional

[stable] Required. [next] Optional; accepts a JSON array string for multi-chain queries (e.g. ["56","1"]).

orderstringOptional

[both] Columns to sort by. Default is descending. Prepend + for ascending (e.g. +name).

limitintegerOptional

[both] Maximum number of results to return.

Default: 20

pageintegerOptional

[both] Page number for pagination.

Default: 0

Header parameters

accept-versionstring · enumOptional

Selects the API version. stable (default) requires chainId and returns a paginated list with embedded markets and a top-level tokens array. next supports multi-chain queries and returns pools grouped by chainId with markets in a separate paginated block.

Possible values:

Responses

200

Returns Pool data for all listed pools.

application/json

400

Malformed Query

application/json

get

/pools

GET /pools HTTP/1.1
Accept: */*

{
  "limit": 20,
  "page": 0,
  "total": 1,
  "result": [
    {
      "address": "0xfD36E2c2a6789Db23113685031d7F16329158384",
      "chainId": "56",
      "name": "Venus",
      "priceOracleAddress": "0x6592b5DE802159F3E74B2486b091C11a8c9eA9e6",
      "closeFactorMantissa": "500000000000000000",
      "liquidationIncentiveMantissa": "1100000000000000000",
      "minLiquidatableCollateralMantissa": "100000000000000000000",
      "markets": [
        {
          "address": "0xA07c5b74C9B40447a954e1466938b865b6BBea36",
          "chainId": "56",
          "symbol": "vBNB",
          "name": "Venus BNB",
          "isListed": true,
          "supplyRatePerBlock": "1234567890",
          "borrowRatePerBlock": "9876543210",
          "rewardsDistributors": [],
          "pointsDistributions": []
        }
      ]
    }
  ],
  "tokens": [
    {
      "address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
      "chainId": "56",
      "symbol": "WBNB",
      "decimals": 18,
      "tokenPrices": [
        {
          "id": "56-0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c-oracle-0x0000000000000000000000000000000000000001",
          "tokenAddress": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
          "chainId": "56",
          "priceSource": "oracle",
          "priceMantissa": "30000000000000000000000",
          "isPriceInvalid": false,
          "hasErrorFetchingPrice": false
        }
      ]
    }
  ]
}

Market Endpoints

get

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

Versioning (controlled via accept-version header):

stable (default): chainId is required. Response includes a top-level tokens array of TokenMetadata objects. Markets include rewardsDistributors and pointsDistributions.
next: chainId is optional for cross-chain queries. Token metadata is embedded inside each market as underlyingTokenMetadata with nested tokenPrices. Supports accountAddress for Prime APY data. No top-level tokens field.

Query parameters

chainIdstringOptional

[stable] Required. [next] Optional. Blockchain chain ID to filter results.

addressstringOptional

[both] Filter by vToken address.

symbolstringOptional

[both] Filter by asset symbol.

namestringOptional

[both] Filter by asset name.

underlyingAddressstringOptional

[both] Filter by underlying token address.

underlyingNamestringOptional

[both] Filter by underlying token name.

underlyingSymbolstringOptional

[both] Filter by underlying token symbol.

orderstringOptional

[both] Columns to sort by. Default is descending. Prepend + for ascending (e.g. +underlyingName).

limitintegerOptional

[both] Maximum number of results to return.

Default: 20

pageintegerOptional

[both] Page number for pagination.

Default: 0

accountAddressstringOptional

[next only] Account address to embed personalised Prime APY boosts into each market.

Header parameters

accept-versionstring · enumOptional

Selects the API version. stable (default) requires chainId and returns a top-level tokens array. next supports cross-chain queries and embeds token data inside each market as underlyingTokenMetadata.

Possible values:

Responses

200

Returns Market data for all listed markets.

application/json

400

Malformed Query

application/json

get

/markets

GET /markets HTTP/1.1
Accept: */*

{
  "limit": 20,
  "page": 0,
  "total": 1,
  "result": [
    {
      "address": "0xA07c5b74C9B40447a954e1466938b865b6BBea36",
      "chainId": "56",
      "poolComptrollerAddress": "0xfD36E2c2a6789Db23113685031d7F16329158384",
      "symbol": "vBNB",
      "name": "Venus BNB",
      "underlyingAddress": null,
      "underlyingSymbol": "BNB",
      "underlyingDecimal": 18,
      "borrowApy": "2.45",
      "supplyApy": "1.23",
      "borrowApyDecimal": "0.0245",
      "supplyApyDecimal": "0.0123",
      "totalBorrowApyDecimal": "0.0245",
      "totalSupplyApyDecimal": "0.0123",
      "liquidityCents": "100000000",
      "tokenPriceCents": "30000",
      "isListed": true,
      "rewardsDistributors": [],
      "pointsDistributions": []
    }
  ],
  "tokens": [
    {
      "address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
      "chainId": "56",
      "symbol": "WBNB",
      "decimals": 18,
      "tokenPrices": [
        {
          "id": "56-0xbb4c...-oracle-0x...",
          "tokenAddress": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
          "chainId": "56",
          "priceSource": "oracle",
          "priceMantissa": "30000000000000000000000",
          "isPriceInvalid": false,
          "hasErrorFetchingPrice": false
        }
      ]
    }
  ]
}

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.

Query parameters

assetstringRequired

vToken address to fetch history for.

chainIdstringRequired

Chain ID of the network to query history for.

periodstring · enumOptionalDefault: yearPossible values:

Responses

200

Returns historical data for the requested asset.

application/json

400

Unexpected error

application/json

get

/markets/history

GET /markets/history?asset=text&chainId=text HTTP/1.1
Accept: */*

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

get

Returns the total value locked by all markets in the requested chains.

Query parameters

chainIdstringOptional

Comma-separated list of chain IDs to filter results. If omitted, all chains are included.

Responses

200

Returns the TVL data for the requested chains.

application/json

suppliedSumCentsstringOptional

borrowedSumCentsstringOptional

liquiditySumCentsstringOptional

marketCountintegerOptional

poolCountintegerOptional

chainCountintegerOptional

400

Unexpected error

application/json

get

/markets/tvl

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

{
  "suppliedSumCents": "text",
  "borrowedSumCents": "text",
  "liquiditySumCents": "text",
  "marketCount": 1,
  "poolCount": 1,
  "chainCount": 1
}

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

forstringRequired

againststringRequired

abstainstringRequired

totalstringRequired

400

Unexpected error

application/json

get

/governance/proposals/{proposalId}/voteSummary

GET /governance/proposals/{proposalId}/voteSummary HTTP/1.1
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

delegateCountnumberOptional

votesstringOptional

balancestringOptional

delegatesstringOptional

400

Unexpected error

application/json

get

/governance/voters/{address}/summary

GET /governance/voters/{address}/summary HTTP/1.1
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

pagenumberOptional

limitnumberOptional

totalnumberOptional

400

Unexpected error

application/json

get

/governance/voters/{address}/history

GET /governance/voters/{address}/history HTTP/1.1
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

offsetnumberOptional

limitnumberOptional

totalnumberOptional

400

Unexpected error

application/json

get

/governance/voters

GET /governance/voters HTTP/1.1
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

offsetnumberOptional

limitnumberOptional

totalnumberOptional

400

Unexpected error

application/json

get

/governance/proposals

GET /governance/proposals HTTP/1.1
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

offsetnumberOptional

limitnumberOptional

totalnumberOptional

400

Unexpected error

application/json

get

/governance/proposals/votes

GET /governance/proposals/votes HTTP/1.1
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

proposalIdintegerRequired

descriptionstringRequired

createdBlockintegerRequired

createdTxHashstringRequired

createdTimestampintegerRequired

startBlockintegerRequired

startTimestampintegerRequired

cancelBlockinteger · nullableRequired

cancelTxHashstring · nullableRequired

cancelTimestampinteger · nullableRequired

endBlockintegerRequired

endTimestampintegerRequired

queuedBlockinteger · nullableRequired

queuedTxHashstring · nullableRequired

queuedTimestampinteger · nullableRequired

executedBlockinteger · nullableRequired

executedTxHashstring · nullableRequired

executedTimestampinteger · nullableRequired

proposerstringRequired

etaintegerRequired

forVotesstringOptional

againstVotesstringOptional

canceledbooleanOptional

executedbooleanOptional

stateintegerRequired

voterCountintegerOptional

abstainedVotesstringOptional

governorNamestringRequired

proposalTypeintegerOptional

400

Unexpected error

application/json

get

/governance/proposals/{proposalId}

GET /governance/proposals/{proposalId} HTTP/1.1
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"
    }
  ]
}

Last updated 1 month ago

hashtagBase URL

hashtagVersioning

hashtagVersioning Choreography

hashtagPool Endpoints

hashtagMarket Endpoints

hashtagGovernance Endpoints

Base URL

Versioning

Versioning Choreography

Pool Endpoints

Market Endpoints

Governance Endpoints