search

Beefy API

Last Update: August 2023

This page provides further details about the functionality and operation of Beefy's REST API, which powers our web application, dashboard and pages on third party sites.

You can access the API at https://api.beefy.finance/arrow-up-right, and the public repository is available on the Beefy GitHubarrow-up-right. The API is maintained under the MIT license, with further details available on the GitHub repoarrow-up-right.

hashtag
Endpoints

Our API offers a range of public endpoints covering the full selection of data required for our web app, backend and dashboard, as well as some third party services.

hashtag
Beefy Vault Endpoints

Endpoints developed for use by the Beefy Applicationarrow-up-right to display vaults' live characteristics and performance to our users.

chevron-rightGET /vaults hashtag

Provides live information about each Beefy vault, including retired (eol) vaults.

The information includes fields for the relevant vault's name/ID, chain, token, underlying assets, related contracts and current status. It also includes the "risks" field, which lists the vault's features taken from the matrix of risk factors used to calculate a vault's safety score.

// Sample response for the /vaults endpoint (e.g. Polygon aTriCrypto3 vault)

{
  "id": "curve-poly-atricrypto3",
  "name": "aTriCrypto3",
  "token": "crvUSDBTCETH3",
  "tokenAddress": "0xdAD97F7713Ae9437fa9249920eC8507e5FbB23d3",
  "tokenDecimals": 18,
  "tokenProviderId": "curve",
  "earnedToken": "mooCurveATriCrypto3",
  "earnedTokenAddress": "0x5A0801BAd20B6c62d86C566ca90688A6b9ea1d3f",
  "earnContractAddress": "0x5A0801BAd20B6c62d86C566ca90688A6b9ea1d3f",
  "oracle": "lps",
  "oracleId": "curve-poly-atricrypto3",
  "status": "active",
  "platformId": "curve",
  "assets": [
    "DAI",
    "USDC",
    "USDT",
    "WBTC",
    "ETH"
  ],
  "strategyTypeId": "multi-lp",
  "risks": [
    "COMPLEXITY_LOW",
    "BATTLE_TESTED",
    "IL_LOW",
    "MCAP_LARGE",
    "PLATFORM_ESTABLISHED",
    "AUDIT",
    "CONTRACTS_VERIFIED",
    "OVER_COLLAT_ALGO_STABLECOIN"
  ],
  "addLiquidityUrl": "https://polygon.curve.fi/atricrypto3/deposit",
  "network": "polygon",
  "createdAt": 1652662923,
  "chain": "polygon",
  "strategy": "0x41D7529b4C9245a50ca6A169d39719DFF117f6CA",
  "lastHarvest": 1664612723,
  "pricePerFullShare": "1178961451902175914"
},

