# Cross-Chain Liquidity & Execution Route Optimizer

> **B2A API** — built for autonomous AI agents, not humans.
> **Zero LLM at runtime** — all computation is deterministic math on on-chain data.
> **Monetised via L402** — Lightning Network micropayments (≈$0.006 per query).

## What this API does

Given a token swap intent (`ETH → USDC`, `5 ETH`, `ethereum + arbitrum + base`),
this API:

1. Fetches live quotes from **1inch** (single-chain DEX aggregator) and **Li.Fi** (cross-chain bridge + DEX).
2. Scores every route using the **True Execution Cost (TEC)** formula:
   ```
   TEC   = C_slippage + C_gas + C_bridge + C_time_penalty
   score = (amount_out × target_price_usd) - TEC - amount_in_usd
   ```
3. Returns the **highest-scoring viable route** plus all candidates ranked.

## When to call this API

Call this API when:
- You are about to execute a DeFi token swap on any EVM chain.
- You want to know whether routing cross-chain is cheaper than same-chain.
- You need a slippage estimate before signing a transaction.
- You need to compare 1inch vs Li.Fi routes with an objective cost metric.

Do NOT call this API if you have no Lightning Network payment capability.

## Authentication: L402 Lightning Protocol

This API uses the **L402 standard** (IETF draft: HTTP 402 + Lightning).

### Step-by-step payment flow

```
1. POST /v1/quote
   Body: { "token_in": "ETH", "token_out": "USDC", ... }
   → HTTP 402
     WWW-Authenticate: L402 macaroon=<base64url_token>, invoice=<BOLT11_string>

2. Pay the BOLT11 invoice on the Lightning Network.
   Amount: typically 10 satoshis ≈ $0.006 USD.
   Your Lightning wallet returns a 32-byte preimage (proof of payment).

3. POST /v1/quote  (same body, add Authorization header)
   Authorization: L402 <macaroon>:<preimage_hex>
   → HTTP 200  (route data)
```

The macaroon expires in **10 minutes** (600 seconds).
If you receive HTTP 401 with `{"detail": "macaroon expired"}`, start over from step 1.

### Parsing the WWW-Authenticate header

```
WWW-Authenticate: L402 macaroon=eyJ..., invoice=lnbc100n1p...

Split on ", invoice=" to separate the two values.
macaroon  = everything after "macaroon=" up to ", invoice="
invoice   = the BOLT11 string starting with "lnbc"
preimage  = 32-byte hex string returned by your Lightning wallet after payment
```

### Authorization header format

```
Authorization: L402 <macaroon_base64url>:<preimage_hex_64chars>
```

## Endpoint: POST /v1/quote

**Requires payment.** Returns the optimal swap route.

### Request body (JSON)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `token_in` | string | yes | Input token symbol. Supported: `ETH`, `USDC`, `USDT`, `DAI`, `WETH` |
| `token_out` | string | yes | Output token symbol. Must differ from `token_in` |
| `amount_in` | float | yes | Input amount in token units (e.g. `5.0` for 5 ETH). Must be > 0 |
| `amount_in_usd` | float | yes | USD value of `amount_in` at call time. Agent pre-computes this from a price oracle |
| `target_price_usd` | float | yes | Spot price of `token_out` in USD (e.g. `1.0` for USDC) |
| `chains` | array[string] | yes | Chains to search. Any subset of: `ethereum`, `arbitrum`, `base`, `optimism`, `polygon` |
| `max_slippage_bps` | int | no | Max acceptable slippage in basis points. Default: `100` (1%). Range: 1–2000 |
| `agent_time_value_per_second` | float | no | USD cost of 1 second of waiting (bridge time penalty coefficient). Default: `0.0001` |
| `max_bridge_time_seconds` | int | no | Hard limit on cross-chain bridge time. Default: `900` (15 min). Routes above this are excluded |

### Minimal example request

```json
{
  "token_in": "ETH",
  "token_out": "USDC",
  "amount_in": 5.0,
  "amount_in_usd": 18500.0,
  "target_price_usd": 1.0,
  "chains": ["arbitrum", "base"]
}
```

### Response structure

```json
{
  "optimal_route": {
    "route_id": "lifi_arbitrum_base_ETH_USDC_1718000000",
    "source": "lifi",
    "route_type": "bridge_then_swap",
    "chain_in": "arbitrum",
    "chain_out": "base",
    "token_in": "ETH",
    "token_out": "USDC",
    "amount_out": 18380.5,
    "amount_out_min": 18196.7,
    "effective_rate": 3676.1,
    "profit_score": -120.3,
    "net_output_value_usd": 18380.5,
    "true_execution_cost_usd": 0.82,
    "slippage_usd": 0.50,
    "gas_usd": 0.02,
    "bridge_fee_usd": 0.30,
    "time_penalty_usd": 0.00,
    "slippage_bps": 50,
    "pool_liquidity_usd": 12000000.0,
    "bridge_time_seconds": 120,
    "is_viable": true,
    "disqualification_reason": null
  },
  "all_routes": [ ... ],
  "gas_snapshot": [ ... ],
  "meta": {
    "token_in": "ETH",
    "token_out": "USDC",
    "amount_in": 5.0,
    "chains": ["arbitrum", "base"],
    "latency_ms": 340,
    "viable_routes": 4,
    "discarded_routes": 1
  }
}
```

`optimal_route` is `null` when no route passes viability checks — relax
`max_slippage_bps` or `max_bridge_time_seconds` and retry.

## Free endpoints (no payment)

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Liveness probe. Returns `{"status": "ok"}` |
| `GET /info` | Pricing, supported chains, tokens, aggregators |
| `GET /openapi.json` | Full OpenAPI 3.1 specification |
| `GET /docs` | Swagger UI |

## Error reference

| HTTP status | Meaning | Action |
|-------------|---------|--------|
| 402 | Payment required | Read `WWW-Authenticate`, pay invoice, retry with `Authorization` header |
| 401 | Bad credentials | Macaroon expired or preimage wrong — restart L402 flow from step 1 |
| 422 | Invalid request body | Fix the field listed in `detail` |
| 503 | All aggregators down | Retry after 5–10 seconds |

## Cost model

- **Price**: 10 satoshis per query (≈ $0.006 at BTC = $60,000)
- **Macaroon TTL**: 600 seconds (10 minutes from payment)
- **Latency**: typically 200–500 ms (parallel aggregator fan-out)
- **Freshness**: quotes are discarded after 3 seconds — you always get live data

## Support

- Docs: /docs
- OpenAPI spec: /openapi.json
- Contact: peretzbatel123@gmail.com