changed 3 years ago
Published Linked with GitHub

Introduction

API

Base url: https://api.homora.alphaventuredao.io/
Swagger: https://api.homora.alphaventuredao.io/doc

Data Types

Pool

Attribute Type Description
key string Pool's key
name string Pool's name (e.g. ETH/USDT)
tokens string[] Pool's token addresses in lowercase
lpTokenAddress string Pool's LP token address in lowercase
poolAddress? string [optional] Only use with Curve pool since pool address is holding the tokens not LP address
wTokenAddress string Wrapper contract address
exchange IExchange IExchange
type PoolType PoolType
wTokenType WTokenType WTokenType
pid? number [optional] Only use with pools that need to be staked on a Masterchef-like contract and pools which wTokenType === WTokenType.WLiquidityGauge
gid? number [optional] Only use with Curve pool
rewardSymbol? string [optional] Pool's reward symbol, usually we use reward symbol from exchange.reward.tokenName
rewardAddress? string [optional] Pool's reward address, usually we use reward address from exchange.reward.rewardTokenAddress
isFarmingDisabled? boolean [optional] A pool that's been hidden on the Farm Pool page (deprecated soon)
status? 'delisting' | 'delisted' [optional] delisting = A pool that's going to be delisted soon. delisted = A pool that's been delisted. For both of the statuses, we'd recommend users to close their position.
stakingAddress? string [optional] Masterchef address of that pool.
spellAddress? string [optional] Pool's spell address, usually we use spellAddress from exchange.spellAddress
migrateTo? string [optinal] Pool that need to be migrate to a new pool
uniswapV3Info UniswapV3Pool UniswapV3Pool

IExchange

Attribute Type Description
name Exchange Exchange Enum
logo string Logo source for Homora's frontend
spellAddress? string [optional] Exchange's spell address
stakingAddress? string [optional] Exchange's staking address
reward IExchangeReward Exchange's liquidity mining reward

IExchangeReward

Attribute Type Description
tokenName string Exchange's liquidity mining reward name
rewardTokenAddress string Exchange's liquidity mining reward address

Safebox

Attribute Type Description
address string Asset address
safeboxAddress string Homora safebox address
cyTokenAddress string Iron Bank lending address

PoolAPY

Attribute Type Description
totalAPY string Total APY
tradingFeeAPY string Trading Fee APY
farminigAPY string Yield Farming APY

TokenDetails

Attribute Type Description
name string Token's name
logo string Logo source for Homora frontend
decimals number Token's decimals

UniswapV3Pool

Attribute Type Description
priceRatioBps [number, number, number] Recommended price range BPS, sorted from safe to risky range
poolFeeBps number Pool's Fee BPS
tickSpacing number Pool's tick spacing (1 / 10 / 60 / 200)

UniswapV3PriceRangeInfo

Attribute Type Description
lastUpdatedTimestamp number Last update timestamp in ms
lastUpdatedTick number Latest pool's tick
priceRanges [PriceRange, PriceRange, PriceRange] Recommended price range, sorted from safe to risky range

PriceRange

Attribute Type Description
apr number Price range APR
lower TickInfo Lower tick info
upper TickInfo Upper tick info

TickInfo

Attribute Type Description
tick number Tick number
price0 string Price of token0 / token1
price1 string Price of token1 / token0

UniswapV3Position

Attribute Type Description
positionId string Uniswap V3 position ID (not Homora position ID)
tickLower number Position's tick lower
tickUpper number Position's tick upper
liquidity string Position's liquidity size (Each position has a different LP price due to the diverse price range of each position.)
apr number Position's APR

Enum

PoolType

enum PoolType {
  LiquidityProviding = 'Liquidity Providing',
  YieldFarming = 'Yield Farming',
}

Exchange

enum Exchange {
  UniswapV2 = 'Uniswap V2',
  UniswapV3 = 'Uniswap V3',
  Sushiswap = 'Sushiswap',
  Curve = 'Curve',
  TraderJoe = 'Trader Joe',
  TraderJoeMasterChefV3 = 'Trader Joe MasterChef V3',
  TraderJoeBoostedMasterChef = 'Trader Joe Boosted MasterChef',
  Pangolin = 'Pangolin',
  PangolinV2 = 'Pangolin V2',
  SpookySwap = 'SpookySwap',
  SpookySwapV2 = 'SpookySwap V2',
  SpiritSwap = 'SpiritSwap',
  Beethovenx = 'Beethovenx',
}

WTokenType

