# 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](#IExchange) |
| `type` | `PoolType` | [PoolType](#PoolType) |
| `wTokenType` | `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](#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](https://hackmd.io/@PhhCdDESRme9EK6zwT-9Pw/BJsYdyrw9#Alpha-Homora-Components) 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[]](#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[]](#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](#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](#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](#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](#UniswapV3Position)> // `Record<Homora position ID, UniswapV3Position>`

## Subgraph
### Endpoint
- Ethereum: https://api.thegraph.com/subgraphs/name/hermioneeth/alpha-homora-v2-relaunch
- Avalanche: https://api.thegraph.com/subgraphs/name/alphafinancelab/alpha-homora-v2-avax
- Fantom: https://api.thegraph.com/subgraphs/name/alphafinancelab/alpha-homora-v2-fantom
- Optimism: https://api.thegraph.com/subgraphs/name/mintcnn/optimism

### 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](https://docs.alphaventuredao.io/homora-v2/additional-info/understanding-collateral-credit-and-borrowing-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.

<!-- # Oracle -->

# Contracts

https://hackmd.io/@PhhCdDESRme9EK6zwT-9Pw/BJsYdyrw9
<!-- # UI

## Farm Pool
## Your Positions
## Lend Pool -->