# Aggregator API

The XOXNO Aggregator API provides optimal swap routing across multiple decentralized exchanges on MultiversX. It analyzes liquidity pools from xExchange, AshSwap, JEX, and OneDex simultaneously to find the best execution path for any trade, including split routes across multiple pools and reverse quotes.

## Base URL

```
https://swap.xoxno.com
```

## Endpoints

| Endpoint              | Method | Description                                |
| --------------------- | ------ | ------------------------------------------ |
| `/api/v1/quote`       | GET    | Get optimal swap route and quote           |
| `/api/v1/pair-config` | GET    | Check pair support and token configuration |
| `/health`             | GET    | Service health check                       |

## Features

### Multi-DEX Routing

Routes are evaluated across all supported DEXs simultaneously. The router uses a beam search over the combined liquidity graph, scoring paths multiplicatively so the best route wins regardless of which exchange holds the deepest liquidity.

### Split Routing

For large trades, the optimizer automatically splits an order across multiple paths to minimize price impact and maximize output. The default split optimizer uses the **hybrid** algorithm (see [Routing Algorithms](#routing-algorithms) below).

### Reverse Quotes

Provide `amountOut` instead of `amountIn` to calculate exactly how much input is required to receive a specific output amount.

### Arbitrage Detection

When `from` and `to` are the same token, the API finds profitable arbitrage cycles across the DEX graph. See the [quote endpoint](https://docs.xoxno.com/developers/quote#arbitrage-mode) for configuration parameters.

### LP Token Support

The API can route through LP token mint and burn operations, enabling single-transaction entry and exit from liquidity positions. Enable with `includeLpRoutes=true`.

## Routing Algorithms

The `algorithm` parameter on the [quote endpoint](https://docs.xoxno.com/developers/aggregator-api/quote) controls how trade amounts are allocated across paths:

| Algorithm    | Strategy                                                                                                                             | Best For                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `greedy`     | Incrementally allocates chunks to the highest-rate path; early termination on declining marginal returns. \~99% optimal.             | Small to medium trades where latency matters       |
| `lagrangian` | Binary search on the Lagrange multiplier to equalize marginal rates across all active paths. Mathematically optimal for convex AMMs. | Large trades where output maximization is critical |
| `hybrid`     | Runs both algorithms and returns whichever produces more output.                                                                     | All use cases (default)                            |

{% hint style="info" %}
Use `hybrid` unless you have a specific reason to prefer one algorithm. It adds minimal latency while providing the optimality guarantees of the Lagrangian approach.
{% endhint %}

## Quick Example

```bash
# Forward quote: how much USDC for 1 WEGLD?
curl "https://swap.xoxno.com/api/v1/quote?\
from=WEGLD-bd4d79&\
to=USDC-c76f1f&\
amountIn=1000000000000000000"

# Reverse quote: how much WEGLD to receive exactly 100 USDC?
curl "https://swap.xoxno.com/api/v1/quote?\
from=WEGLD-bd4d79&\
to=USDC-c76f1f&\
amountOut=100000000"
```

## Response Overview

All successful responses include:

* Optimal input and output amounts (raw and human-readable)
* Exchange rate and estimated price impact
* Minimum output amount after slippage
* Detailed path breakdown (optional, controlled by `includePaths`)
* Ready-to-use transaction data (`txData`)
* Fee breakdown

## Child Pages

* [Quote Endpoint](https://docs.xoxno.com/developers/aggregator-api/quote) — Full parameter reference, response schema, and examples
* [Pair Configuration](https://docs.xoxno.com/developers/aggregator-api/pair-config) — Validate token support and retrieve decimal metadata
* [Integration Guide](https://docs.xoxno.com/developers/aggregator-api/integration-guide) — Step-by-step integration walkthrough
* [Error Reference](https://github.com/XOXNO/docs/blob/main/developers/aggregator-api/error-reference.md) — Complete error codes and resolution guidance