# EVA Graph API

## JSON-RPC API

The EVA API is a JSON-RPC interface following the [JSON-RPC 2.0 spec](https://www.jsonrpc.org/specification). Any HTTP network library can interact with it easily. The `eva_subscription` method requires websockets.

### `eva_getMarkets`

Returns DeFi markets that are available for price subscription, routing, and settlement. This method has no parameters. The response is formatted as nested dictionary following the format: `{<fromTokenA>: {<toTokenB>: [<available_markets>]}}`

**Request**

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "eth_getMarkets",
    "params": {}
}

**Response**

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "markets": {
            "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
                "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": ["UniswapV2", "UniswapV3", "Balancer"],
                "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE": ["UniswapV2", "UniswapV3"],
                "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599": ["Sushiswap", "Bancor"],
                ...
            },
            ...
        }
    }
}

### `eva_getTokens`

Returns tokens on DeFi markets that are available for price subscription, routing, and settlement. This method has no parameters.

**Request**

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "eva_getTokens",
    "params": {}
}

**Response**

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "tokens": {
            "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
                "symbol": "WETH",
                "decimals": 18
            },
            "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": {
                "symbol": "USDC",
                "decimals": 6
            },
            ...
        }
    }
}

### `eva_getRoutes`

This method is built upon our graph search engine that returns the optimal routes between `tokenIn` and `tokenOut` for a given list of `amountIns`. The maximum route length control parameter is exposed to increase performance by reducing the search space (we find `maxRouteLength=3` to be a good upper bound, and `maxRouteLength=2` if speed is more important). Additionally, by setting `maxRouteLength=1` search will be limited to a single market (e.g. a single `UniswapV2` pair) which turns EVA into a DEX aggregator instead of an order routing system.

**Request**

{
    "jsonrpc": "2.0",
    "id": 12,
    "method": "eva_getRoutes",
    "params": {
        "amountIns": [1.15, 42.45, 100],
        "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "maxRouteLength": 4
    }
}

**Response**

A route is returned for each `amountIn`. The `contractCalldata` can be used alongside a Geth node (see `eth_***` APIs below) to execute this route.

{
    "jsonrpc": "2.0",
    "id": 12,
    "result": {
        "routes": [
            {
                "amountIn": 1.15,
                "amountOut": 4240.901,
                "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
                "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                "contractCalldata": "0x8ba8cc9879a...",
                "gasCost": {
                    "eth": 0.01,
                    "tokenOut": 20.5
                },
                "route": [
                    {
                        "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
                        "tokenOut": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
                        "amountIn": 1.15,
                        "amountOut": 14101329.541,
                        "market": "UniswapV2"
                    },
                    {
                        "tokenIn": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
                        "tokenOut": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
                        "amountIn": 14101329.541,
                        "amountOut": 0.1549,
                        "market": "UniswapV3"
                    },
                    {
                        "tokenIn": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
                        "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                        "amountIn": 0.1549,
                        "amountOut": 4240.901,
                        "market": "SushiSwap"
                    }
                ]
            },
            {
                "amountIn": 42.45,
                "amountOut": 179988.12228,
                "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
                "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                "contractCalldata": ...,
                "gasCost": {...},
                "route": [...],
            }
        ],
        "metadata": {
            "millisSinceLastBlock": 2252
        }
    }
}

### `eva_subscribe`

This is a websocket-backed API that turns the `eva_getRoutes` method (and future methods in development) into a subscription. For the `eva_getRoutes` this means up to date pricing and executable routes.

**Request**

{
    "jsonrpc": "2.0",
    "id": 25,
    "method": "eva_subscribe",
    "params": [
        "eva_getRoutes",
        {
            "amountsIn": [1.15, 42.45, 100],
            "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "maxRouteLength": 4
        }
    ]
}

This response is returned immediately with the subscription ID to be able to have multiple ongoing subscriptions and know which is which (e.g. subscribe to WETH to USDC routes, DAI to UNI, etc.)

**Response (Immediate)**

{
    "jsonrpc": "2.0",
    "id": 25,
    "result": "0x4a8a4c0517381924f9838102c5a4dcb7"
}

**Response (Later)**

{
    "jsonrpc": "2.0",
    "id": 25,
    "result": {
        "subscription":"0x4a8a4c0517381924f9838102c5a4dcb7",
        "routes": [
            {
                "amountIn": 42.45,
                "amountOut": 179988.12228,
                "tokenIn": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
                "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                "contractCalldata": ...,
                "gasCost": {...},
                "route": [...]
            },
            ...
        ],
        "metadata": {
            "millisSinceLastBlock": 2252
        }
    }
}

### `eth_***`

The following `eth_*` namespace methods are exposed to support submitting transactions that go direct to miner to stay out of the mempool. These methods are of identical format to Geth's so that they can be dropped-in to a web3 library (e.g. [Ethers.js](https://docs.ethers.io/v5/) or [Web3.py](https://web3py.readthedocs.io/en/stable/)) but with the direct-to-miner functionality.

* `eth_call` - for simulation
* `eth_sendTransaction` - for sending transaction
* `eth_estimateGas` - got gas estimation

## Client Usage Example

Here's how we're thinking clients will use this API.

1. Client calls `eva_getMarkets` and `eva_getTokens` to explore available tradeable/priceable tokens. Likely only a subset of the available tokens will be of interested.
2. Client will subscribe to a handful of routes (e.g. USDC to DAI, WETH to UNI, and UNI to DAI) with a ladder of `amountIns` (e.g. `[1, 10, 100]`) to monitor token prices and market depth in real time (i.e. per each mined block).
3. Client will simultaneously monitor a CEX. When a cross-exchange opportunity is identified client will then,
1. Call `eva_getRoute` to request an optimal route for an exact `amountIn` based on their strategy.
2. Use the `contractCalldata` field to send transactions via their web3 client of choice
3. Transactions sent by clients pointed to our Ethereum node (see `eth_***` API above) have their txs remain out of the mempool.