docs/api-reference

# API Reference

## Agent Discovery

/.well-known/agent-registration.json — EIP-8004 agent metadata
/.well-known/x402 — x402 payment discovery (networks, pricing, facilitator)

## x402 Payment Protocol

Native x402 v2 support. Any x402-compatible SDK works — no registration, no API key.

Flow:
1. POST /quote → 402 + PAYMENT-REQUIRED header
2. Agent signs EIP-3009 transferWithAuthorization (gasless)
3. POST /quote + PAYMENT-SIGNATURE header → 200 + quote

PAYMENT-REQUIRED header (base64 JSON):
{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "100",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xd55dDB23D8B5BE8085C1CD47A570a96b8752637a1",
    "maxTimeoutSeconds": 60
  }],
  "resource": {
    "url": "/quote",
    "description": "DEX aggregator swap quote",
    "mimeType": "application/json"
  }
}

Facilitator endpoints (for SDK integration):
GET   /.well-known/x402    Discovery: networks, pricing, facilitator URL
POST  /x402/verify         Verify payment signature off-chain
POST  /x402/settle         Settle payment on-chain (transferWithAuthorization)

## POST /quote

Get the best swap route across all supported DEXes.

Request:
{
  "chain_id": 8453,
  "token_in": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "token_out": "0x4200000000000000000000000000000000000006",
  "amount_in": "1000000000",
  "amount_usd": 1000.0,
  "slippage_bps": 50,
  "taker": "0x1111111111111111111111111111111111111111",
  "allow_partial": false
}

Response:
{
  "dex": "SmartRouter",
  "output": "401234567890123456",
  "gas_estimate": "184000",
  "source": "local",
  "router": "0x8b4F808...",
  "calldata": "0x...",
  "execution": {
    "spender": "0x8b4F808...",
    "target": "0x8b4F808...",
    "calldata": "0x...",
    "value": "0x0"
  },
  "steps": [...],
  "route_path": "USDC>[UniV3:500]>WETH",
  "price_impact_bps": 8,
  "pool_grades": ["A"],
  "route_executable": true,
  "route_unexecutable_reason": null,
  "last_sync_block": 28456789,
  "sync_lag_ms": 2100,
  "tax_in_bps": 0,
  "tax_out_bps": 0
}

## POST /compare/simulate

Compare normalized execution payloads by dry-run realized output. Winner selection uses actualOutput, not quotedOutput.

Request:
{
  "chainId": 8453,
  "candidates": [{
    "providerId": "odos",
    "target": "0x2222222222222222222222222222222222222222",
    "data": "0x1234abcd...",
    "value": "0x0",
    "inputToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "outputToken": "0x4200000000000000000000000000000000000006",
    "inputAmount": "1250000000",
    "approveTarget": "0x8b4F80818376FE1903c930A2a74823611732c7f4",
    "quotedOutput": "2489150000"
  }]
}

Response:
{
  "results": [{
    "providerId": "odos",
    "status": "ok",
    "success": true,
    "quotedOutput": "2489150000",
    "actualOutput": "2487000000",
    "accuracyDelta": "-2150000",
    "accuracyBps": 9991,
    "error": null
  }],
  "winnerProviderId": "odos"
}

## POST /auth/quota/claim

Applies purchased quota from an on-chain transaction. Requires X-API-Key header.

Request:
{
  "chain_id": 8453,
  "tx_hash": "0x..."
}

Response:
{
  "chain_id": 8453,
  "tx_hash": "0x...",
  "purchased_quotes": 10000,
  "quota_total": 10050,
  "quota_used": 42,
  "quota_remaining": 10008
}

## GET /health

Health check with pool counts, sync status, memory.

{
  "status": "ok",
  "version": "1.5.8",
  "uptime_secs": 45000,
  "pools": { "total": 12500, "v2": 3000, "v3": 5000, "v4": 200, ... },
  "sync": { "max_lag_ms": 2500, "v2_last_block": 28456789, ... },
  "memory": { "total_tracked_mb": 180, "v3_estimated_mb": 120, ... },
  "system": { "rss_mb": 280, "jemalloc_allocated_mb": 200, "num_cpus": 4 },
  "grades": [{ "chain": "Base", "distribution": [500,1200,2000,800,200,50] }],
  "graphs": [{ "chain": "Base", "tokens": 450, "edges": 8000 }]
}

## GET /api/tokens

Token registry: address to chain/symbol/decimals.

{
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": { "chain_id": 1, "symbol": "USDC", "decimals": 6 },
  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913": { "chain_id": 8453, "symbol": "USDC", "decimals": 6 },
  "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1": { "chain_id": 42161, "symbol": "WETH", "decimals": 18 },
  ...
}

## GET /api/pool/:chain_id/:address

Pool debug: tokens, reserves/liquidity, tick state, grade.

{
  "address": "0x...",
  "chain_id": 8453,
  "found_in": "v3",
  "grade": "A",
  "v3": {
    "token0": "0x833589f...",
    "token1": "0x4200000...",
    "fee": 500,
    "liquidity": "123456789012345",
    "tick": -200100,
    "tick_count": 842
  }
}

## GET /stats/pairs

Query params: chain_id, sort_by (total|last_hour|recent|trending), limit

{
  "total_pairs": 250,
  "total_queries": 150000,
  "pairs": [{
    "token_in": "0x833589f...",
    "token_out": "0x4200000...",
    "total": 5000,
    "local": 4800,
    "path_hint": 150,
    "not_found": 50,
    "avg_latency_ms": 0.8
  }]
}

## Error Codes

400  Bad Request      invalid token address, unsupported chain_id
401  Unauthorized     missing or invalid API key / payment signature
402  Payment Required quota exhausted; PAYMENT-REQUIRED header with x402 v2 payload
404  Not Found        no route found for the given pair/amount
503  Unavailable      RPC pool exhausted, service degraded