\n );\n}\n```\n\n## Wallet Connection\n\nThe widget expects your app to provide the wallet context (wagmi, RainbowKit, AppKit, etc.). A typical integration uses `customWalletUI=\"provider\"` with `onRequestConnect` and `onRequestAccount` to wire the widget's connect/account buttons into your existing wallet modals — this is the recommended approach for most integrators.\n\n### Provider (recommended)\n\nWrap the widget inside your existing wallet provider. Pass `onRequestConnect` and `onRequestAccount` so the widget's built-in buttons open your modals. The widget inherits the wagmi context automatically.\n\n```tsx\nimport { useConnectModal, useAccountModal } from '@rainbow-me/rainbowkit';\n\nfunction SwapPage() {\n const { openConnectModal } = useConnectModal();\n const { openAccountModal } = useAccountModal();\n\n return (\n openConnectModal?.()}\n onRequestAccount={() => openAccountModal?.()}\n />\n );\n}\n```\n\nThis works the same way with AppKit or any other wagmi-compatible wallet kit — just swap the modal hooks.\n\n\n\n## Chain & RPC Configuration\n\nYour wagmi config **must include all Aori-supported chains** or approvals, wrapping/unwrapping, and chain switching will fail silently.\n\nImport `wagmiChains` and `buildTransports` from the widget package — these provide every supported chain with built-in RPC fallback (multiple public RPCs per chain, tried in order on error or rate-limit).\n\n```ts\nimport { wagmiChains, buildTransports } from '@aori/mega-swap-widget';\nimport { getDefaultConfig } from '@rainbow-me/rainbowkit';\nimport { aoriConfig } from './aori.config';\n\nconst wagmiConfig = getDefaultConfig({\n appName: 'My App',\n projectId: 'YOUR_WALLETCONNECT_PROJECT_ID',\n chains: wagmiChains,\n transports: buildTransports(aoriConfig.rpcOverrides),\n ssr: false,\n});\n```\n\nThere are two separate RPC paths in the widget:\n\n| Path | Source | Used for |\n| --- | --- | --- |\n| **Widget internal** | `rpcOverrides` in `AoriSwapWidgetConfig` | Balance fetching, quote pricing |\n| **Wagmi** | `buildTransports()` in your wagmi config | Signing, sending txs, chain switching |\n\n`rpcOverrides` in your `aori.config` only affects the widget's internal viem clients. Wagmi transports are configured separately via `buildTransports()` — any URLs passed there are **client-side JavaScript** and will be visible in the browser. Never pass private RPC URLs directly to `buildTransports`.\n\nTo keep private RPCs server-side for both paths, use the same relative proxy paths (e.g. `/api/rpc/1`) in your `rpcOverrides` and pass them to `buildTransports` as shown above. The browser hits your API route, which forwards to the real RPC with credentials from environment variables. See [Server-Side Proxying](#server-side-proxying) for how to set up the proxy routes.\n\n## Server-Side Proxying\n\nIn production you almost certainly want to keep your API key **and** private RPC URLs off the client. The widget supports this via two config fields: `vtApiBaseUrl` and `rpcOverrides`. Both accept relative paths that hit your own backend routes, which then forward requests upstream with the real credentials attached.\n\n### API Key Proxy (`vtApiBaseUrl`)\n\nInstead of passing `apiKey` in the client config, point `vtApiBaseUrl` at your own API route. The widget will send all transfer/quote requests there instead of directly to the Aori API.\n\n**Widget config:**\n\n```ts\nconst config: AoriSwapWidgetConfig = {\n vtApiBaseUrl: '/api/vt',\n // no apiKey needed — the server injects it\n // ...\n};\n```\n\n**Next.js API route** (`pages/api/vt/[...path].ts`):\n\n```ts\nimport type { NextApiRequest, NextApiResponse } from 'next';\n\nconst VT_UPSTREAM = 'https://transfer.layerzero-api.com/v1';\n\nexport default async function handler(req: NextApiRequest, res: NextApiResponse) {\n const { path } = req.query;\n const segments = Array.isArray(path) ? path.join('/') : path ?? '';\n const queryString = new URL(req.url!, `http://${req.headers.host}`).search;\n const upstreamUrl = `${VT_UPSTREAM}/${segments}${queryString}`;\n\n const apiKey = process.env.VT_API_KEY;\n if (!apiKey) {\n return res.status(500).json({ error: 'VT_API_KEY not configured' });\n }\n\n const headers: Record = {\n 'Content-Type': 'application/json',\n 'x-api-key': apiKey,\n };\n\n const upstream = await fetch(upstreamUrl, {\n method: req.method,\n headers,\n body: req.method !== 'GET' && req.method !== 'HEAD' ? JSON.stringify(req.body) : undefined,\n });\n\n const contentType = upstream.headers.get('content-type') ?? 'application/json';\n res.setHeader('Content-Type', contentType);\n res.status(upstream.status);\n\n const body = await upstream.text();\n res.send(body);\n}\n```\n\nThen set `VT_API_KEY` in your `.env` (or hosting provider's environment variables):\n\n```\nVT_API_KEY=your_aori_api_key\n```\n\n### Private RPC Proxy (`rpcOverrides`)\n\nThe same pattern works for RPC endpoints. Point each chain's override at a local route that forwards JSON-RPC requests to your private RPC, keeping the URL and any auth tokens server-side.\n\n**Widget config:**\n\n```ts\nconst config: AoriSwapWidgetConfig = {\n vtApiBaseUrl: '/api/vt',\n rpcOverrides: {\n 1: '/api/rpc/1',\n 10: '/api/rpc/10',\n 56: '/api/rpc/56',\n 8453: '/api/rpc/8453',\n 42161: '/api/rpc/42161',\n 143: '/api/rpc/143',\n 4326: '/api/rpc/4326',\n },\n // ...\n};\n```\n\n**Next.js API route** (`pages/api/rpc/[chainId].ts`):\n\n```ts\nimport type { NextApiRequest, NextApiResponse } from 'next';\n\nconst RPC_URLS: Record = {\n '1': process.env.ETHEREUM_RPC_URL,\n '10': process.env.OPTIMISM_RPC_URL,\n '56': process.env.BSC_RPC_URL,\n '8453': process.env.BASE_RPC_URL,\n '42161': process.env.ARBITRUM_RPC_URL,\n '143': process.env.MONAD_RPC_URL,\n '4326': process.env.MEGAETH_RPC_URL,\n};\n\nfunction jsonRpcError(res: NextApiResponse, id: unknown, code: number, message: string) {\n return res.status(200).json({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });\n}\n\nexport default async function handler(req: NextApiRequest, res: NextApiResponse) {\n if (req.method !== 'POST') {\n return res.status(405).json({ error: 'Method not allowed' });\n }\n\n const chainId = req.query.chainId as string;\n const rpcUrl = RPC_URLS[chainId];\n\n if (!rpcUrl) {\n return jsonRpcError(res, null, -32603, `RPC not configured for chain ${chainId}`);\n }\n\n try {\n const response = await fetch(rpcUrl, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(req.body),\n });\n\n res.setHeader('Cache-Control', 'no-store');\n return res.status(200).json(await response.json());\n } catch (error) {\n return jsonRpcError(res, null, -32603, error instanceof Error ? error.message : 'RPC request failed');\n }\n}\n```\n\n**.env:**\n\n```\nETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY\nOPTIMISM_RPC_URL=https://opt-mainnet.g.alchemy.com/v2/YOUR_KEY\nBSC_RPC_URL=https://bsc-mainnet.g.alchemy.com/v2/YOUR_KEY\nBASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY\nARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY\nMONAD_RPC_URL=https://your-monad-rpc.example.com\nMEGAETH_RPC_URL=https://your-megaeth-rpc.example.com\n```\n\n> **Not using Next.js?** The same approach works with any backend — Express, Fastify, Cloudflare Workers, etc. The proxy just needs to forward the request body upstream and return the response. The widget doesn't care what's behind the route as long as it speaks the same protocol (REST for VT, JSON-RPC for RPCs).\n\n## Props\n\n| Prop | Type | Default | Description |\n| -------------------- | ---------------------------------------- | -------------- | ------------------------------------------------ |\n| `config` | `AoriSwapWidgetConfig` | — | Widget configuration (required) |\n| `customWalletUI` | `'none' \\| 'provider'` | `'provider'` | `'provider'` wires into your wallet modals via callbacks; `'none'` hides all wallet UI |\n| `onRequestConnect` | `() => void` | — | Open the host app's connect modal |\n| `onRequestAccount` | `() => void` | — | Open the host app's account modal |\n| `onSwapSubmitted` | `(quoteId: string) => void` | — | Fires immediately after the user's signing/transaction steps complete and the order is submitted to the Aori backend. `quoteId` is the VT quote ID for tracking. |\n| `onSwapComplete` | `(data: SwapCompleteData) => void` | — | Fires when polling confirms the swap is settled on-chain. Returns `{ quoteId, aoriOrderHash, explorerUrl, details }` where `details` is the full Aori `/data/details` response. |\n| `onBlockedWallet` | `(data: BlockedWalletEvent) => void` | — | Fires after wallet screening completes. Returns `{ address, allowed, source? }` where `source` is `'chainalysis-oracle'` or `'screening-url'` (present when blocked). |\n| `onBaseTokenChange` | `(token: Asset) => void` | — | Callback when the base token changes |\n| `onQuoteTokenChange` | `(token: Asset) => void` | — | Callback when the quote token changes |\n| `className` | `string` | — | Additional CSS class on the root element |\n\n### Swap Lifecycle Hooks Example\n\nUse `onSwapSubmitted` to know when the order hits the Aori backend, and `onSwapComplete` to get the full details once it settles on-chain:\n\n```tsx\n {\n // Fires immediately after the user signs and the order is submitted.\n // quoteId is the VT quote ID — use it to track the order or just wait for onSwapComplete.\n }}\n onSwapComplete={({ aoriOrderHash, explorerUrl, details }) => {\n // Fires when polling confirms the swap is settled on-chain.\n // details is the full response from https://api.aori.io/data/details/${aoriOrderHash}\n\n // Redirect to a confirmation page\n router.push(`/confirmation?order=${aoriOrderHash}`);\n\n // Or persist to your own tx history\n const getEventTime = (type: string) =>\n details.events.find(e => e.event === type)?.timestamp ?? null;\n\n addToHistory({\n orderHash: aoriOrderHash,\n explorerUrl,\n inputAmount: details.inputAmount,\n inputChain: details.inputChain,\n outputAmount: details.outputAmount,\n outputChain: details.outputChain,\n srcTx: details.srcTx,\n dstTx: details.dstTx,\n // individual event timestamps — use these to show status progression in your UI\n createdAt: getEventTime('created'),\n receivedAt: getEventTime('received'),\n completedAt: getEventTime('completed'),\n failedAt: getEventTime('failed'),\n canceledAt: getEventTime('cancelled'),\n });\n }}\n/>\n```\n\nThe `SwapCompleteData` type:\n\n```ts\ninterface SwapCompleteData {\n quoteId: string; // VT quote ID (same value as onSwapSubmitted)\n aoriOrderHash: string; // Aori order hash, parsed from explorerUrl\n explorerUrl: string; // https://aoriscan.io/order/0x...\n details: AoriOrderDetails;\n}\n\ninterface AoriOrderDetails {\n orderHash: string;\n offerer: string;\n recipient: string;\n inputToken: string;\n inputAmount: string;\n inputChain: string;\n inputTokenValueUsd: string;\n outputToken: string;\n outputAmount: string;\n outputChain: string;\n outputTokenValueUsd: string;\n startTime: number;\n endTime: number;\n timestamp: number;\n srcTx: string | null;\n dstTx: string | null;\n events: Array<{\n event: string; // 'created' | 'received' | 'completed' | 'failed' | 'cancelled'\n timestamp: number;\n }>;\n}\n```\n\n### What You Can Build With These Hooks\n\nThe data from `onSwapComplete` is generic — you decide what to do with it. Some examples:\n\n- **Tx history component** — render a live list of swaps with status, amounts, and links\n- **Confirmation page** — redirect to a dedicated page after settlement with order details\n- **Custom notification** — show a toast, modal, or banner with the swap result\n- **Analytics** — send swap events to your own backend or analytics pipeline\n- **Order detail page** — use `aoriOrderHash` to link to or render a full order breakdown\n- **Just the data** — store it in state, context, or your DB and use it however your app needs\n\nThe hooks don't dictate any UI. They hand you the data at the right moment — you wire it into whatever component or flow makes sense for your app.\n\n### Building a Live Tx History\n\nOne common pattern — use both hooks together to maintain a live list. `onSwapSubmitted` adds a pending entry immediately, `onSwapComplete` updates it in-place once settled:\n\n```tsx\nconst [history, setHistory] = useState([]);\n\nconst addOrUpdate = (quoteId, patch) =>\n setHistory(prev => {\n const exists = prev.find(e => e.quoteId === quoteId);\n if (exists) return prev.map(e => e.quoteId === quoteId ? { ...e, ...patch } : e);\n return [...prev, { quoteId, status: 'pending', orderHash: null, ...patch }];\n });\n\n {\n addOrUpdate(quoteId, { status: 'pending' });\n }}\n onSwapComplete={({ quoteId, aoriOrderHash, explorerUrl, details }) => {\n const getEventTime = (type) =>\n details.events.find(e => e.event === type)?.timestamp ?? null;\n\n addOrUpdate(quoteId, {\n status: getEventTime('failed') ? 'failed' : 'completed',\n orderHash: aoriOrderHash,\n explorerUrl,\n inputAmount: details.inputAmount,\n inputChain: details.inputChain,\n outputAmount: details.outputAmount,\n outputChain: details.outputChain,\n srcTx: details.srcTx,\n dstTx: details.dstTx,\n createdAt: getEventTime('created'),\n receivedAt: getEventTime('received'),\n completedAt: getEventTime('completed'),\n failedAt: getEventTime('failed'),\n });\n }}\n/>\n\n// Render history however you like\n{history.map(tx => )}\n```\n\nThis gives you a real-time list that:\n- Shows \"pending\" the instant the user submits\n- Updates to \"completed\" or \"failed\" once on-chain settlement confirms\n- Has all the data needed to render amounts, chains, tx links, and a status timeline\n\n### Fetching Order History Outside the Hook\n\nThe `onSwapComplete` hook only captures swaps from the current session. To load a wallet's full order history — on mount, for a tx history page, etc. — use the Aori API directly with the connected wallet address.\n\n**Query all orders for a wallet** ([`/data/query`](https://docs.aori.io/reference/query)):\n\n```ts\nconst res = await fetch(\n `https://api.aori.io/data/query?offerer=[connected_wallet_address]&page=0&limit=100&sortBy=createdAt_desc`\n);\nconst { orders, pagination } = await res.json();\n// orders is an array of summarised order objects with srcTx, dstTx, amounts, chains, status\n```\n\n**Get full details for a specific order** ([`/data/details`](https://docs.aori.io/reference/details)):\n\n```ts\nconst res = await fetch(`https://api.aori.io/data/details/${orderHash}`);\nconst details = await res.json();\n// Full event history, tx hashes, block numbers, timestamps\n```\n\nThe recommended pattern for a tx history feature:\n\n- **On swap completion** — write to your own state/DB via `onSwapComplete`\n- **On page load** — fetch historical orders from `/data/query?offerer=${address}` to backfill swaps from past sessions\n- **On detail view** — fetch `/data/details/${orderHash}` for the full event timeline of a specific order\n\n## Configuration\n\nSee [`AoriSwapWidgetConfig`](./src/config/types.ts) for the full type. Only non-default values need to be specified.\n\n| Section | Type | Description |\n| --- | --- | --- |\n| `theme` | `{ mode, light?, dark? }` | Active color mode and optional light/dark theme overrides. Each theme controls colors, border radius, fonts, and shadows. |\n| `tokens` | `{ defaultBase?, defaultQuote?, lockBase?, lockQuote?, enabledChains?, disableInverting?, supportedInputTokens?, supportedOutputTokens?, unsupportedInputTokens?, unsupportedOutputTokens? }` | Default token pair, enabled chains, lock/invert settings, per-side token whitelists, and per-side token blocklists. All fields are optional — when omitted, all supported tokens and chains are available. `unsupportedInputTokens`/`unsupportedOutputTokens` hide specific tokens from the asset selection menu (applied after the whitelist; flips with the whitelist on invert). |\n| `appearance` | `{ widgetType?, tokenDisplay?, assetMenuVariant?, swapButtonVariant?, ... }` | Layout variant (`default`, `compact`, `horizontal`, `split`), token display style, asset menu variant, quote loader, and other UI options. |\n| `settings` | `{ defaultSlippage? }` | Default slippage tolerance. |\n| `integrator` | `{ id?, feeRecipient?, feeAmount? }` | Integrator ID, fee recipient address, and fee amount for revenue attribution. |\n| `vtApiBaseUrl` | `string` | Base URL for the Aori transfer API. Use a relative path (e.g. `'/api/vt'`) to proxy through your server and keep the API key off the client. |\n| `rpcOverrides` | `Record` | Override RPCs for the widget's internal viem clients. Accepts direct URLs or relative paths to your own proxy routes. |\n| `walletScreening` | `{ enabled?, useChainalysisOracle?, screeningUrl?, blacklist? }` | Wallet screening / sanctions compliance. See [Wallet Screening](#wallet-screening). |\n\n### Wallet Screening\n\nThe widget includes built-in wallet screening to check connecting addresses against sanctions lists. Screening runs automatically when a wallet connects. If the address is flagged, the widget disables all inputs, stops quoting, and replaces the swap button with a blocked banner.\n\nThere are two layers:\n\n| Layer | What it does | Config | Default |\n| --- | --- | --- | --- |\n| **Layer 1** — Chainalysis Oracle | Calls the [Chainalysis Sanctions Oracle](https://go.chainalysis.com/chainalysis-oracle-docs.html) smart contract on Ethereum mainnet. Checks the address against the OFAC SDN list. Free, no API key, no backend required. | `useChainalysisOracle` | `true` |\n| **Layer 2** — Custom screening endpoint | Calls an integrator-provided server route with `GET ?address=0x...`, expects `{ allowed: boolean }`. Use this to add TRM Labs, Chainalysis Screening API, or your own compliance backend. | `screeningUrl` | `undefined` (off) |\n\nBoth layers run in sequence when configured. If either flags the address, the widget locks down.\n\n#### Config Reference\n\n| Field | Type | Default | Description |\n| --- | --- | --- | --- |\n| `enabled` | `boolean` | `true` | Master toggle for all screening. Set `false` to disable everything. |\n| `blacklist` | `string[] \\| (address: string) => boolean \\| Promise` | `undefined` | Blacklist. Static array of addresses or async function to grab addresses from external/internal datasource. Checked before Layer 1/2 — if matched, skips all other checks. |\n| `useChainalysisOracle` | `boolean` | `true` | Layer 1. Calls the on-chain Chainalysis oracle. |\n| `screeningUrl` | `string` | `undefined` | Layer 2. URL to your server-side screening endpoint. |\n\n#### Blacklist\n\nThe `blacklist` field lets you block specific addresses without relying on Layer 1/2. It runs first — if the address is blacklisted, Layer 1 and Layer 2 are never called.\n\n**Static list** — hardcode addresses directly in the config:\n\n```ts\nwalletScreening: {\n blacklist: [\n '0x26da3963613301798251427fB5b93d6fC7cB75D8',\n '0x607aE55107457f6645149cd66ED5D220fBEB2F96',\n ],\n},\n```\n\n**Async function** — check against your own database or any external data source:\n\nThe function receives the wallet address and must return `true` (blocked) or `false` (allowed). How you determine that is entirely up to you — query a database, call an API, read a file, whatever. The widget only cares about the boolean you return.\n\n```ts\nwalletScreening: {\n blacklist: async (address) => {\n // Call your own backend route — the response shape is yours to define\n const res = await fetch(`/api/blacklist?address=${address}`);\n const data = await res.json();\n\n // Map whatever field your API returns to a boolean:\n // data.blocked, data.flagged, data.is_sanctioned, data.status === 'denied', etc.\n return Boolean(data.blocked);\n },\n},\n```\n\nThe widget doesn't know or care what backs your route. Here are three real-world patterns for the server side — each returns a JSON response with whatever field name you choose, and the config function maps it to a boolean:\n\n**PostgreSQL**\n\n```ts\n// pages/api/blacklist.ts (or any backend route)\nimport { pool } from '@/lib/db';\n\nexport default async function handler(req, res) {\n const { address } = req.query;\n const { rows } = await pool.query(\n 'SELECT is_blocked FROM accounts WHERE LOWER(address) = LOWER($1)',\n [address],\n );\n // Your table might use \"is_blocked\", \"flagged\", \"sanctioned\", etc.\n return res.json({ blocked: rows[0]?.is_blocked ?? false });\n}\n```\n\n**REST / internal compliance API**\n\n```ts\nexport default async function handler(req, res) {\n const { address } = req.query;\n const upstream = await fetch(\n `https://internal-api.example.com/compliance/check?address=${address}`,\n { headers: { Authorization: `Bearer ${process.env.COMPLIANCE_KEY}` } },\n );\n const data = await upstream.json();\n // The upstream API might return { flagged: true } or { status: \"denied\" }\n // — just map it to your response shape\n return res.json({ blocked: data.flagged });\n}\n```\n\n**JSON file (lightweight / testing)**\n\n```ts\nimport fs from 'fs';\nimport path from 'path';\n\nexport default function handler(req, res) {\n const { address } = req.query;\n const db = JSON.parse(\n fs.readFileSync(path.join(process.cwd(), 'data', 'blacklist.json'), 'utf-8'),\n );\n const entry = db.find((e) => e.address.toLowerCase() === address.toLowerCase());\n return res.json({ blocked: entry?.blocked ?? false });\n}\n```\n\nThe key point: your server route normalizes whatever your datasource returns into a consistent response, and your config function reads that response and returns a boolean. The field names, table schemas, and API shapes are all yours.\n\n**Combined** — mix static addresses with a dynamic source in one function:\n\n```ts\nconst hardcoded = ['0x26da...', '0x607a...'];\n\nwalletScreening: {\n blacklist: async (address) => {\n if (hardcoded.some((a) => a.toLowerCase() === address.toLowerCase())) return true;\n const res = await fetch(`/api/blacklist?address=${address}`);\n const data = await res.json();\n return data.blocked;\n },\n},\n```\n\n#### Screening Examples\n\n**Most integrators — Layer 1 runs automatically, nothing to set:**\n\n```ts\nexport const aoriConfig: AoriSwapWidgetConfig = {\n vtApiBaseUrl: '/api/vt',\n rpcOverrides: { 1: '/api/rpc/1', /* ... */ },\n theme: { mode: 'dark' },\n // walletScreening is not set — Layer 1 (Chainalysis oracle) is on by default.\n // No config needed. The oracle check runs automatically when a wallet connects.\n};\n```\n\n**Explicitly enabling Layer 1 (same behavior as above, just explicit):**\n\n```ts\nexport const aoriConfig: AoriSwapWidgetConfig = {\n vtApiBaseUrl: '/api/vt',\n rpcOverrides: { 1: '/api/rpc/1', /* ... */ },\n theme: { mode: 'dark' },\n walletScreening: {\n enabled: true,\n useChainalysisOracle: true,\n },\n};\n```\n\n**Layer 1 + Layer 2 (oracle + your own screening server):**\n\n```ts\nexport const aoriConfig: AoriSwapWidgetConfig = {\n vtApiBaseUrl: '/api/vt',\n rpcOverrides: { 1: '/api/rpc/1', /* ... */ },\n theme: { mode: 'dark' },\n walletScreening: {\n // Layer 1 still runs (default true)\n screeningUrl: '/api/screen-wallet', // Layer 2 — your server route\n },\n};\n```\n\n**Layer 2 only (disable the oracle, use only your own screening):**\n\n```ts\nexport const aoriConfig: AoriSwapWidgetConfig = {\n vtApiBaseUrl: '/api/vt',\n rpcOverrides: { 1: '/api/rpc/1', /* ... */ },\n theme: { mode: 'dark' },\n walletScreening: {\n useChainalysisOracle: false, // Layer 1 off\n screeningUrl: '/api/screen-wallet', // Layer 2 only\n },\n};\n```\n\n**Disable all screening:**\n\n```ts\nexport const aoriConfig: AoriSwapWidgetConfig = {\n vtApiBaseUrl: '/api/vt',\n rpcOverrides: { 1: '/api/rpc/1', /* ... */ },\n theme: { mode: 'dark' },\n walletScreening: {\n enabled: false, // No screening at all\n },\n};\n```\n\n#### Layer 2 Server Route\n\nWhen `screeningUrl` is set, the widget sends `GET ?address=0x...` when a wallet connects. Your server must return JSON:\n\n```json\n{ \"allowed\": true }\n```\n\nor:\n\n```json\n{ \"allowed\": false }\n```\n\nYour server route handles the actual compliance logic — TRM Labs, Chainalysis Screening API, a database lookup, a static blocklist, whatever. The widget doesn't know or care what's behind the URL. This follows the same pattern as `vtApiBaseUrl` and `rpcOverrides` — set a relative path in the config, build a server route that handles it.\n\n**Example Next.js API route using the free Chainalysis Sanctions Screening API** (`pages/api/screen-wallet.ts`):\n\n```ts\nimport type { NextApiRequest, NextApiResponse } from 'next';\n\nexport default async function handler(req: NextApiRequest, res: NextApiResponse) {\n if (req.method !== 'GET') {\n return res.status(405).json({ error: 'Method not allowed' });\n }\n\n const address = req.query.address as string | undefined;\n if (!address) {\n return res.status(400).json({ error: 'Missing address query param' });\n }\n\n const apiKey = process.env.CHAINALYSIS_API_KEY;\n if (!apiKey) {\n console.error('CHAINALYSIS_API_KEY not set');\n return res.status(200).json({ allowed: true }); // fail open\n }\n\n try {\n const response = await fetch(\n `https://public.chainalysis.com/api/v1/address/${address}`,\n { headers: { 'X-API-Key': apiKey, Accept: 'application/json' } },\n );\n\n if (!response.ok) {\n console.error(`Chainalysis API error: ${response.status}`);\n return res.status(200).json({ allowed: true }); // fail open\n }\n\n const data: { identifications: unknown[] } = await response.json();\n return res.status(200).json({ allowed: data.identifications.length === 0 });\n } catch (error) {\n console.error('Chainalysis API request failed:', error);\n return res.status(200).json({ allowed: true }); // fail open\n }\n}\n```\n\nYou can replace the Chainalysis call with any provider/internal service you use fro wallet screening (TRM Labs, Elliptic, a static blocklist, etc.) — the widget only cares that the route returns `{ allowed: boolean }`.\n\n#### How it works\n\n1. User connects wallet (wagmi `useAccount`).\n2. **Blacklist** (if `blacklist` is set): Checked first. If the address matches the static list or the async function returns `true`, the wallet is blocked immediately — Layer 1 and Layer 2 are skipped.\n3. **Layer 1** (if `useChainalysisOracle` is not `false`): Widget calls `isSanctioned(address)` on the Chainalysis oracle contract. The oracle covers all EVM addresses regardless of which chain the user is swapping on.\n4. **Layer 2** (if `screeningUrl` is set): Widget calls `GET ?address=0x...` and reads the `allowed` field from the JSON response.\n5. If any check flags the address: all inputs are disabled, quoting stops, and the swap button is replaced with a blocked banner. The widget is fully inert.\n6. If a clean wallet connects (or the user switches accounts to a clean wallet), the widget returns to normal.\n\n#### `onBlockedWallet` Callback\n\nThe `onBlockedWallet` prop fires once after screening completes for a connected address. Use it for compliance logging, custom UI, audit trails, or to force-disconnect blocked wallets.\n\n```tsx\nimport { SwapWidget, type BlockedWalletEvent } from '@aori/swap-widget';\n\n {\n if (!allowed) {\n // source is 'blacklist', 'chainalysis-oracle' (Layer 1), or 'screening-url' (Layer 2)\n console.warn(`Blocked wallet: ${address} (flagged by ${source})`);\n analytics.track('wallet_blocked', { address, source });\n }\n }}\n/>\n```\n\nResults are cached in-memory for 1 hour per address, so tab-switching, remounting ``, or rendering it multiple times won't re-trigger network calls.\n\n#### `useWalletScreening` Hook\n\nRead screening state anywhere inside the widget tree:\n\n```tsx\nimport { useWalletScreening } from '@aori/swap-widget';\n\nfunction Banner() {\n const { status, isBlocked, address, source } = useWalletScreening();\n if (status === 'checking') return
Verifying wallet…
;\n if (isBlocked) return
{address} blocked by {source}.
;\n return null;\n}\n```\n\nReturns `{ status, isBlocked, address, source }` — `source` is `'blacklist' | 'chainalysis-oracle' | 'screening-url' | null`.\n\n#### Hoisting ``\n\nIf you need `useWalletScreening` outside the widget tree (e.g. in a header or Tab or sibling component), wrap your app with the provider directly. When hoisted, the `walletScreening` config and `onBlockedWallet` props on `` are ignored — the outer provider owns both.\n\n```tsx\nimport { WalletScreeningProvider, SwapWidget } from '@aori/swap-widget';\n\n\n \n \n \n \n \n\n```\n\n#### Headless `screenWallet`\n\nExported for server-side use (API routes, middleware). Doesn't share the in-widget cache — add your own if needed.\n\n```ts\nimport { screenWallet } from '@aori/swap-widget';\n\nconst { allowed, source } = await screenWallet(address, { useChainalysisOracle: true });\n```\n\n### Invertible Token Lists\n\nWhen `disableInverting` is `false` (or omitted), users can flip the swap direction using the invert button. When they do, `supportedInputTokens` and `supportedOutputTokens` swap sides — meaning token list A becomes the output whitelist and token list B becomes the input whitelist.\n\nThis enables **bidirectional bridge** configurations with a single config. For example, a USDM stablecoin bridge:\n\n```ts\ntokens: {\n supportedInputTokens: [\n { chainId: 1, address: '0x...' }, // USDC Ethereum\n { chainId: 8453, address: '0x...' }, // USDC Base\n { chainId: 42161, address: '0x...' }, // USDC Arbitrum\n // ... other stablecoins\n ],\n supportedOutputTokens: [\n { chainId: 4326, address: '0x...' }, // USDM MegaETH\n ],\n supportedInputChains: [1, 8453, 42161],\n supportedOutputChains: [4326],\n disableInverting: false,\n lockBase: false,\n lockQuote: false,\n}\n```\n\nIn the default direction, the user picks a stablecoin as input and receives USDM. After inverting, the lists flip — USDM becomes the only input option and the stablecoins become the output options.\n\n**Dynamic locking:** When a side's effective token list contains exactly one token, that side's token selection is automatically disabled and the dropdown icon is hidden. No need to set `lockBase` or `lockQuote` — locking is inferred from the list length and updates dynamically on invert.\n\nSet `disableInverting: true` to prevent flipping and keep the lists fixed to their configured sides.\n\n### Token Blocklists\n\nUse `unsupportedInputTokens` and `unsupportedOutputTokens` to hide specific tokens from the asset selection menu without enumerating every supported token. Useful when you want the default registry behavior (all supported tokens listed) but need to exclude one or two for legal/compliance/business reasons.\n\n```ts\ntokens: {\n unsupportedInputTokens: [\n { chainId: 4326, address: '0x...' }, // hide MEGA from the input/base side\n ],\n unsupportedOutputTokens: [\n { chainId: 4326, address: '0x...' }, // hide MEGA from the output/quote side\n ],\n}\n```\n\n**Order of operations:** registry → `supportedInputTokens` / `supportedOutputTokens` whitelist → `unsupportedInputTokens` / `unsupportedOutputTokens` blocklist → asset menu. The blocklist applies on top of the whitelist (or on top of the full registry when no whitelist is set), so a blocked token is hidden whether or not you also use the whitelist.\n\n**Invert behavior:** When `disableInverting: false` and the user flips the swap, `unsupportedInputTokens` ↔ `unsupportedOutputTokens` swap together — same as `supportedInputTokens` ↔ `supportedOutputTokens`. A token blocked from the input side stays blocked when that side becomes the output after inversion only if you list it in both `unsupportedInputTokens` and `unsupportedOutputTokens`.\n\n## Display Patterns\n\nThe widget is a standard React component — place it anywhere in your layout.\n\n### Inline (default)\n\n```tsx\n\n```\n\n### Modal / Dialog\n\n```tsx\nconst [open, setOpen] = useState(false);\n\nreturn (\n <>\n \n {open && (\n setOpen(false)}\n >\n
e.stopPropagation()}>\n \n
\n \n )}\n \n);\n```\n\n### Drawer / Slide-in\n\n```tsx\nconst [open, setOpen] = useState(false);\n\nreturn (\n <>\n \n \n \n \n \n {open && (\n setOpen(false)}\n />\n )}\n \n);\n```\n\nThese are minimal examples. In production, use your app's existing modal/drawer components (Radix, shadcn, Headless UI, etc.) for accessibility and consistent behavior.\n\n## Resources\n\n- [Full Documentation](https://docs.aori.io)\n- [Widget API Reference](https://docs.aori.io/swap-widget)\n- [GitHub](https://github.com/aori-io)\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}