---
title: 'V2 API Specs'
disqus: hackmd
---

Umami API v2
===

## Table of Contents

[TOC]

## Protocol Metrics
General Overview
- Caching for all Phase 1 values (cachd) expiry time tbd, can be quick
- Utilize TheGraph for Phase 1 data, pricing can come from llama's new api with coingecko api failover

## Protocol Metrics

- `/v2/token/metrics`
​

{
  totalSupply: "650000",
  circulating: "123456",
  marinating: "234567",
  compounding: "345678",
  price: "$19.73"
}

## Staking Metrics
---
​
- `/v2/staking/metrics/current?keys=<key1>&keys=<key2>`

Keys :
- `apr` : Marinator APR
- `apy` : Compoundor APY
- `total-eth` : Total ETH distributed since inception
- `month-eth` : Total ETH distributed in the last 30 days
- `revenues-eth` : ETH distributed last month for 100 UMAMI staked
- `revenues-usd` : USD value of the ETH distributed last month for 100 UMAMI staked
​

[
  {
    key: "revenues-usd",
    label: "Revenue per 100 UMAMI",
    value: "$4.30",
    context: "The dollar value of the .... "
  },
  {
    key: "apy",
    label: "Current APY",
    value: "15.66%",
    context: "The current APY.... "
  }
]

​
- `/v2/staking/metrics/historic?t={1m|3m|12m}&keys=<key1>&keys=<key2>`

Param `MetricKey` :

- `revenues-usd-historical` : USD value of the ETH distributed last month for 100 UMAMI staked
- `pps-historical` : Historical daily distributions
​
Thoughts on APR calcs:
1m = 30 data points, 7 day previous average (End date is final date in the average series.)
3m = 30 data points, 14 day previous average
12m = 52 data points, 30 day previous average

[
  {
    label: "Revenue per 100 UMAMI",
    current: "$4.30"
    context: "The dollar value of the .... "
    data: [
        [ "s1x1", "s1y1" ],
        [ "s1x2", "s1y2" ],
        [ "s1x3", "s1y3" ],
     ]
  },
  {
    label: "APY",
    current: "23.4%"
    context: "Current APY assuming xyz"
  }
]

## Vaults (Phase 2)

Just gathering notes for future funcitonality, subject to change based on final v2 vault contracts, do not implement yet.

- `/whitelist/:addr`

  {
    "whitelist": {
      "onList": true,
      "proof": []
    }
  }

`/vaults`

Static information about all vaults.

This will be used for the vaults overview page.

  [
    {
      // URL for the UI, i.e. umami.finance/vaults/glpUSDC
      // also used as a key for other stats.
      "id": "glpUSDC",
      "name": "GLP/TCR USDC Pool",
      "address": "0x2e2...",
      "category": "market-hedged",
      "audit": "https://...",
      "tokens": {
        "asset": {
          "symbol": "USDC",
          "name": "USDCoin",
          "decimals": 6,
          "address": "0x...",
          // This will be the graphic to use in our interface
          "logoURI": "https://tokens.1inch.io/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png"
        },
        "receipt": {
          "symbol": "glpUSDC",
          "name": "glpUSDC",
          "decimals": 6,
          "address": "0x...",
          "logoURI": "https://..."
        }
      },
      "strategyText": "We use [GMX](https://gmx.io). We _really_ like it."
    },
    {
      /** glpETH **/
    },
    {
      /** glpBTC **/
    }
  ]

- `/vaults/status`

This URL pulls the **dynamic** information about all vaults. We won't cache this and will poll the API for it regularly. Upstream fees will be pulled particularly frequently when depositing or withdrawing, so we should consider having a separate route for them specifically.

  [
    {
      "id": "glpUSDC",
      "fees": {
        // Fees assessed by umami
        // NOTE: fees could alternatively be in basis points?
        "umami": [0.5, 1.5, 15, 0],
        // Fees from upstream platforms, i.e. GLP mint/burn
        "upstream": {
          "deposit": 0.8723,
          "withdraw": 0.0233
        }
      },
      "balance": {
        // These can be stringified BigNumbers of atomic amount
        "current": "5450627077554",
        "max": "5000000000000"
      }
    },
    {
      /** glpETH **/
    },
    {
      /** glpBTC **/
    }
  ]

- `/vault/:id`

Same as `/vaults`, but only returns info for one vault. May not use this while there aren't many vaults.

  { /** vault info **/ }

- `/vault/:id/status`

Same as `/vaults/status`, but only returns info for one vault.

  { /** vault status **/ }

- `/vault/:id/upstreamFees/:{withdraw|deposit}`

Returns just the specified upstream fee for this vault. We can potentially use the route above, but we'll want to poll this quite frequently when depositing to ensure the user gets an accurate depiction of the fees they'll pay, so splitting it out from other stats may ease the laod on the server side.

  0.8723

## Personal Dashboard Metrics (Phase 2)