hashtag
Field Notes:

  • id - the unique identifying string assigned to each vault, including separate versions of the same vault.

  • tokenAddress - the contract address for the main deposit asset, typically an LP token.

  • earnedTokenAddress - the contract of the token which is earned by the strategy used by the vault. For most Beefy vaults, this is the same as the vault contract, because the strategy is autocompounding. For earnings pool vaults (which don't autocompound), this will be the native token of the chain or protocol that the vault relates to.

  • earnContractAddress - the address of the Beefy vault contract which handles deposits and withdrawals and issues the mooVault token to users.

  • status - shows whether a vault is live ("active") or retired ("eol").

  • assets - the underlying assets at the base of the relevant vault's stack (typically the assets included in the LP that the vault is built on).

  • strategyTypeID - indicates what type of strategy is being utilised by the vault (e.g. "single" asset, "lp", "multi-lp", etc).

  • risks - a list of the vault's applicable features taken from the matrix of factors used to calculate a vault's safety score.

  • network - the relevant blockchain that the vault resides on.

  • createdAt - the block of the relevant blockchain where the vault was created.

  • strategy - the address of the strategy contract currently in use by the vault.

  • lastHarvest - the block of the relevant blockchain where the vault was last harvested - i.e. where profits were collected from the strategy (and autocompounded, if applicable).

  • pricePerFullShare - the current average price (denominated in the deposit asset, e.g. the underlying LP token) for each whole share of the vault's total issued share capital, reflecting the total value invested into the vault over its life divided by the number of shares of the vault issued.

chevron-rightGET /apyhashtag

Provides the current and live annual percentage yield of each Beefy vault.

// Sample response for the /apy endpoint

{
  ...
  "balancer-usdc-link-eth-bal-aave": 0.03705509745347668,
  "balancer-matic-usdc-eth-bal": 0.052770609595836904,
  "baby-wbnb-busd": 0.1612595689122669,
  "baby-usdc-wbnb": 0.16031283171896837,
  "balancer-vst-dai-usdt-usdc": 0.029489187277781825,
  "balancer-bal-eth": 0.024578537703132453,
  "curve-matic-stmatic": 0.08866966650936048,
  "sushi-poly-weth-sx": 0.7135292677781775,
  "sushi-poly-bct-klima": 0.0007036903322936716,
}

Field Notes:

  • Vault APY - Each field reflects the unique id string of a vault, and returns a value which represents the live APY as a decimal. For instance, "0.037" represents 3.7% APY.

chevron-rightGET /apy/breakdownhashtag

Provides more detailed information relating to the yield of each Beefy vault, which is required to assess the expected APY based on factors like the APR, rate of compounding and applicable fees.

// Sample response from the /apy/breakdown endpoint (e.g. Polygon Cometh UST-ETH LP)

{
  "bifi-maxi": {
    "totalApy": 0.07598675804818633
  },
  "cometh-must-eth": {
    "vaultApr": 1.186973388240745,
    "compoundingsPerYear": 2190,
    "beefyPerformanceFee": 0.045,
    "vaultApy": 2.1057844292858614,
    "lpFee": 0.005,
    "tradingApr": 0.22324214039526927,
    "totalApy": 2.8825691266420788
  }
}

hashtag
Field Notes

  • vaultApr - the annual percentage return of the vault, calculated from the expected yearly rewards of the vault, denominated in $USD, divided by the total amount invested in the vault, also in $USD.

  • compoundingsPerYear - the estimated current number of compounding events ("harvest" calls) per year.

  • beefyPerformanceFee - the flat Beefy performance fee included in the calculation.

  • vaultApy - the annual percentage yield (APY) of the vault, calculated by compounding the vaultApr detailed above, using the compoundingsPerYear figure, and adjusting for the beefyPerformanceFee.

  • lpFee - the Liquidity Provider (LP) fee charged for each trade.

  • tradingApr - the annual interest received from trading fees, without applying or account for any compounding effect.

  • totalApy - the known total APY, calculated as totalApy = (1 + vaultApy) * (1 + tradingApr) - 1.

chevron-rightGET /tvlhashtag

Provides the current and live total value locked of each Beefy vault, which is the sum of the current market capitalisation of all of the assets currently held by the relevant vault, denominated in $USD.

chevron-rightGET /feeshashtag

Provides a detailed breakdown of the current fee structure for each Beefy vault.

Field Notes:

  • performance - a list of the fee settings which together constitute the performance fee charged on every compounding event ("harvest") for each vault.

  • total - the total performance fee charged, being the sum of the other facts in the "performance" list.

  • strategist - the fee payable to the strategist that deploys the vault, as a form of incentive to encourage community contributions.

  • call - the fee payable to the caller of the harvest function which gives rise to the compounding of the vault.

  • treasury - the fee payable to the Beefy treasury to support the protocol.

  • stakers - the fee payable to holders and stakers of the BIFI token, which is pay out to our BIFI Earnings Pool vaults or to buy back BIFI tokens for our BIFI Maxi vaults.

  • withdraw - the fee charged on the value of your deposit upon withdrawal from the vault, to protect against attacks against and abuse of our vaults.

  • lastUpdated - the block of the relevant blockchain for the vault from which the data in the API was last updated.

hashtag
External Asset Endpoints

Endpoints developed for use by the Beefy Applicationarrow-up-right to display information about the assets underlying our Beefy vaults to our users.

chevron-rightGET /lpshashtag

Provides the current live prices of underlying liquidity pools used by each Beefy vaults.

Field Notes:

  • LP Price - each field reflects the unique oracleId string of an LP vault, and returns a value which represents the live price in USD. For instance, "1.165" represents a price of $1.17.

chevron-rightGET /lps/breakdownhashtag

Provides more detailed information relating to the liquidity pool used by each Beefy vault.

Field Notes:

  • price - the current and live price per full share of the LP token, denominated in $USD.

  • tokens - a list of the contract addresses of each of the underlying assets/tokens included in the LP.

  • balances - a list of the current balances of each of the tokens in the vault, as listed in the previous field, denominated in the underlying token.

  • totalSupply - the current and live number of LP tokens issued.

chevron-rightGET /tokenshashtag

Provides information on all of the tokens utilised by Beefy, including individual assets and currencies, staked assets and LPs, sorted by the blockchain each is deployed on.

Field Notes:

  • name - a string showing the full name of the token associated with the relevant ID.

  • symbol - a string showing the symbol assigned to the token by the issuer.

  • address - the contract address for the relevant token.

  • decimals - the number of decimal permitted for the token by the issuer, representing how divisible it is on chain.

GET /tokens/{blockchain}

For further specificity, you can add a {blockchain} parameter to the /tokens endpoint to return only tokens on a given blockchain (e.g. /tokens/polygon returns only tokens issued on the Polygon blockchain).

hashtag
Other Beefy App Endpoints

Endpoints developed for use by the Beefy Applicationarrow-up-right to display other information not relating to individual vaults.

chevron-rightGET /confighashtag

Provides information on the addresses of the current configuration of wallets used to operate each blockchain used by the the Beefy Applicationarrow-up-right.

Field Notes:

  • devMultisig - the address of the Beefy developer multisignature wallet used to manage development updates on the chain.

  • treasuryMultisig - the address of the Beefy treasury multisignature wallet used to manage Beefy's core treasury of funds on the chain.

  • strategyOwner - the address of the standard Beefy wallet that acts as owner of strategy contracts on the chain.

  • vaultOwner - the address of the standard Beefy wallet that acts as owner of vault contracts on the chain.

  • keeper - the address of the standard Beefy wallet that acts as keeper of vault contracts on the chain. This includes managing the whitelist of strategies used by the vault, and pausing or panicking the vault if required.

  • treasurer - the address of the standard Beefy wallet that acts as the treasurer on the chain. This includes managing payments from the treasury for various reasons, and is often the same wallet as the treasuryMultisig.

  • launchpoolOwner - the address of the standard Beefy wallet that acts as owner of the launchpool/boost contracts deployed on the chain. This is often the same wallet as the devMultisig.

  • rewardPool - the address of the standard Beefy wallet that holds the rewards allocated for boosts on the chain.

  • treasury - the address of the standard Beefy wallet that acts as the treasury on the chain, and is managed by the treasurer and treasuryMultisig.

  • beefyFeeRecipient - the address of the standard Beefy wallet that acts receives performance fees charged on harvests from all Beefy vaults on the chain.

  • bifiMaxiStrategy - the address of the strategy attached to the native $BIFI Maxi vault on the chain.

  • voter - the address of the standard Beefy wallet that is used to direct Beefy's voting power on various third party protocols.

  • beefyFeeConfig - address of the upgradeable proxy contract used to set the configuration of performance fees charged for vaults on the chain.

GET /config/{blockchain}

For further specificity, you can add a {blockchain} parameter to the /config endpoint to return the configuration details of a given blockchain (e.g. /config/polygon returns only the details for the Polygon blockchain).

chevron-rightGET /boostshashtag

Provides information on all Launchpool Boosts hosted by Beefy on the application, including live and historic boosts.

Field Notes:

  • id - the unique identifying string assigned to each vault, including separate versions of the same vault.

  • poolId - the unique identifying string assigned to each LP that Beefy has vaulted, including separate versions of the same LP.

  • name - the full name of the partner(s) which have funded the boost.

  • assets - a list of the underlying assets used for the vault or any underlying LP.

  • tokenAddress - the address of the Beefy vault contract which handles deposits and withdrawals and issues the mooVault token to users.

  • earnedToken - the name of the boost reward token earned by boost participants.

  • earnedTokenDecimals - the number of decimal places assigned and used for the earnedToken from its creation.

  • earnTokenAddress - the contract address of the earnedToken.

  • earnContractAddress - the contract address of the boost contract, which holds the assigned boost rewards and distributes them to boost participants.

  • isMooStaked - whether the boost requires users to stake their mooTokens in a further contract with Beefy to receive the boost.

  • partners - shorthand label for the partner(s) which have funded the boost.

  • periodFinish - the block of the hosted blockchain where the boost ends.

GET /boosts/{blockchain}

For further specificity, you can add a {blockchain} parameter to the /boosts endpoint to return only boosts on a given blockchain (e.g. /boosts/polygon returns only boosts hosted on the Polygon blockchain).

chevron-rightGET /bifibuybackhashtag

Provides details of the daily amount of BIFI buyback carried out on each blockchain.

Field Notes:

  • buybackTokenAmount - shows the current daily amount of $BIFI tokens bought back by the protocol on the relevant chain.

  • buybackUsdAmount - shows the current value of the above in USD.

hashtag
Dashboard Endpoints

Endpoints developed for the Beefy Dashboardarrow-up-right to display overarching information about the protocol.

circle-info

Please note that the Dashboard site and the /earnings endpoint are both no longer actively maintained by Beefy. Though the Dashboard site remains live, it does not reflect every vault that has been implemented and every chain that Beefy has deployed to.

hashtag
Databarn Endpoints

Endpoints related to databarn, our historical data indexer. These endpoints are rate limited to maximum 5 requests per seconds. You may also want to try the interactive swagger uiarrow-up-right for these endpoints.

hashtag
Fetches the investor timeline

get

Describes all transactions for a given investor

Query parameters
addressstring · min: 42 · max: 42RequiredPattern: ^0x[a-fA-F0-9]{40}$
Responses
chevron-right
200

The investor timeline, list of all deposit and withdraw transaction for a given investor

application/json
get
/api/v1/beefy/timeline
200

The investor timeline, list of all deposit and withdraw transaction for a given investor

hashtag
Fetches all product configurations for a chain

get

Returns the configuration accounted for in databarn

Path parameters
chainstring · enumRequired

Only include produce for this chain

Possible values:
Query parameters
include_eolbooleanOptional

Include EOL (end of life) products, you probably never want to set this to true

Default: false
Responses
chevron-right
200

List of all beefy products, vaults, boosts, governance vaults, etc.

application/json
get
/api/v1/beefy/product/{chain}
200

List of all beefy products, vaults, boosts, governance vaults, etc.

hashtag
Fetch a specific product configuration

get

Find one product configuration by chain and contract address

Path parameters
chainstring · enumRequired

Only include products for this chain

Possible values:
contract_addressstring · min: 42 · max: 42Required

The product contract address

Pattern: ^0x[a-fA-F0-9]{40}$
Responses
chevron-right
200

Default Response

application/json
get
/api/v1/beefy/product/{chain}/{contract_address}
200

Default Response

hashtag
Get tvl snapshots in usd for a specific product.

get

This endpoint returns snapshots of the api /tvls endpoints done every 15 minutes and can be used to request raw historical data but the time range must not exceede 1 week and the result will be truncated to 1000 elements. from_date is inclusive and to_date is exclusive to make is easier to use in loops

Path parameters
chainstring · enumRequired

Only include products for this chain

Possible values:
contract_addressstring · min: 42 · max: 42Required

The product contract address

Pattern: ^0x[a-fA-F0-9]{40}$
Query parameters
from_date_utcstring · date-timeRequired

Inclusive date time to fetch data from, interpreted as utc tz

Example: 2023-01-01T00:00:00
to_date_utcstring · date-timeRequired

Exclusive date time to fetch data to, interpreted as utc tz

Example: 2023-01-01T00:00:00
Responses
chevron-right
200

The raw tvl time series

application/json
get
/api/v1/beefy/product/{chain}/{contract_address}/tvl
200

The raw tvl time series

hashtag
Get a quick price time series for a given product and time bucket

get

This endpoint is essentially used for charting and UIs as it provides a simple interface to get the most widely displayed time series.

Query parameters
product_keystring · min: 10 · max: 100Required
price_typestring · enumRequired

share_to_underlying is the ratio from share token to LP token (ppfs). underlying_to_usd is the ratio from an LP token to USD.

Possible values:
time_bucketstring · enumRequired

Defines a bucket size and a time range like <bucket size>_<time range>. For example, 1d_1M means: 1 month of data aggregated by buckets of 1 day.

Possible values:
Responses
chevron-right
200

The price time series

application/json
get
/api/v1/price/
200

The price time series

hashtag
Get a raw historical time series for a given time range.

get

This endpoint can be used to request raw historical data but the time range must not exceede a week and the result will be truncated to 1000 elements. from_date is inclusive and to_date is exclusive to make is easier to use in loops

Query parameters
product_keystring · min: 10 · max: 100Required
price_typestring · enumRequired

share_to_underlying is the ratio from share token to LP token (ppfs). underlying_to_usd is the ratio from an LP token to USD.

Possible values:
from_date_utcstring · date-timeRequired

Inclusive date time to fetch data from, interpreted as utc tz

Example: 2023-01-01T00:00:00
to_date_utcstring · date-timeRequired

Exclusive date time to fetch data to, interpreted as utc tz

Example: 2023-01-01T00:00:00
Responses
chevron-right
200

The raw price time series

application/json
get
/api/v1/price/raw
200

The raw price time series

hashtag
Third Party Endpoints

Endpoints required or utilised by third party platforms to display information about Beefy or its products on their sites.

chevron-rightGET /cmchashtag

Provides information required by CoinMarketCaparrow-up-right in order to display Beefy vaults in their yield farming section.

chevron-rightGET /supplyhashtag

Provides information required by Coingeckoarrow-up-right in order to display BIFI's total supply and circulating supply on its site.

hashtag
Subgraph

Please note that Beefy does not currently operate or maintain any subgraphs for our protocol.

Our friends at Messari have developed a subgraph for our presence on BSC chain, which is available at https://api.thegraph.com/subgraphs/name/messari/beefy-finance-bscarrow-up-right, and on The Graph's websitearrow-up-right (ID: QmfEtMEgjik9FSZdqAmp2DkNFG4M9TK4Go8uyCUj8EVxY6). Beefy has had no role in the development or maintenance of this subgraph. Please direct any questions or requests for assistance in relation to this subgraph directly to Messari.

hashtag
Other Data

For any readers seeking further information about Beefy and our protocol's performance, please head to the #📊-beefy-data channel in our Discord serverarrow-up-right. We'll be happy to answer any questions you may have there and you're welcome to inspect the history of our discussions in that channel for further background into our data work.

You'll also find in that channel a collection of weekly reports on the breakdown of our $BIFI token across our different chains and vaults, which are lovingly prepared by core contributor EPETE.

Last updated

Was this helpful?