# BlazePhoenix — agent-readable integration guide

> On-chain DEX aggregator on Base (8453), Ethereum (1), Optimism (10) and
> Arbitrum (42161). Every quote is computed ON-CHAIN by the Quoter contract
> (previewPlan) — the public API is a thin mirror of the chain. No API key,
> no signup, open CORS. Execution surplus is returned to the user.
> Token: BZPX (Base) 0x23113e72165a034265Ab8Bf2277CCB7a85Cb7483

## Quote a swap

GET https://blazephoenix.xyz/api/quote?chain=base&in=WETH&out=USDC&amountIn=1000000000000000000

- chain: 8453/base · 1/eth · 10/optimism · 42161/arbitrum
- in / out: 0x-token-address, ETH / WETH / USDC / BZPX, or ANY traded symbol —
  unknown tickers are resolved to the deepest-liquidity token on that chain and
  the resolution is echoed back in `resolved` (addresses recommended for
  precision; the batch endpoint takes addresses/built-in symbols only)
- amountIn: integer in the token's base units (wei-style)
- optional recipient=0x… → the response includes tx {to,data,value} — ready to
  sign and send to the Router (approve tokenIn for the router first)
- optional slippageBps (0–5000), deadlineSec (10–3600, default 120), exact=1
- `amountOut` in the response is the net output after the 0.28% protocol fee —
  compare that number across aggregators.
- errors: 400 bad_* · 422 no_route · 502 rpc_unreachable (stable JSON codes;
  502 carries retry-after: 3)
- poll freely: identical concurrent requests coalesce into ONE on-chain call
  and previews are edge-cached for ~1 block — meta.cache tells you which
  (miss | coalesced | hit). exact=1 and recipient requests are never TTL-cached.

## Batch (max 10 per call)

POST https://blazephoenix.xyz/api/quote/batch
{"requests":[{"chain":"base","in":"WETH","out":"USDC","amountIn":"1000000000000000000"}]}

## Pool X-Ray (phantom-liquidity scanner)

GET https://blazephoenix.xyz/api/xray?chain=base&token=BZPX

For any token, compares its deepest pools' Dexscreener-reported reserves against
a live balanceOf(pair) read on-chain. Returns per-pool + summary:
reportedLiquidityUsd vs realLiquidityUsd, phantomPct (advertised depth NOT in the
pool contracts), maxSafeTradeUsd (≤1% impact), and a verdict
(healthy | elevated | high | insufficient_data). Every figure is reproducible
with one `cast call ... balanceOf(address)`. Interactive: /?tab=xray

## Start here (discovery + monitoring)

- Discovery root (the API describes itself): https://blazephoenix.xyz/api
- Health (no upstream calls — poll freely):  https://blazephoenix.xyz/api/health
- Live stats (fills/traders per chain, from on-chain events, reproducible):
  https://blazephoenix.xyz/api/stats
- Every 200 quote response is self-describing: `units` states the amount
  format and `links` carries docs/openapi/manifest/sdk — an agent that sees
  one response can bootstrap the whole integration.

## Machine-readable references

- OpenAPI 3.1 spec:   https://blazephoenix.xyz/api/openapi.json
- Protocol manifest:  https://blazephoenix.xyz/api/manifest
  (contracts per chain, token, Swap/Surplus event topic0s for indexers)
- Human docs + live playground: https://blazephoenix.xyz/?tab=api

## SDK

npm i @blazephoenix/sdk   (TypeScript, ESM+CJS; viem optional)
repo: https://github.com/blazephoenixxyz-crypto/SDK

## Deep links (open the site pre-filled)

https://blazephoenix.xyz/?tab=swap&chain=base&in=ETH&out=BZPX&amt=0.5

## Index our fills (data platforms)

One `Swap` event per fill on the Router of each chain
(topic0 0xd6d34547c69c5ee3d2667625c188acf1006abb93e0ee7cf03925c67cf7760413).
Re-run any fill's quote at its block and compare with the executed amount to
verify our quoted-vs-executed record — no permission needed.

## Verified contract addresses (searchable)

Base (8453):     Router 0x2a779f9Be49aac57495A8B6467Cc325a8a47Eb9f ·
                 Quoter 0x4cEF0615614B212895F45Aa1D4833B16666E18d3 ·
                 Staking 0x3f60C7aa0c36a78D200405feBE143d2Cf3fA0c77 ·
                 BZPX 0x23113e72165a034265Ab8Bf2277CCB7a85Cb7483
Ethereum (1):    Router 0xE1aE5f49013920CF71De8CED4043e14C4d63416b ·
                 Quoter 0x4a20AA0912388ff7A9221Ab6BFC224cc20Baa0c3
Optimism (10) &
Arbitrum (42161): Router 0x7262e7483ab6f0db7b8f90eC3a9de3B02Ab36F6A ·
                 Quoter 0xfB18EF6f62A0278A273Af4b7A46b454F9E482dc2

## Proof of solvency (live, reproducible)

- Full report (HTML, refreshed from chain ~10 min, every solvency() field):
  https://blazephoenix.xyz/solvency
- README badge (shields.io endpoint, live isSolvent()):
  ![solvency](https://img.shields.io/endpoint?url=https%3A%2F%2Fblazephoenix.xyz%2Fapi%2Fbadge)
- Reproduce: `cast call 0x3f60C7aa0c36a78D200405feBE143d2Cf3fA0c77 "isSolvent()(bool)" --rpc-url https://mainnet.base.org`

## Embeddable solvency badge (live isSolvent() from chain)

<iframe src="https://blazephoenix.xyz/widget/solvency.html" width="280"
height="70" style="border:0" title="BlazePhoenix solvency"></iframe>

## Long-tail swap pages

Curated pair landing pages exist at /swap/<chain>-<in>-<out>, e.g.
https://blazephoenix.xyz/swap/base-eth-bzpx — all listed in /sitemap.xml.

Contact: contact@blazephoenix.xyz · X: @blazephoenyx