synroute-quote-demo

A tiny, zero‑framework Vite + TypeScript demo that shows how little code it takes to integrate the Synthra SynRoute API — type an amount, get a live quote, and swap with one click.

The entire integration is a single fetch to /v1/quote (plus /v1/swap for the optional swap). No SDK, no runtime dependencies — everything lives in one readable src/main.ts.

---

✨ Features

• Live quotes — the output updates in real time as you type, with the route the engine found.
• Token list from chain — tokens are loaded from the public Synthra token list and filtered to the active chain, complete with logos.
• One‑click swap — /v1/swap returns the approval metadata and a ready‑to‑send transaction; the demo handles approval, the optional Permit2 signature, and the swap.
• Real wallet state — connect status is reflected live (connected address chip + dynamic button label) and stays in sync with accountsChanged.
• Zero runtime dependencies — plain TypeScript, the built‑in fetch, and window.ethereum. Vite + TypeScript are dev‑only.

🧠 How it works

The whole quote integration is this:

const res = await fetch(`${API_BASE}/v1/quote`, {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-api-key': API_KEY },
  body: JSON.stringify({
    chainId: 5042002,          // Arc
    tokenIn,                   // address or alias
    tokenOut,
    amount: rawAmount,         // raw integer (wei-like), per token decimals
    tradeType: 'EXACT_INPUT',  // or 'EXACT_OUTPUT' to target the output instead
  }),
})
// → { amountOut, amountOutDecimals, routeString, ... }

For the swap, POST /v1/swap returns the approval info and an executable transaction, so submitting is just sending the calldata the API gives you:

1. Approve the token (one‑time): approval.tokenApproval.approveTransaction.
2. Permit2 signature (permit2 mode only): sign approval.permit2.typedData with eth_signTypedData_v4, then call /v1/swap again with the signature.
3. Swap: send the returned transaction (to, data, value).

🚀 Getting started

Requirements: Node.js ≥ 18 (uses the built‑in fetch), a Synthra API key, and an injected wallet (e.g. MetaMask / Kevo) for swapping.

git clone <your-fork-url> synroute-quote-demo
cd synroute-quote-demo
npm install
cp .env.example .env       # then set VITE_SYNTHRA_API_KEY
npm run dev                # open the printed local URL

Build for production:

npm run build && npm run preview

⚙️ Configuration

Vite exposes only VITE_‑prefixed variables to the browser. Set them in .env (see .env.example):

Variable	Description
VITE_SYNTHRA_API_BASE	API base URL. Defaults to https://trading-api.synthra.org.
VITE_SYNTHRA_API_KEY	Your Synthra API key (sent as the x-api-key header).

⚠️ These ship inside the built bundle, so use a test key for any public demo. In production, proxy the API through a small backend instead of exposing the key.

🕹️ Usage

1. Pick the input/output tokens from the dropdowns (loaded live from the Synthra token list).
2. Type an amount — the quote updates as you type.
3. Click Connect & swap to connect an injected wallet, then approve and swap. Once connected, the chip shows your address and the button becomes Swap.

🛠️ Customizing

All knobs are constants at the top of src/main.ts:

Constant	Purpose
CHAIN_ID	Execution chain id. Defaults to Arc (5042002).
DEFAULT_IN / DEFAULT_OUT	Default token pair (by symbol).
TOKENLIST_URL	Source token list (Uniswap token‑list format).
APPROVAL_MODE	'permit2' (Universal Router, recommended) or 'erc20' (SwapRouter02).

Approval modes. With permit2, the token is approved to Permit2 once and each swap is authorized by a gasless EIP‑712 signature (the swap targets the Universal Router). With erc20, the token is approved directly to SwapRouter02. On Arc, permit2 is the recommended path.

📁 Project structure

.
├── index.html        # markup + styles for the swap card
├── src/
│   ├── main.ts       # the entire integration: quote, swap, token list, wallet
│   └── vite-env.d.ts # ambient types (env vars + injected wallet)
├── .env.example
└── package.json

🧩 Tech stack

• Vite + TypeScript (strict) — dev tooling only.
• Native fetch and the injected window.ethereum provider — no libraries shipped to the browser.

📝 Notes & caveats

• CORS: the browser calls trading-api.synthra.org directly. If your demo origin isn’t allowed by the API, quotes will fail with a CORS error — serve the demo from an allowed origin or proxy the calls.
• Arc gas: Arc’s native‑USDC is an ERC20‑facade precompile that gas estimation under‑models, so the swap is sent with generous gas headroom (unused gas is refunded). See arcGasHeadroom in src/main.ts.
• Scope: this is an educational demo. Use test keys and testnets, and review the code before adapting it for production.

🔗 Links

• Synthra developer docs: https://developers.synthra.org
• Synthra token list: https://github.com/Synthra-swap/tokenlists

License

MIT