Add examples and documentation

README.md

@@ -7,22 +7,63 @@
 
 *This repo is being used as part of the [crvUSD Risk Modeling effort](https://github.com/xenophonlabs/crvUSDrisk).*
 
-TODO: 
+## About
 
-- Complete README
+As part of the [crvUSD Risk Modeling effort](https://github.com/xenophonlabs/crvUSDrisk), we have been storing quotes from the [1Inch Swap API](https://portal.1inch.dev/documentation/swap/swagger?method=get&path=%2Fv5.2%2F1%2Fquote) for certain tokens pertaining to the crvUSD ecosystem (a full list can be found in `src.configs.tokens.py` and is reproduced below).
 
-- Add demo notebook with plots!
+We query random trade sizes for each token pair every hour to generate a `price impact curve`. This allows us to model the expected price impact of traders arbitraging the various pools connected to Curve's new stablecoin. In turn, this gives us a reasonable idea of when price-sensitive arbitrageur would or would not arbitrage mispricings in these pools. A more detailed explanation of how these price impact curves are used can be found here: `https://github.com/xenophonlabs/crvUSDrisk/blob/main/notebooks/demo_slippage_curves.ipynb`.
 
+![Sample Quotes](./figs/sample_quotes.png)
+*Sample quotes for USDC -> WETH between December 1, 2023 and December 8, 2023.*
 
-### Usage
+![Sample Price Impact](./figs/sample_price_impact.png)
+*Sample price impact curve for USDC -> WETH between December 1, 2023 and December 8, 2023.*
 
 
-- We provide a simple flask API for querying our database to create ``price impact curves''.
+### Supported Tokens
 
+All pairwise combinations of the below tokens have been stored every hour since Thursday, November 16, 2023 at 6pm UTC. 
 
-### Replicating this service
+| Image | Name | Parameters |
+| -------- | ----------- | ---------- |
+| [![USDC](https://assets.coingecko.com/coins/images/6319/thumb/usdc.png?1696506694)](https://assets.coingecko.com/coins/images/6319/thumb/usdc.png?1696506694) | USDC | `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` |
+| [![USDT](https://assets.coingecko.com/coins/images/325/thumb/Tether.png?1696501661)](https://assets.coingecko.com/coins/images/325/thumb/Tether.png?1696501661) | USDT | `0xdac17f958d2ee523a2206206994597c13d831ec7` |
+| [![USDP](https://assets.coingecko.com/coins/images/6013/thumb/Pax_Dollar.png?1696506427)](https://assets.coingecko.com/coins/images/6013/thumb/Pax_Dollar.png?1696506427) | USDP | `0x8e870d67f660d95d5be530380d0ec0bd388289e1` |
+| [![TUSD](https://assets.coingecko.com/coins/images/3449/thumb/tusd.png?1696504140)](https://assets.coingecko.com/coins/images/3449/thumb/tusd.png?1696504140) | TUSD | `0x0000000000085d4780b73119b644ae5ecd22b376` |
+| [![WETH](https://assets.coingecko.com/coins/images/2518/thumb/weth.png?1696503332)](https://assets.coingecko.com/coins/images/2518/thumb/weth.png?1696503332) | WETH | `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2` |
+| [![WSTETH](https://assets.coingecko.com/coins/images/18834/thumb/wstETH.png?1696518295)](https://assets.coingecko.com/coins/images/18834/thumb/wstETH.png?1696518295) | wstETH | `0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0` |
+| [![SFRXETH](https://assets.coingecko.com/coins/images/28285/thumb/sfrxETH_icon.png?1696527285)](https://assets.coingecko.com/coins/images/28285/thumb/sfrxETH_icon.png?1696527285) | sfrxETH | `0xac3e018457b222d93114458476f3e3416abbe38f` |
+| [![WBTC](https://assets.coingecko.com/coins/images/7598/thumb/wrapped_bitcoin_wbtc.png?1696507857)](https://assets.coingecko.com/coins/images/7598/thumb/wrapped_bitcoin_wbtc.png?1696507857) | WBTC | `0x2260fac5e5542a773aa44fbcfedf7c193bc2c599` |
+| [![tBTC](https://assets.coingecko.com/coins/images/11224/thumb/0x18084fba666a33d37592fa2633fd49a74dd93a88.png?1696511155)](https://assets.coingecko.com/coins/images/11224/thumb/0x18084fba666a33d37592fa2633fd49a74dd93a88.png?1696511155) | tBTC | `0x18084fba666a33d37592fa2633fd49a74dd93a88` |
 
-- This repo may be used to create a service that queries quotes from 1inch for all pairwise combinations of tokens in the `src/configs/tokens.py` file.
+## Usage
 
-- These quotes are saved to a Postgres database
+All API requests should be made to the base URL: `http://97.107.138.106/` with the endpoint `quotes`. 
 
+Below, we query quotes for all pairs of the supported tokens from December 12, 2023 to December 13, 2023. Notice that the `start` and `end` parameters are **REQUIRED** and that we use the `--compressed` flag to speed up the query.
+
+```bash
+curl --compressed "http://97.107.138.106/quotes?&start=1702166400&end=1702252800"
+```
+
+### Parameters
+
+| Parameter           | Description                                                                                          | Default Value  | Required |
+|---------------------|------------------------------------------------------------------------------------------------------|----------------|----------|
+| start               | The start timestamp to get quotes for. If not provided, all quotes until `end` are returned.        | None           | Yes      |
+| end                 | The end timestamp to get quotes for. If not provided, all quotes from `start` are returned.        | None           | Yes      |
+| pair                | The pair to get quotes for. If not provided, all pairs are returned.                                | None           | No       |
+| cols                | The columns to return. If not provided, all columns are returned.                                    | None           | No       |
+| process             | Whether to process the quotes. If processed, the returned quotes will be grouped by `hour` and a `price_impact` column will be added. Refer to :func:`src.db.datahandler.DataHandler.process_quotes`. | True           | No       |
+| include-ref-price   | Whether to include the inferred reference price for the price impact calc.                           | False          | No       |
+
+
+### To Do
+
+There are a couple things we are still working on here:
+
+- Cache common responses.
+
+- Acquire and configuring a domain name.
+
+- Add more tokens to our queries.