enum WTokenType {
  WERC20 = 'WERC20',
  WStakingRewards = 'WStakingRewards',
  WMasterChef = 'WMasterChef',
  WMasterChefJoeV3 = 'WMasterChefJoeV3',
  WBoostedMasterChefJoe = 'WBoostedMasterChefJoe',
  WLiquidityGauge = 'WLiquidityGauge',
  WMiniChef = 'WMiniChef',
  WMiniChefV2 = 'WMiniChefV2',
  WMasterChefBeets = 'WMasterChefBeets',
  WMasterChefBoolV2 = 'WMasterChefBoolV2',
  WUniswapV3 = 'WUniswapV3',
}

API Endpoint

Farm Pools

To get all of the farming pools of each chain.

Endpoint: https://api.homora.alphaventuredao.io/v2/[chainId]/pools
Example: https://api.homora.alphaventuredao.io/v2/43114/pools

return type: Pool[]

Lend Pools

To get all of the lending pools of each chain

Endpoint: https://api.homora.alphaventuredao.io/v2/[chainId]/safeboxes
Example: https://api.homora.alphaventuredao.io/v2/43114/safeboxes

return type: Safebox[]

APYs

To get all of the farming pool's APYs of each chain (except for UniswapV3 Pools)

Endpoint: https://api.homora.alphaventuredao.io/v2/[chainId]/apys
Example: https://api.homora.alphaventuredao.io/v2/43114/apys

return type: Record<string, PoolAPY> // Record<Pool's key, PoolAPY>

Token Details

To get all of the token details with the name and decimals of each chain

Endpoint: https://api.homora.alphaventuredao.io/v2/[chainId]/tokens
Example: https://api.homora.alphaventuredao.io/v2/43114/tokens

return type: Record<string, TokenDetails> // Record<Token's address, TokenDetails>

All Positions

To get all of the positions sorted by highest to lowest debt ratio of each chain. Only use with liquidation page only.

Endpoint: https://api.homora.alphaventuredao.io/v2/[chainId]/positions
Example: https://api.homora.alphaventuredao.io/v2/43114/positions

(UniswapV3) Pool's price range & APR

To get all of the Uniswap V3 pool's price ranges and APRs

Endpoint: https://api.homora.alphaventuredao.io/v2/[chainId]/uniswapv3/price-range
Example: https://api.homora.alphaventuredao.io/v2/10/uniswapv3/price-range

return type: Record<string, UniswapV3PriceRangeInfo> // Record<Pool's key, UniswapV3PriceRangeInfo>

(UniswapV3) Positions Info

To get user's Uniswap V3 position info

Endpoint: https://api.homora.alphaventuredao.io/v2/[chainId]/uniswapv3/positions
Example: https://api.homora.alphaventuredao.io/v2/10/uniswapv3/positions

return type: Record<string, UniswapV3Position> // Record<Homora position ID, UniswapV3Position>

Subgraph

Endpoint

Query

positions {
  id
  owner
  collateralSize
  collateralToken {
    token
    tokenId
  }
}

Data

  • id : Position ID
  • owner : Position owner address
  • collateralSize : The size of the collateral (if 0 then the position is closed because there's no collateral left)
  • collateralToken - token : Wrap token contract address. It's an ERC-1155 contract that keep user positions.
  • collateralToken - token : Token ID that determine the position info like LP address or PID.

Calculation

Pool's Best Leverage

The pool's best leverage is calculated by borrowing each token to the maximum borrowing amount and check that which one gives the best APY, then use that leverage as the pool's max leverage.
*Please note that the pool best leverage showing in the Homora V2's UI aren't always the pool max leverage because in some situation, the borrow APY is quite high from high utilization of the lending pool so the UI won't suggest that leverage.

tokenMaxLeverage or the max leverage of each borrowing token is calculated as:

tokenMaxLeverage = borrowFactor / (borrowFactor - (collateralFactor * cappedDebtRatio))

*Default cappedDebtRatio is set to 0.95
Read more about collateral and borrow credit.

The total APY of that tokenMaxLeverage is calculated as:

totalAPY = ((farmingAPR + tradingFeeAPY) * tokenMaxLeverage) + (totalRewardAPY * (tokenMaxLeverage - 1)) - (tokenBorrowApy * (tokenMaxLeverage - 1))

*The rewardAPY and borrowAPY is multiplied by (maxLeverage-1) because the interest only happens when the leverage is >1

Then compared totalAPY of each borrowing token (also with the totalAPY if has no leverage) to see which one gives the best APY.

Contracts

https://hackmd.io/@PhhCdDESRme9EK6zwT-9Pw/BJsYdyrw9

Select a repo