swap.thorchain: Instructions file for Codex

AGENTS.md — working on this codebase

Instructions for AI coding agents contributing to swap.thorchain.org (the runtime guidance served to browsing agents lives at /AGENTS.md on the site, generated from src/lib/agent/discovery.ts — this file is about the code).

What this is

Next.js (App Router, TypeScript, Tailwind) web UI for native cross-chain swaps, powered by THORChain and Maya Protocol. Users sign in their own wallets, or use memoless ("instant") swaps with no wallet connection.

Two-component architecture:

• UI — this repo.
• Backend API — the swap aggregator: https://api.thorchain.org/v1 (quotes/routing, x-api-key gated) and https://api.thorchain.org/memoless/api/v1 (memoless swaps, no key). Protocol metadata (pools, mimir, THORNames, balances) comes from THORNode/Midgard gateways — see src/lib/api.ts and src/lib/thorchain-api.ts.

Commands

• npm run dev — dev server (Turbopack). Check whether one is already running before starting another.
• npx tsc --noEmit -p tsconfig.json — typecheck; this is the CI-relevant check (next lint is currently broken).
• npm run build — production build (standalone output, single instance — in-memory rate limiting and idempotency stores rely on this).

Key areas

• src/components/swap/ — swap flow UI; src/lib/wallets.ts — wallet/TCSwap SDK config (env vars in .env.example).
• src/lib/tronlink.ts — a connector the SDK does not ship, registered in wallets.ts like any @tcswap/wallets/* one. Exodus is not one of these: it lives in the SDK as @tcswap/wallets/exodus (the browser extension), added in ../TCSwap. Mind the version — through 4.3.26 that subpath was an alias for Exodus's unrelated Passkeys wallet, which has always had its own @tcswap/wallets/passkeys export and still does; only 4.3.27 onwards carries the extension connector, so package.json must ask for at least that. Brave Wallet is in the SDK too, as @tcswap/wallets/brave (connectBrave, 4.3.34 onwards): it reaches both of Brave's accounts, EVM and Solana, through Brave's own providers, where connectEVMWallet with WalletOption.BRAVE gets the EVM account only, from whichever extension owns window.ethereum. Rabby is WalletOption.RABBY (4.3.35 onwards) on the SDK's connectEVMWallet, which uses the provider Rabby announces over EIP-6963 (rdns io.rabby) rather than window.ethereum — Rabby takes that from MetaMask only when set as the default wallet, and flags it isMetaMask too. Binance Wallet is the SDK's @tcswap/wallets/binance (connectBinance, 4.3.37 onwards): the Binance Web3 Wallet extension injects everything under the window.binancew3w namespace — an EIP-1193 EVM provider (ethereum, also announced over EIP-6963 as com.binance.wallet, the connector's last-resort lookup), a Phantom-shaped Solana one (solana), a Unisat-compatible Bitcoin one (bitcoin, mirrored as window.unisat flagged isBinance on builds without the namespaced copy), and its own Tron provider (tron), which answers getAccount()/signTransaction() rather than TronLink's tronWeb surface. The Bitcoin provider exists only in the Binance App's in-app dApp browser — the Chrome extension serves EVM, Solana and TRON only, so the app filters BTC out of the wallet's chain list (supportedChains in src/lib/wallets.ts). WalletConnect is the SDK's @tcswap/wallets/walletconnect (connectWalletconnect), listed only when NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID is set. One QR scan connects every selected chain the wallet supports; the app warns about the rest. A reload restores the stored sessions without a QR code (restoreOnly), and a session ended from the phone removes its chains (onWalletconnectDisconnect, then disconnectWallet(WALLETCONNECT, chains)). The connect dialog calls preloadWalletconnect when it opens, so the QR modal opens at once, and isWalletconnectDismissed tells a closed QR modal from a real error. Needs @tcswap/wallets 4.3.36 or later.
• Disconnect a wallet with core's disconnectWallet (@tcswap/core 4.1.36 or later), not disconnectChain per chain. A chain holds only the last wallet connected on it, so disconnectChain may hit another wallet; disconnectWallet ends only this wallet's sessions and hands each chain back to another connected wallet.
• isPrivateSwap in src/store/limit-swap-store.ts — the PRIVATE tab: the swap is routed through Houdini Swap (AppConfig.privateProvider, providers: ["HOUDINI"] on the aggregator, @tcswap/plugins/houdini in the SDK) instead of the native protocols. Each tab has its own asset list (useModeAssets in src/hooks/use-assets.ts), and a private route is priced floating and tracked by its Houdini order id (Transaction.providerSwapId). See docs/private-swaps.md before touching any HOUDINI branch.
• public/widget.js + src/app/widget/ — the embeddable swap iframe. The loader mirrors the host page's dark/light mode into the iframe: it reads the effective background painted behind the widget (so a .dark class, data-theme, or a CSS-variable swap all work without configuration), boots the iframe with ?theme=, and pushes later changes over postMessage — src/app/widget/theme.ts holds that contract plus the pre-paint script that stops the embed flashing the wrong theme. Keep widget.js plain unbundled ES5-style script — it runs as-is on third-party sites.
• src/lib/agent/discovery-files.ts — single registry of every static discovery file (/llms.txt, /AGENTS.md, /openapi.json, /.well-known/*, …), served by src/proxy.ts before filesystem routes. Add new agent/developer surfaces here, not as route folders.
• src/lib/agent/discovery.ts — markdown content for /AGENTS.md, /llms.txt, /llms-full.md, /auth.md, and the agent skill; src/lib/agent/openapi.ts — the OpenAPI document.
• src/lib/agent/developer-portal.ts — content for /developers.md; src/app/developers/page.tsx is a hand-built HTML mirror — keep the two in sync.
• src/lib/agent/developer-docs.ts — the named developer resources at /developers/<topic> (quickstart, api, mcp, auth, sdks, webhooks). One markdown source per topic feeds both the HTML page (src/app/developers/[topic]/page.tsx, rendered by src/components/markdown-article.tsx) and the .md twin, so they cannot drift. Topic metadata lives in developer-topics.ts — split out so developer-portal.ts can link the pages without an import cycle.
• The MCP server is anonymous and must stay that way: publish no /.well-known/oauth-* metadata and no registration endpoint, and never link one from a discovery document either — a linked path reads as published metadata. MCP connectors read protected-resource metadata as "OAuth required" and then fail a sign-in flow against a site with no accounts — see the note in docs/agent-readiness/orank.md, testNoAuthorizationSurfaceBlocksConnectors, and the link guard in testDiscoveryDocsAreTruthful (test/agent-contracts.test.mjs), which also asserts that every own-origin URL a discovery document links resolves.
• sdk/python, sdk/go — dependency-free clients over this site's keyless public surfaces (the MCP tools and the support endpoints). The TypeScript SDK is the already-published @tcswap/sdk from the TCSwap monorepo — do not add a second npm client for the same APIs. src/lib/agent/sdks.ts is the single list the developer docs, llms.txt, and AGENTS.md render from; PyPI publication is still a manual step (see docs/agent-readiness/orank.md).
• src/lib/agent/skills.ts — published agent skills (one per capability area, YAML frontmatter); routes and the skills index are generated from AGENT_SKILLS.
• src/lib/agent/markdown-pages.ts — markdown twins: .md appended to any content page URL, plus Accept: text/markdown negotiation, resolved in src/proxy.ts.
• src/lib/agent/pricing.ts — content for /pricing.md; src/lib/agent/agent-mode.ts — the /?mode=agent view (JSON or markdown by Accept), derived from MCP_TOOLS and developerEndpoints so it stays in sync.
• src/lib/agent/mcp-tools.ts — tool definitions and the server card (edge-safe, no node:crypto); src/lib/agent/mcp-server.ts + src/lib/agent/mcp-ui.ts — public MCP server at /mcp (stateless streamable HTTP, read-only THORNode tools, MCP Apps quote view). public/robots.txt carries AI Content-Signal lines whose ordering matters.
• src/app/api/ — support endpoints (/api/v1/* canonical, unversioned aliases kept); JSON errors via src/lib/api-error.ts, idempotency via src/lib/agent/idempotency.ts.
• src/lib/rate-limit.ts — per-client limiter shared by /mcp and the support endpoints. Key on cf-connecting-ip (or the last forwarded hop), never the first x-forwarded-for entry: the edge appends to whatever the caller sent, so the leftmost value is forgeable.
• src/components/chatwoot-widget.tsx — the live-chat widget (a Chatwoot Website-channel inbox), rendered only when NEXT_PUBLIC_CHATWOOT_WEBSITE_TOKEN is set. There is no bug-report form or /api/report-bug endpoint any more — support is live chat and email.
• server.json (repo root) + src/app/.well-known/mcp-registry-auth/route.ts — the official MCP Registry record and its domain-ownership proof (served from MCP_REGISTRY_AUTH). Keep server.json's version in step with MCP_SERVER_INFO.version; publishing steps are in docs/agent-readiness/mcp-registry.md.
• docs/agent-readiness/ — notes on agent-readiness scanners and decisions; read before changing discovery surfaces.
• src/lib/banner.ts + src/app/api/banner/route.ts + src/hooks/use-banner.ts — the announcement banner. It is content owned by the affiliate admin (swap.thorchain-admin, admin-only /banner, published at its /api/banner), not by this repo: this app proxies that endpoint through its own origin (30s cache, BANNER_API_URL) and each tab polls every 10 min once the browser is idle, so a banner goes up without a deploy and never competes with the swap's own requests. An icon uploaded there is proxied the same way at /api/banner/icon, so the banner is always same-origin. Nothing is bundled — an unreachable admin means the last-seen banner, or none. Its copy is translated by the admin on save and is deliberately not in src/i18n/messages. See docs/banner.md.