Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API

The Venus Protocol API providing access to indexed protocol data.

The Venus Protocol API exposes indexed lending-market, pool, and governance data. The OpenAPI specification embedded below currently documents two endpoint families:

  • Market and pool data — listed markets, pool configuration, historical market snapshots, and aggregate TVL

  • Governance data — proposals, votes, and voter activity

API responses are derived from indexed data and can lag the chain, omit a recent event, or temporarily fail. Do not treat them as authoritative for transaction simulation, balances, permissions, market pause state, prices, or liquidation safety. Read the relevant contracts through an RPC endpoint at a recorded block when correctness depends on live state.

The live Swagger playground and OpenAPI JSON are the source of truth for the currently published request parameters and response schemas. The checked-in specification rendered on this page is a snapshot and should be resynchronized when the live JSON changes.

Base URL

The documented read endpoints are available without authentication at these origins. Endpoint paths are appended directly to the origin; there is no /api prefix.

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

For example, a BNB Chain mainnet request to the default stable pools route is:

curl --get 'https://api.venus.io/pools' \
  --data-urlencode 'chainId=56'

Versioning

Routes that declare the accept-version request header support stable and next. Omitting the header selects stable; an unsupported value is rejected. Do not assume every API route is versioned—check the OpenAPI entry for the specific path.

stable and next can have different required query parameters and response shapes. In the published specification, this is material for /markets and /pools; read the schema for the selected version instead of deserializing both as the same object.

The current stable responses for those routes include an HTTP Warning: 299 header instructing clients to migrate to accept-version: next. Test the next schema before switching and monitor response warnings during every rollout:

When next is promoted, the server can make both header values resolve to the newly stable implementation and warn clients to remove accept-version: next. Removing that opt-in after promotion avoids silently receiving a later preview. Pin client expectations with contract tests; the header name is not a permanent schema version identifier.

This page was checked against the live v1.73.0 specification. Live service behavior and the live OpenAPI document take precedence over the checked-in snapshot rendered below.

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
400

Malformed Query

application/json
errorstringRequired
get/pools
GET /pools HTTP/1.1
Accept: */*

{
  "error": "text"
}

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
400

Malformed Query

application/json
errorstringRequired
get/markets
GET /markets HTTP/1.1
Accept: */*

{
  "error": "text"
}
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
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/markets/history
GET /markets/history?asset=text&chainId=text HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}
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
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/markets/tvl
GET /markets/tvl HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}

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
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/governance/proposals/{proposalId}/voteSummary
GET /governance/proposals/{proposalId}/voteSummary HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}
get

Retrieve a summary of an account's voter profile.

Path parameters
addressstringRequired

Account address

Responses
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/governance/voters/{address}/summary
GET /governance/voters/{address}/summary HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}
get

Retrieve the history of proposals a given account has voted on

Path parameters
addressstringRequired

Account address

Responses
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/governance/voters/{address}/history
GET /governance/voters/{address}/history HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}
get

Query voter accounts ordered by votes.

Query parameters
limitintegerOptional

Limit used for pagination

Default: 20
pageintegerOptional

Page number to fetch

Default: 0
Responses
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/governance/voters
GET /governance/voters HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}
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
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/governance/proposals
GET /governance/proposals HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}
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
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/governance/proposals/votes
GET /governance/proposals/votes HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}
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
400

Unexpected error

application/json
messagestringRequired
statusbooleanRequired
get/governance/proposals/{proposalId}
GET /governance/proposals/{proposalId} HTTP/1.1
Accept: */*

{
  "message": "text",
  "status": true
}

Last updated