> For the complete documentation index, see [llms.txt](https://docs-v4.venus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v4.venus.io/services/api.md). # 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 {% hint style="warning" %} 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. {% endhint %} The live [Swagger playground](https://api.venus.io/docs/playground) and [OpenAPI JSON](https://api.venus.io/docs/swagger.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: ```bash 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: ```bash curl --get 'https://api.venus.io/markets' \ --header 'accept-version: next' \ --data-urlencode 'chainId=56' \ --data-urlencode 'limit=1' ``` 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 {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/pools" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} ### Market Endpoints {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/markets" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/markets/history" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/markets/tvl" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} ### Governance Endpoints {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/governance/proposals/{proposalId}/voteSummary" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/governance/voters/{address}/summary" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/governance/voters/{address}/history" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/governance/voters" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/governance/proposals" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/governance/proposals/votes" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} {% openapi src="/files/NeHm3NSWDcZ66uG7Ad3x" path="/governance/proposals/{proposalId}" method="get" %} [swagger.json](https://1811016925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSfxZmzf9N5T5Npv859XY%2Fuploads%2Fgit-blob-dbb2c7ace483764d85edc0ab191f48205eec2a8b%2Fswagger.json?alt=media) {% endopenapi %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs-v4.venus.io/services/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.