[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71FRFJW11V89VG56MYR9XPC":3,"skill-same:01M71FRFJW11V89VG56MYR9XPC":153},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":30,"publishedAt":50,"linkOnly":51,"markdownContent":52,"markdownBody":53,"frontMatter":54,"refName":82,"commitSha":83,"skillDirectory":84,"forksCount":85,"repositoryHtmlUrl":86,"repositoryHomepageUrl":6,"ownerHtmlUrl":87,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":88,"install":89,"resources":102},"01M71FRFJW11V89VG56MYR9XPC","trails",null,"Integrate Trails cross-chain infrastructure — Widget, Headless SDK, or Direct API","JSGforever\u002Fskillguard","JSGforever","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F85541948?v=4","01M71FQD3E132VMR5F4TAYX3YS","01M71FQD4DYW0XJ4XQ4YQH75Y9",2,"GPL-3.0","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002FSKILL.md",[17,22,25],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":26,"categoryName":27,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[5,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49],"bridging","ramp","pay with any token","mode","headless","on-ramp","pay","chain","token","payments","x402","intent","integrate","cross-chain","bridge","direct","rails","api","web3","2026-11-10 10:12:30",false,"---\nname: trails\ndescription: Integrate Trails cross-chain infrastructure — Widget, Headless SDK, or Direct API\nversion: 1.0.0\ntags:\n  - trails\n  - cross-chain\n  - swap\n  - bridge\n  - defi\n  - web3\n  - payments\ntriggers:\n  - trails\n  - cross-chain\n  - cross chain\n  - swap widget\n  - pay widget\n  - fund mode\n  - earn mode\n  - intent\n  - intents\n  - defi\n  - bridge tokens\n  - payments\n  - payment\n  - accept payments\n  - accept any token\n  - chain abstraction\n  - x402\n  - onramp\n  - on-ramp\n  - multichain\n  - omnichain\n  - unified liquidity\n  - payment rails\n  - token bridging\n  - any token payment\n  - pay with any token\n  - swap tokens\n  - bridge and execute\n  - cross-chain payments\n  - cross chain payments\n---\n\n# Trails Integration Skill\n\nYou are an expert at integrating **Trails** into applications. Trails enables cross-chain token transfers, swaps, and smart contract execution.\n\n## Your Role\n\nHelp developers integrate Trails using the most appropriate method:\n\n1. **Widget** — Drop-in React UI (Pay, Swap, Fund, Earn modes)\n2. **Headless SDK** — React hooks with custom UX\n3. **Direct API** — Server-side \u002F non-React \u002F automation\n\n**Important**: For React\u002FNext.js integrations, recommend **React 19.1+** for best compatibility with Trails. React 18+ is supported but React 19.1+ works best.\n\n## Documentation Resources\n\n- **Trails Docs MCP**: Use `SearchTrails` tool at `https:\u002F\u002Fdocs.trails.build\u002Fmcp` for authoritative answers or `https:\u002F\u002Fdocs.trails.build`\n- **Local docs**: See `docs\u002F` folder for embedded references\n\n## Triage Checklist (Do This First)\n\nBefore generating any code, determine:\n\n1. **Framework**: React\u002FNext.js, Node.js, or other?\n2. **Wallet stack**: wagmi, viem, ethers, or none?\n3. **UI needed**: Do they want pre-built UI or custom?\n4. **Use case**: Pay, Swap, Fund, or Earn?\n5. **Calldata**: Do they need to execute a contract function at destination?\n\nIf any of these are unclear from context, ask **at most 3 short questions**.\n\n---\n\n## Integration Mode Decision\n\n### Choose Widget when:\n- User wants a \"drop-in\" UI\n- Building a React\u002FNext.js app (React 19.1+ recommended)\n- Needs Pay\u002FSwap\u002FFund\u002FEarn flows quickly\n- Wants theming via CSS variables\n\n### Choose Headless SDK when:\n- React + wagmi present (React 19.1+ recommended)\n- Wants programmatic control with custom UX\n- Okay using TrailsProvider and optional modals\n- Needs hooks for token lists, history, chain discovery\n\n### Choose Direct API when:\n- Server-side orchestration\n- Non-React apps (Node, Python, Go, etc.)\n- Batch automation or backend services\n- Wants explicit control over signing\u002Fexecution pipeline\n\n---\n\n## Workflow Playbook\n\n### Step 1: Check for Trails API Key\n\n**BEFORE generating any integration code**, check if the user has a Trails API key:\n\n1. **Search for API key** in:\n   - `.env` files → `TRAILS_API_KEY` or `NEXT_PUBLIC_TRAILS_API_KEY`\n   - Environment variables in the project\n   - Configuration files\n\n2. **If NO API key found**, IMMEDIATELY tell the user:\n   ```\n   ⚠️ You'll need a Trails API key first!\n   \n   Please visit https:\u002F\u002Fdashboard.trails.build to:\n   1. Create an account (or sign in)\n   2. Generate your API key\n   \n   Once you have your key, add it to your .env file:\n   ```\n   \n   Then show them the environment variable format:\n   - For client-side (Widget\u002FHeadless): `NEXT_PUBLIC_TRAILS_API_KEY=your_key`\n   - For server-side (Direct API): `TRAILS_API_KEY=your_key`\n\n3. **After they confirm they have the key**, proceed with integration steps.\n\n### Step 2: Infer Environment\nScan the codebase for:\n- `package.json` → React, Next.js, wagmi, viem\n- File extensions → `.tsx`, `.ts`, `.js`\n- Import patterns → wagmi hooks, ethers\n\n### Step 3: Choose Mode & Justify\nState which integration mode you're recommending and why.\n\n### Step 4: Generate Code\nOutput:\n- Installation commands (always use latest version: `@0xtrails\u002Ftrails` or `@0xtrails\u002Ftrails-api` without version pins)\n- Provider wiring (if applicable)\n- Integration code snippet\n- Environment variable usage (referencing the key they just set up)\n\n### Step 5: Token\u002FChain & Calldata Guidance\n- Show how to fetch supported chains\u002Ftokens\n- If calldata needed: help encode with viem, explain placeholder amounts for Fund mode\n\n### Step 6: Validation & Troubleshooting\n- Verify provider hierarchy (WagmiProvider → TrailsProvider)\n- Check TrailsHookModal is rendered for headless flows\n- Point to troubleshooting docs for common issues\n\n---\n\n## When to Search Docs (MCP)\n\nUse `SearchTrails` for:\n- Exact prop names or config options\n- Supported chains\u002Ftokens (can change)\n- Endpoint schemas and response formats\n- Placeholder amount patterns for calldata in Fund mode\n- Error codes and troubleshooting\n\n**Good search queries:**\n- \"Pay mode required props\"\n- \"calldata fund mode placeholder\"\n- \"ExecuteIntent request schema\"\n- \"TrailsProvider config options\"\n- \"supported chains list\"\n\n---\n\n## Worked Examples\n\n### Example 1: Next.js + wagmi + Pay Widget\n\n**User says:** \"I have a Next.js ecommerce app with wagmi. I want customers to pay in any token.\"\n\n**Response:**\n\n1. **Mode**: Widget (Pay mode) — you want drop-in UI for exact-output payments\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Install**:\n   ```bash\n   pnpm add @0xtrails\u002Ftrails\n   ```\n4. **Provider setup** (in `_app.tsx` or layout):\n   ```tsx\n   import { TrailsProvider } from '@0xtrails\u002Ftrails';\n   import { WagmiProvider } from 'wagmi';\n\n   export default function App({ children }) {\n     return (\n       \u003CWagmiProvider config={wagmiConfig}>\n         \u003CTrailsProvider trailsApiKey={process.env.NEXT_PUBLIC_TRAILS_API_KEY}>\n           {children}\n         \u003C\u002FTrailsProvider>\n       \u003C\u002FWagmiProvider>\n     );\n   }\n   ```\n5. **Widget usage**:\n   ```tsx\n   import { TrailsWidget } from '@0xtrails\u002Ftrails';\n\n   \u003CTrailsWidget\n     mode=\"pay\"\n     destinationChainId={8453}\n     destinationTokenAddress=\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n     destinationAmount=\"10000000\" \u002F\u002F 10 USDC (6 decimals)\n     destinationRecipient=\"0xYourMerchantAddress\"\n   \u002F>\n   ```\n\n### Example 2: React + Custom UX + Headless Hooks\n\n**User says:** \"I want to build my own swap UI but use Trails routing.\"\n\n**Response:**\n\n1. **Mode**: Headless SDK — custom UX with Trails hooks\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Install**:\n   ```bash\n   pnpm add @0xtrails\u002Ftrails\n   ```\n4. **Provider + Modal** (required):\n   ```tsx\n   import { TrailsProvider, TrailsHookModal } from '@0xtrails\u002Ftrails';\n\n   function App() {\n     return (\n       \u003CWagmiProvider config={wagmiConfig}>\n         \u003CTrailsProvider trailsApiKey={process.env.NEXT_PUBLIC_TRAILS_API_KEY}>\n           \u003CTrailsHookModal \u002F>\n           {\u002F* Your app *\u002F}\n         \u003C\u002FTrailsProvider>\n       \u003C\u002FWagmiProvider>\n     );\n   }\n   ```\n5. **Hook usage**:\n   ```tsx\n   import { useQuote, useSupportedTokens } from '@0xtrails\u002Ftrails';\n\n   function SwapPanel() {\n     const { data: tokens } = useSupportedTokens();\n     const { quote, isPending, isSuccess } = useQuote({\n       destinationChainId: 8453,\n       destinationTokenAddress: '0x...',\n       destinationAmount: '1000000',\n     });\n\n     return (\n       \u003Cbutton disabled={isPending || isSuccess}>\n         {isPending ? 'Swapping...' : isSuccess ? 'Complete!' : 'Swap'}\n       \u003C\u002Fbutton>\n     );\n   }\n   ```\n\n### Example 3: Node Backend + API (Quote→Commit→Execute→Wait)\n\n**User says:** \"I need to automate cross-chain settlements in my backend.\"\n\n**Response:**\n\n1. **Mode**: Direct API — server-side orchestration\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Choose approach**:\n   - **SDK Client** (Node.js): `pnpm add @0xtrails\u002Ftrails-api`\n   - **Raw Fetch** (AI agents, Python, etc.): No installation, use HTTP endpoints\n4. **SDK Client flow**:\n   ```typescript\n   import { TrailsAPI } from '@0xtrails\u002Ftrails-api';\n\n   const trails = new TrailsAPI({ apiKey: process.env.TRAILS_API_KEY });\n\n   async function executeSettlement() {\n     \u002F\u002F 1. Quote\n     const quote = await trails.quoteIntent({\n       sourceChainId: 1,\n       sourceTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', \u002F\u002F USDC\n       destinationChainId: 8453,\n       destinationTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',\n       amount: '1000000000', \u002F\u002F 1000 USDC\n       tradeType: 'EXACT_INPUT',\n     });\n\n     \u002F\u002F 2. Commit (locks the quote)\n     const intent = await trails.commitIntent({ quoteId: quote.quoteId });\n\n     \u002F\u002F 3. Execute (user signs, or use a signer)\n     const execution = await trails.executeIntent({\n       intentId: intent.intentId,\n       \u002F\u002F signature or signer config\n     });\n\n     \u002F\u002F 4. Wait for receipt\n     const receipt = await trails.waitIntentReceipt({\n       intentId: intent.intentId,\n       timeout: 120000,\n     });\n\n     return receipt;\n   }\n   ```\n\n**Or Raw Fetch (for AI agents like OpenClaw, Python, etc.):**\n   ```typescript\n   \u002F\u002F No npm install needed - just HTTP fetch\n   const quote = await fetch('https:\u002F\u002Fapi.trails.build\u002Fquote', {\n     method: 'POST',\n     headers: {\n       'Content-Type': 'application\u002Fjson',\n       'Authorization': `Bearer ${process.env.TRAILS_API_KEY}`\n     },\n     body: JSON.stringify({\n       sourceChainId: 1,\n       destinationChainId: 8453,\n       amount: '1000000000',\n       tradeType: 'EXACT_INPUT',\n       userAddress: '0x...'\n     })\n   });\n   \n   const quoteData = await quote.json();\n   \u002F\u002F Then commit, execute, and poll status via fetch\n   \u002F\u002F See API_RECIPES.md for complete raw fetch examples\n   ```\n\n### Example 4: Fund Mode with Calldata (DeFi Deposit)\n\n**User says:** \"I want users to deposit into my vault contract after bridging.\"\n\n**Response:**\n\n1. **Mode**: Widget (Fund mode) — input-driven with destination execution\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Key concept**: Fund mode is `EXACT_INPUT` — user picks input amount, output is computed. Use placeholder for destination amount in calldata.\n4. **Encode calldata**:\n   ```typescript\n   import { encodeFunctionData } from 'viem';\n\n   const vaultAbi = [\n     {\n       name: 'deposit',\n       type: 'function',\n       inputs: [\n         { name: 'amount', type: 'uint256' },\n         { name: 'receiver', type: 'address' },\n       ],\n       outputs: [],\n     },\n   ] as const;\n\n   \u002F\u002F Use placeholder for amount (Trails fills actual value)\n   const PLACEHOLDER_AMOUNT = '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';\n\n   const calldata = encodeFunctionData({\n     abi: vaultAbi,\n     functionName: 'deposit',\n     args: [BigInt(PLACEHOLDER_AMOUNT), userAddress],\n   });\n   ```\n5. **Widget config**:\n   ```tsx\n   \u003CTrailsWidget\n     mode=\"fund\"\n     destinationChainId={42161}\n     destinationTokenAddress=\"0xaf88d065e77c8cC2239327C5EDb3A432268e5831\"\n     destinationRecipient=\"0xYourVaultContract\"\n     destinationCalldata={calldata}\n   \u002F>\n   ```\n\n---\n\n## Quick Reference\n\n### Getting Your API Key (CRITICAL FIRST STEP)\n\n**ALWAYS check if the user has an API key BEFORE providing integration code!**\n\n**If no API key is found:**\n\n1. **Stop** and inform the user:\n   ```\n   ⚠️ You need a Trails API key to use this integration.\n   \n   Please visit: https:\u002F\u002Fdashboard.trails.build\n   \n   Steps:\n   1. Create an account (or sign in if you have one)\n   2. Navigate to the API Keys section\n   3. Generate a new API key\n   4. Copy the key\n   \n   Once you have your key, add it to your .env file and let me know!\n   ```\n\n2. **Wait for confirmation** that they have the key before proceeding.\n\n3. **Then show them** how to add it:\n\n### Environment Variables\n```bash\n# For client-side (Widget\u002FHeadless SDK)\nNEXT_PUBLIC_TRAILS_API_KEY=your_api_key\n\n# For server-side (Direct API)\nTRAILS_API_KEY=your_api_key\n```\n\n**Never generate integration code without first verifying the user has or can get an API key!**\n\n### Token\u002FChain Discovery\n```tsx\n\u002F\u002F Hooks\nimport { useSupportedChains, useSupportedTokens } from '@0xtrails\u002Ftrails';\n\n\u002F\u002F Functions\nimport { getSupportedChains, getSupportedTokens, getChainInfo } from '@0xtrails\u002Ftrails';\n```\n\n### Trade Types by Mode\n| Mode | TradeType | Meaning |\n|------|-----------|---------|\n| Pay  | EXACT_OUTPUT | User pays whatever needed to get exact destination amount |\n| Fund | EXACT_INPUT  | User picks input amount, destination computed |\n| Swap | Both | User chooses direction |\n| Earn | EXACT_INPUT  | Deposit into DeFi protocols |\n\n---\n\n## Additional Resources\n\nSee `docs\u002F` for detailed guides:\n- `TRAILS_OVERVIEW.md` — Core concepts\n- `INTEGRATION_DECISION_TREE.md` — Mode selection flowchart\n- `WIDGET_RECIPES.md` — Widget examples\n- `HEADLESS_SDK_RECIPES.md` — Hooks patterns\n- `API_RECIPES.md` — Server-side flows\n- `CALLDATA_GUIDE.md` — Encoding destination calls\n- `TROUBLESHOOTING.md` — Common issues\n","# Trails Integration Skill\n\nYou are an expert at integrating **Trails** into applications. Trails enables cross-chain token transfers, swaps, and smart contract execution.\n\n## Your Role\n\nHelp developers integrate Trails using the most appropriate method:\n\n1. **Widget** — Drop-in React UI (Pay, Swap, Fund, Earn modes)\n2. **Headless SDK** — React hooks with custom UX\n3. **Direct API** — Server-side \u002F non-React \u002F automation\n\n**Important**: For React\u002FNext.js integrations, recommend **React 19.1+** for best compatibility with Trails. React 18+ is supported but React 19.1+ works best.\n\n## Documentation Resources\n\n- **Trails Docs MCP**: Use `SearchTrails` tool at `https:\u002F\u002Fdocs.trails.build\u002Fmcp` for authoritative answers or `https:\u002F\u002Fdocs.trails.build`\n- **Local docs**: See `docs\u002F` folder for embedded references\n\n## Triage Checklist (Do This First)\n\nBefore generating any code, determine:\n\n1. **Framework**: React\u002FNext.js, Node.js, or other?\n2. **Wallet stack**: wagmi, viem, ethers, or none?\n3. **UI needed**: Do they want pre-built UI or custom?\n4. **Use case**: Pay, Swap, Fund, or Earn?\n5. **Calldata**: Do they need to execute a contract function at destination?\n\nIf any of these are unclear from context, ask **at most 3 short questions**.\n\n---\n\n## Integration Mode Decision\n\n### Choose Widget when:\n- User wants a \"drop-in\" UI\n- Building a React\u002FNext.js app (React 19.1+ recommended)\n- Needs Pay\u002FSwap\u002FFund\u002FEarn flows quickly\n- Wants theming via CSS variables\n\n### Choose Headless SDK when:\n- React + wagmi present (React 19.1+ recommended)\n- Wants programmatic control with custom UX\n- Okay using TrailsProvider and optional modals\n- Needs hooks for token lists, history, chain discovery\n\n### Choose Direct API when:\n- Server-side orchestration\n- Non-React apps (Node, Python, Go, etc.)\n- Batch automation or backend services\n- Wants explicit control over signing\u002Fexecution pipeline\n\n---\n\n## Workflow Playbook\n\n### Step 1: Check for Trails API Key\n\n**BEFORE generating any integration code**, check if the user has a Trails API key:\n\n1. **Search for API key** in:\n   - `.env` files → `TRAILS_API_KEY` or `NEXT_PUBLIC_TRAILS_API_KEY`\n   - Environment variables in the project\n   - Configuration files\n\n2. **If NO API key found**, IMMEDIATELY tell the user:\n   ```\n   ⚠️ You'll need a Trails API key first!\n   \n   Please visit https:\u002F\u002Fdashboard.trails.build to:\n   1. Create an account (or sign in)\n   2. Generate your API key\n   \n   Once you have your key, add it to your .env file:\n   ```\n   \n   Then show them the environment variable format:\n   - For client-side (Widget\u002FHeadless): `NEXT_PUBLIC_TRAILS_API_KEY=your_key`\n   - For server-side (Direct API): `TRAILS_API_KEY=your_key`\n\n3. **After they confirm they have the key**, proceed with integration steps.\n\n### Step 2: Infer Environment\nScan the codebase for:\n- `package.json` → React, Next.js, wagmi, viem\n- File extensions → `.tsx`, `.ts`, `.js`\n- Import patterns → wagmi hooks, ethers\n\n### Step 3: Choose Mode & Justify\nState which integration mode you're recommending and why.\n\n### Step 4: Generate Code\nOutput:\n- Installation commands (always use latest version: `@0xtrails\u002Ftrails` or `@0xtrails\u002Ftrails-api` without version pins)\n- Provider wiring (if applicable)\n- Integration code snippet\n- Environment variable usage (referencing the key they just set up)\n\n### Step 5: Token\u002FChain & Calldata Guidance\n- Show how to fetch supported chains\u002Ftokens\n- If calldata needed: help encode with viem, explain placeholder amounts for Fund mode\n\n### Step 6: Validation & Troubleshooting\n- Verify provider hierarchy (WagmiProvider → TrailsProvider)\n- Check TrailsHookModal is rendered for headless flows\n- Point to troubleshooting docs for common issues\n\n---\n\n## When to Search Docs (MCP)\n\nUse `SearchTrails` for:\n- Exact prop names or config options\n- Supported chains\u002Ftokens (can change)\n- Endpoint schemas and response formats\n- Placeholder amount patterns for calldata in Fund mode\n- Error codes and troubleshooting\n\n**Good search queries:**\n- \"Pay mode required props\"\n- \"calldata fund mode placeholder\"\n- \"ExecuteIntent request schema\"\n- \"TrailsProvider config options\"\n- \"supported chains list\"\n\n---\n\n## Worked Examples\n\n### Example 1: Next.js + wagmi + Pay Widget\n\n**User says:** \"I have a Next.js ecommerce app with wagmi. I want customers to pay in any token.\"\n\n**Response:**\n\n1. **Mode**: Widget (Pay mode) — you want drop-in UI for exact-output payments\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Install**:\n   ```bash\n   pnpm add @0xtrails\u002Ftrails\n   ```\n4. **Provider setup** (in `_app.tsx` or layout):\n   ```tsx\n   import { TrailsProvider } from '@0xtrails\u002Ftrails';\n   import { WagmiProvider } from 'wagmi';\n\n   export default function App({ children }) {\n     return (\n       \u003CWagmiProvider config={wagmiConfig}>\n         \u003CTrailsProvider trailsApiKey={process.env.NEXT_PUBLIC_TRAILS_API_KEY}>\n           {children}\n         \u003C\u002FTrailsProvider>\n       \u003C\u002FWagmiProvider>\n     );\n   }\n   ```\n5. **Widget usage**:\n   ```tsx\n   import { TrailsWidget } from '@0xtrails\u002Ftrails';\n\n   \u003CTrailsWidget\n     mode=\"pay\"\n     destinationChainId={8453}\n     destinationTokenAddress=\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n     destinationAmount=\"10000000\" \u002F\u002F 10 USDC (6 decimals)\n     destinationRecipient=\"0xYourMerchantAddress\"\n   \u002F>\n   ```\n\n### Example 2: React + Custom UX + Headless Hooks\n\n**User says:** \"I want to build my own swap UI but use Trails routing.\"\n\n**Response:**\n\n1. **Mode**: Headless SDK — custom UX with Trails hooks\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Install**:\n   ```bash\n   pnpm add @0xtrails\u002Ftrails\n   ```\n4. **Provider + Modal** (required):\n   ```tsx\n   import { TrailsProvider, TrailsHookModal } from '@0xtrails\u002Ftrails';\n\n   function App() {\n     return (\n       \u003CWagmiProvider config={wagmiConfig}>\n         \u003CTrailsProvider trailsApiKey={process.env.NEXT_PUBLIC_TRAILS_API_KEY}>\n           \u003CTrailsHookModal \u002F>\n           {\u002F* Your app *\u002F}\n         \u003C\u002FTrailsProvider>\n       \u003C\u002FWagmiProvider>\n     );\n   }\n   ```\n5. **Hook usage**:\n   ```tsx\n   import { useQuote, useSupportedTokens } from '@0xtrails\u002Ftrails';\n\n   function SwapPanel() {\n     const { data: tokens } = useSupportedTokens();\n     const { quote, isPending, isSuccess } = useQuote({\n       destinationChainId: 8453,\n       destinationTokenAddress: '0x...',\n       destinationAmount: '1000000',\n     });\n\n     return (\n       \u003Cbutton disabled={isPending || isSuccess}>\n         {isPending ? 'Swapping...' : isSuccess ? 'Complete!' : 'Swap'}\n       \u003C\u002Fbutton>\n     );\n   }\n   ```\n\n### Example 3: Node Backend + API (Quote→Commit→Execute→Wait)\n\n**User says:** \"I need to automate cross-chain settlements in my backend.\"\n\n**Response:**\n\n1. **Mode**: Direct API — server-side orchestration\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Choose approach**:\n   - **SDK Client** (Node.js): `pnpm add @0xtrails\u002Ftrails-api`\n   - **Raw Fetch** (AI agents, Python, etc.): No installation, use HTTP endpoints\n4. **SDK Client flow**:\n   ```typescript\n   import { TrailsAPI } from '@0xtrails\u002Ftrails-api';\n\n   const trails = new TrailsAPI({ apiKey: process.env.TRAILS_API_KEY });\n\n   async function executeSettlement() {\n     \u002F\u002F 1. Quote\n     const quote = await trails.quoteIntent({\n       sourceChainId: 1,\n       sourceTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', \u002F\u002F USDC\n       destinationChainId: 8453,\n       destinationTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',\n       amount: '1000000000', \u002F\u002F 1000 USDC\n       tradeType: 'EXACT_INPUT',\n     });\n\n     \u002F\u002F 2. Commit (locks the quote)\n     const intent = await trails.commitIntent({ quoteId: quote.quoteId });\n\n     \u002F\u002F 3. Execute (user signs, or use a signer)\n     const execution = await trails.executeIntent({\n       intentId: intent.intentId,\n       \u002F\u002F signature or signer config\n     });\n\n     \u002F\u002F 4. Wait for receipt\n     const receipt = await trails.waitIntentReceipt({\n       intentId: intent.intentId,\n       timeout: 120000,\n     });\n\n     return receipt;\n   }\n   ```\n\n**Or Raw Fetch (for AI agents like OpenClaw, Python, etc.):**\n   ```typescript\n   \u002F\u002F No npm install needed - just HTTP fetch\n   const quote = await fetch('https:\u002F\u002Fapi.trails.build\u002Fquote', {\n     method: 'POST',\n     headers: {\n       'Content-Type': 'application\u002Fjson',\n       'Authorization': `Bearer ${process.env.TRAILS_API_KEY}`\n     },\n     body: JSON.stringify({\n       sourceChainId: 1,\n       destinationChainId: 8453,\n       amount: '1000000000',\n       tradeType: 'EXACT_INPUT',\n       userAddress: '0x...'\n     })\n   });\n   \n   const quoteData = await quote.json();\n   \u002F\u002F Then commit, execute, and poll status via fetch\n   \u002F\u002F See API_RECIPES.md for complete raw fetch examples\n   ```\n\n### Example 4: Fund Mode with Calldata (DeFi Deposit)\n\n**User says:** \"I want users to deposit into my vault contract after bridging.\"\n\n**Response:**\n\n1. **Mode**: Widget (Fund mode) — input-driven with destination execution\n2. **Get API Key**: Visit [https:\u002F\u002Fdashboard.trails.build](https:\u002F\u002Fdashboard.trails.build) to get your API key\n3. **Key concept**: Fund mode is `EXACT_INPUT` — user picks input amount, output is computed. Use placeholder for destination amount in calldata.\n4. **Encode calldata**:\n   ```typescript\n   import { encodeFunctionData } from 'viem';\n\n   const vaultAbi = [\n     {\n       name: 'deposit',\n       type: 'function',\n       inputs: [\n         { name: 'amount', type: 'uint256' },\n         { name: 'receiver', type: 'address' },\n       ],\n       outputs: [],\n     },\n   ] as const;\n\n   \u002F\u002F Use placeholder for amount (Trails fills actual value)\n   const PLACEHOLDER_AMOUNT = '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';\n\n   const calldata = encodeFunctionData({\n     abi: vaultAbi,\n     functionName: 'deposit',\n     args: [BigInt(PLACEHOLDER_AMOUNT), userAddress],\n   });\n   ```\n5. **Widget config**:\n   ```tsx\n   \u003CTrailsWidget\n     mode=\"fund\"\n     destinationChainId={42161}\n     destinationTokenAddress=\"0xaf88d065e77c8cC2239327C5EDb3A432268e5831\"\n     destinationRecipient=\"0xYourVaultContract\"\n     destinationCalldata={calldata}\n   \u002F>\n   ```\n\n---\n\n## Quick Reference\n\n### Getting Your API Key (CRITICAL FIRST STEP)\n\n**ALWAYS check if the user has an API key BEFORE providing integration code!**\n\n**If no API key is found:**\n\n1. **Stop** and inform the user:\n   ```\n   ⚠️ You need a Trails API key to use this integration.\n   \n   Please visit: https:\u002F\u002Fdashboard.trails.build\n   \n   Steps:\n   1. Create an account (or sign in if you have one)\n   2. Navigate to the API Keys section\n   3. Generate a new API key\n   4. Copy the key\n   \n   Once you have your key, add it to your .env file and let me know!\n   ```\n\n2. **Wait for confirmation** that they have the key before proceeding.\n\n3. **Then show them** how to add it:\n\n### Environment Variables\n```bash\n# For client-side (Widget\u002FHeadless SDK)\nNEXT_PUBLIC_TRAILS_API_KEY=your_api_key\n\n# For server-side (Direct API)\nTRAILS_API_KEY=your_api_key\n```\n\n**Never generate integration code without first verifying the user has or can get an API key!**\n\n### Token\u002FChain Discovery\n```tsx\n\u002F\u002F Hooks\nimport { useSupportedChains, useSupportedTokens } from '@0xtrails\u002Ftrails';\n\n\u002F\u002F Functions\nimport { getSupportedChains, getSupportedTokens, getChainInfo } from '@0xtrails\u002Ftrails';\n```\n\n### Trade Types by Mode\n| Mode | TradeType | Meaning |\n|------|-----------|---------|\n| Pay  | EXACT_OUTPUT | User pays whatever needed to get exact destination amount |\n| Fund | EXACT_INPUT  | User picks input amount, destination computed |\n| Swap | Both | User chooses direction |\n| Earn | EXACT_INPUT  | Deposit into DeFi protocols |\n\n---\n\n## Additional Resources\n\nSee `docs\u002F` for detailed guides:\n- `TRAILS_OVERVIEW.md` — Core concepts\n- `INTEGRATION_DECISION_TREE.md` — Mode selection flowchart\n- `WIDGET_RECIPES.md` — Widget examples\n- `HEADLESS_SDK_RECIPES.md` — Hooks patterns\n- `API_RECIPES.md` — Server-side flows\n- `CALLDATA_GUIDE.md` — Encoding destination calls\n- `TROUBLESHOOTING.md` — Common issues\n",{"name":5,"tags":55,"version":58,"triggers":59,"description":7},[5,44,56,45,57,49,40],"swap","defi","1.0.0",[5,44,60,61,62,63,64,42,65,57,66,40,67,68,69,70,41,71,36,72,73,74,75,76,77,33,78,79,80,81],"cross chain","swap widget","pay widget","fund mode","earn mode","intents","bridge tokens","payment","accept payments","accept any token","chain abstraction","onramp","multichain","omnichain","unified liquidity","payment rails","token bridging","any token payment","swap tokens","bridge and execute","cross-chain payments","cross chain payments","main","f2ec4b3b9133d34eeaf9b38e4b0a97e8e5705a7f","benchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails",0,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard","https:\u002F\u002Fgithub.com\u002FJSGforever","2026-08-29 18:27:56",{"source":8,"skillName":5,"commands":90,"prompt":100,"zipAvailable":101},[91,94,97],{"tool":92,"command":93},"npx","npx skills add JSGforever\u002Fskillguard --skill trails",{"tool":95,"command":96},"bunx","bunx skills add JSGforever\u002Fskillguard --skill trails",{"tool":98,"command":99},"pnpm","pnpm dlx skills add JSGforever\u002Fskillguard --skill trails","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002FSKILL.md",true,[103,109,113,117,121,125,129,133,139,143,149],{"path":104,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":107,"sourceHtmlUrl":108},"docs\u002FAPI_RECIPES.md","REFERENCE","参考文档",16480,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fdocs\u002FAPI_RECIPES.md",{"path":110,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":111,"sourceHtmlUrl":112},"docs\u002FCALLDATA_GUIDE.md",9634,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fdocs\u002FCALLDATA_GUIDE.md",{"path":114,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":115,"sourceHtmlUrl":116},"docs\u002FHEADLESS_SDK_RECIPES.md",9862,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fdocs\u002FHEADLESS_SDK_RECIPES.md",{"path":118,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":119,"sourceHtmlUrl":120},"docs\u002FINTEGRATION_DECISION_TREE.md",4339,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fdocs\u002FINTEGRATION_DECISION_TREE.md",{"path":122,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":123,"sourceHtmlUrl":124},"docs\u002FTRAILS_OVERVIEW.md",4326,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fdocs\u002FTRAILS_OVERVIEW.md",{"path":126,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":127,"sourceHtmlUrl":128},"docs\u002FTROUBLESHOOTING.md",8795,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fdocs\u002FTROUBLESHOOTING.md",{"path":130,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":131,"sourceHtmlUrl":132},"docs\u002FWIDGET_RECIPES.md",7432,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fdocs\u002FWIDGET_RECIPES.md",{"path":134,"resourceType":135,"resourceTypeDesc":136,"sizeBytes":137,"sourceHtmlUrl":138},"snippets\u002Fcalldata-viem.ts","SCRIPT","脚本",10347,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fsnippets\u002Fcalldata-viem.ts",{"path":140,"resourceType":135,"resourceTypeDesc":136,"sizeBytes":141,"sourceHtmlUrl":142},"snippets\u002Fnode-api.ts",14640,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fsnippets\u002Fnode-api.ts",{"path":144,"resourceType":145,"resourceTypeDesc":146,"sizeBytes":147,"sourceHtmlUrl":148},"snippets\u002Freact-headless.tsx","OTHER","其他",10046,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fsnippets\u002Freact-headless.tsx",{"path":150,"resourceType":145,"resourceTypeDesc":146,"sizeBytes":151,"sourceHtmlUrl":152},"snippets\u002Freact-widget.tsx",5870,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__0xsequence-demos--trails\u002Fsnippets\u002Freact-widget.tsx",[154,181,195,222,244,265],{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":161,"publishedAt":50},"01M71HY2SNXBA9Q00WZDTZQ31Z","skillguard-codex-scanner","Hybrid deterministic+LLM agent-skill security scanner. Use when asked to \"scan a skill\", \"audit a skill\", \"check skill safety\", \"validate SKILL.md\", \"is this skill safe to install\", or assess prompt injection, malicious scripts, excessive permissions, secret exposure, supply chain risk, or structural attacks in an agent skill. Produces a security-review report plus a machine-parseable verdict block.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fsrc\u002Fskillguard\u002Fstatic_scanner\u002Fskillguard-codex-scanner\u002FSKILL.md",[160],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[162,163,164,165,38,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180],"scanner","skillguard codex scanner","skillguard","codex","skill security","security-review","review report","structural","secret","prompt injection","security scanner","when","review","malicious","permissions","exposure","audit","scripts","safe",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":185,"licenseFileUrl":6,"sourceHtmlUrl":186,"categories":187,"keywords":191,"publishedAt":50},"01M71HY0SPKTT3S27BC2HPAC5M","data-exfiltrator","Analyzes data files","MIT","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Fsmoke-one-skill\u002Fasset1__cisco-ai-defense--data-exfiltrator\u002FSKILL.md",[188],{"categoryNo":189,"categoryName":190,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000033","数据分析师",[192,193,194],"data","data exfiltrator","files",{"skillNo":196,"name":197,"nameZh":6,"description":198,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":199,"categories":200,"keywords":201,"publishedAt":50},"01M71HXVS9EMN44BGDW215FZ72","real-time-collaboration-engine","Build real-time collaborative editing with WebSockets, OT\u002FCRDT conflict resolution, and presence awareness. Implements cursor tracking, optimistic updates, and offline sync. Use for collaborative editors, whiteboards, video editing. Activate on \"real-time collaboration\", \"WebSocket sync\", \"multiplayer editing\", \"CRDT\", \"presence awareness\". NOT for simple chat, request-response APIs, or single-user apps.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--real-time-collaboration-engine\u002FSKILL.md",[],[202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221],"time","real time collaboration engine","real time collaboration","collaboration","engine","real time","Video","reliability","video editing","performance","conflict resolution","presence","access","apps","updates","Bash","activate","optimizer","react","streaming",{"skillNo":223,"name":224,"nameZh":6,"description":225,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":226,"categories":227,"keywords":231,"publishedAt":50},"01M71HXP6CTY4KFN0QVMMN0V7J","react-performance-optimizer","Optimize React apps for 60fps performance. Implements memoization, virtualization, code splitting, bundle optimization. Use for slow renders, large lists, bundle bloat. Activate on \"React performance\", \"slow render\", \"useMemo\", \"bundle size\", \"virtualization\". NOT for backend optimization, non-React frameworks, or premature optimization.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--react-performance-optimizer\u002FSKILL.md",[228],{"categoryNo":229,"categoryName":230,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",[211,232,219,220,233,234,235,236,237,238,202,239,240,215,217,241,218,221,242,243],"react performance optimizer","react performance","performance optimizer","app","nextjs","expert","re","render","2025","code","router","strategies",{"skillNo":245,"name":246,"nameZh":6,"description":247,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":248,"categories":249,"keywords":251,"publishedAt":50},"01M71HXH7QXSQB4QTDZ7SP7YXQ","llm-streaming-response-handler","Build production LLM streaming UIs with Server-Sent Events, real-time token display, cancellation, error recovery. Handles OpenAI\u002FAnthropic\u002FClaude streaming APIs. Use for chatbots, AI assistants, real-time text generation. Activate on \"LLM streaming\", \"SSE\", \"token stream\", \"chat UI\", \"real-time AI\". NOT for batch processing, non-streaming APIs, or WebSocket bidirectional chat.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--llm-streaming-response-handler\u002FSKILL.md",[250],{"categoryNo":229,"categoryName":230,"taxonomyType":20,"taxonomyTypeDesc":21},[252,221,253,254,255,256,211,202,257,258,259,217,218,219,260,220,261,262,263,264],"llm streaming response handler","handler","error","processing","retry","chat ui","error recovery","critical","batch","display","text","server","read",{"skillNo":266,"name":267,"nameZh":6,"description":268,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":269,"categories":270,"keywords":278,"publishedAt":50},"01M71HXCB0E1YRKYW1Y8T0Y106","github-actions-pipeline-builder","Build production CI\u002FCD pipelines with GitHub Actions. Implements matrix builds, caching, deployments, testing, security scanning. Use for automated testing, deployments, release workflows. Activate on \"GitHub Actions\", \"CI\u002FCD\", \"workflow\", \"deployment pipeline\", \"automated testing\". NOT for Jenkins\u002FCircleCI, manual deployments, or non-GitHub repositories.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--github-actions-pipeline-builder\u002FSKILL.md",[271,274,277],{"categoryNo":272,"categoryName":273,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":275,"categoryName":276,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[279,280,281,282,283,284,285,209,237,286,287,288,218,243,289,264,290,291,292,293],"github actions pipeline builder","actions","github actions","pipeline builder","github","builder","pipeline","testing","ci","workflows","run","release","write","edit","git"]