# The free quote API, the SDK and the MCP server: three doors, one on-chain quote

> Canonical: https://blazephoenix.xyz/learn/api-sdk-mcp
> License: CC BY 4.0 (attribution + link) · © 2026 BlazePhoenix
> Updated: 2026-07-27

Three ways into the same on-chain quote: a free keyless HTTP API, a TypeScript SDK, and an MCP server exposing quotes and token scans as native AI-agent tools. High-volume callers bring their own RPC.

There is one engine underneath and three ways to reach it. The API is HTTP and speaks to anything. The SDK is TypeScript and removes the boilerplate. The MCP server exposes the same operations as tools an AI agent can call on its own. Whichever door you pick, the number you get back was computed by the Quoter contract on-chain — the API is a thin mirror of the chain, not a pricing service with an opinion.

That distinction is the reason this integration is worth wiring: you are not trusting our server to be honest about a price. You are asking a contract, through us, and you can ask the same contract yourself with a free eth_call to confirm we relayed it faithfully.

## Door 1 — the HTTP API

No signup, no key, open CORS. The core call takes a chain, an input token, an output token and an amount in base units, and returns the net output after the 0.28% protocol fee — the number to compare across aggregators.

Add a recipient address and the response also carries a ready-to-broadcast transaction object: to, data and value. Sign it and send it. Approve the input token for the Router first.

Errors are stable JSON codes rather than prose, so a bot can branch on them: 400 for a malformed request, 422 when no route exists, 502 when the RPC is unreachable (carrying retry-after: 3). Identical concurrent requests coalesce into a single on-chain call, and previews are edge-cached for roughly one block, so polling is cheap and honest — meta.cache tells you whether you got a miss, a coalesced result or a hit.

```
Quote 1 WETH into USDC on Base:
  curl 'https://blazephoenix.xyz/api/quote?chain=base&in=WETH&out=USDC&amountIn=1000000000000000000'

Up to ten quotes in one call:
  curl -X POST https://blazephoenix.xyz/api/quote/batch \
    -H 'content-type: application/json' \
    -d '{"requests":[{"chain":"base","in":"WETH","out":"USDC","amountIn":"1000000000000000000"}]}'

Scan a token for phantom liquidity:
  curl 'https://blazephoenix.xyz/api/xray?chain=base&token=BZPX'
```

## Door 2 — the TypeScript SDK

The SDK wraps the same endpoints with types, retries and a polling helper, so a bot that needs a fresh quote every few seconds does not have to reimplement backoff, coalescing awareness and error mapping. It is RPC-optional: give it your own endpoint and it will read the chain directly; give it nothing and it uses the public API.

The design rule we hold to across versions: public surfaces do not break. Parameter names, response field names and error codes stay stable, because integrations are written once and left alone for months. New capability arrives as new optional fields, never as a renamed old one.

```
npm i github:blazephoenixxyz-crypto/SDK

import { quote } from '@blazephoenix/sdk';
const q = await quote({ chain: 'base', in: 'WETH', out: 'USDC', amountIn: 10n ** 18n });
console.log(q.amountOut);  // net of the 0.28% fee
```

## Door 3 — the MCP server (for AI agents)

Model Context Protocol is how an AI assistant discovers and calls external tools. Our MCP endpoint publishes the same operations as native tools: quote a pair, scan a token for phantom liquidity, read protocol statistics, check staking solvency. An agent connected to it can answer "is this token safe and what would I get for 1 ETH of it" without anyone writing glue code first.

This matters more than it sounds. Most protocols are reachable by an agent only through a human-shaped web page it has to guess at. Publishing tools with typed inputs turns a guess into a call — and an agent that can call you reliably will keep choosing you.

```
MCP endpoint:
  https://blazephoenix.xyz/mcp

Agent manifest and the full machine map:
  https://blazephoenix.xyz/.well-known/ai-plugin.json
  https://blazephoenix.xyz/capabilities.json
```

## Cost, honestly: why heavy callers should bring their own RPC

Every quote is an eth_call against a node, and node capacity is the one part of this stack that is not free to us. A page view costs nothing to serve; ten thousand automated quotes an hour do not. We would rather tell you that plainly than quietly degrade the service and let you wonder why your bot got slower.

So the posture is: casual and human-scale use stays free and keyless, exactly as it is today. Sustained, high-volume automation should bring its own RPC endpoint — a free tier from any node provider is enough — so that the cost of your traffic lands with you rather than being rationed away from everyone else. The SDK already accepts your endpoint; the API is moving to accept one too, and heavy callers who supply it will not be rate-limited against the shared pool.

Nothing about the arithmetic changes when you bring your own node. You are calling the same contract with the same parameters — you are just paying for your own reads. And if you ever suspect we are shading a number, that is precisely the setup that lets you prove it either way.

## Which door to pick

Building a Telegram or Discord bot, a dashboard, or anything that runs unattended: SDK, with your own RPC. Wiring a one-off script or a language we do not ship a package for: the HTTP API. Giving an AI assistant the ability to quote and scan on its own initiative: MCP.

All three return the same number, because all three are asking the same contract. That is the whole point of computing the quote on-chain: there is no version of the price that only we can see.

**Verify it yourself:** Run the curl quote above, then reproduce the same figure directly against the Quoter contract with a free eth_call (previewPlan) — the API is a mirror, and this is how you check the mirror is flat

Related: https://blazephoenix.xyz/learn/on-chain-quoting · https://blazephoenix.xyz/learn/phantom-liquidity · https://blazephoenix.xyz/learn/integrated-dexes · https://blazephoenix.xyz/learn/eightfold-dispatcher