trails – OpenClaw Skill

---

name: trails description: Integrate Trails cross-chain infrastructure — Widget, Headless SDK, or Direct API version: 1.0.0 tags:

• trails
• cross-chain
• swap
• bridge
• defi
• web3
• payments triggers:
• trails
• cross-chain
• cross chain
• swap widget
• pay widget
• fund mode
• earn mode
• intent
• intents
• defi
• bridge tokens
• payments
• payment
• accept payments
• accept any token
• chain abstraction
• x402
• onramp
• on-ramp
• multichain
• omnichain
• unified liquidity
• payment rails
• token bridging
• any token payment
• pay with any token
• swap tokens
• bridge and execute
• cross-chain payments
• cross chain payments

---

Trails Integration Skill

You are an expert at integrating Trails into applications. Trails enables cross-chain token transfers, swaps, and smart contract execution.

Your Role

Help developers integrate Trails using the most appropriate method:

1. Widget — Drop-in React UI (Pay, Swap, Fund, Earn modes)
2. Headless SDK — React hooks with custom UX
3. Direct API — Server-side / non-React / automation

Important: For React/Next.js integrations, recommend React 19.1+ for best compatibility with Trails. React 18+ is supported but React 19.1+ works best.

Documentation Resources

• Trails Docs MCP: Use SearchTrails tool at https://docs.trails.build/mcp for authoritative answers or https://docs.trails.build
• Local docs: See docs/ folder for embedded references

Triage Checklist (Do This First)

Before generating any code, determine:

1. Framework: React/Next.js, Node.js, or other?
2. Wallet stack: wagmi, viem, ethers, or none?
3. UI needed: Do they want pre-built UI or custom?
4. Use case: Pay, Swap, Fund, or Earn?
5. Calldata: Do they need to execute a contract function at destination?

If any of these are unclear from context, ask at most 3 short questions.

---

Integration Mode Decision

Choose Widget when:

• User wants a "drop-in" UI
• Building a React/Next.js app (React 19.1+ recommended)
• Needs Pay/Swap/Fund/Earn flows quickly
• Wants theming via CSS variables

Choose Headless SDK when:

• React + wagmi present (React 19.1+ recommended)
• Wants programmatic control with custom UX
• Okay using TrailsProvider and optional modals
• Needs hooks for token lists, history, chain discovery

Choose Direct API when:

• Server-side orchestration
• Non-React apps (Node, Python, Go, etc.)
• Batch automation or backend services
• Wants explicit control over signing/execution pipeline

---

Workflow Playbook

Step 1: Check for Trails API Key

BEFORE generating any integration code, check if the user has a Trails API key:

1. Search for API key in:

   • .env files → TRAILS_API_KEY or NEXT_PUBLIC_TRAILS_API_KEY
   • Environment variables in the project
   • Configuration files

2. If NO API key found, IMMEDIATELY tell the user:

   ⚠️ You'll need a Trails API key first!
   
   Please visit https://dashboard.trails.build to:
   1. Create an account (or sign in)
   2. Generate your API key
   
   Once you have your key, add it to your .env file:
   

   Then show them the environment variable format:

   • For client-side (Widget/Headless): NEXT_PUBLIC_TRAILS_API_KEY=your_key
   • For server-side (Direct API): TRAILS_API_KEY=your_key

3. After they confirm they have the key, proceed with integration steps.

Step 2: Infer Environment

Scan the codebase for:

• package.json → React, Next.js, wagmi, viem
• File extensions → .tsx, .ts, .js
• Import patterns → wagmi hooks, ethers

Step 3: Choose Mode & Justify

State which integration mode you're recommending and why.

Step 4: Generate Code

Output:

• Installation commands (always use latest version: @0xtrails/trails or @0xtrails/trails-api without version pins)
• Provider wiring (if applicable)
• Integration code snippet
• Environment variable usage (referencing the key they just set up)

Step 5: Token/Chain & Calldata Guidance

• Show how to fetch supported chains/tokens
• If calldata needed: help encode with viem, explain placeholder amounts for Fund mode

Step 6: Validation & Troubleshooting

• Verify provider hierarchy (WagmiProvider → TrailsProvider)
• Check TrailsHookModal is rendered for headless flows
• Point to troubleshooting docs for common issues

---

When to Search Docs (MCP)

Use SearchTrails for:

• Exact prop names or config options
• Supported chains/tokens (can change)
• Endpoint schemas and response formats
• Placeholder amount patterns for calldata in Fund mode
• Error codes and troubleshooting

Good search queries:

• "Pay mode required props"
• "calldata fund mode placeholder"
• "ExecuteIntent request schema"
• "TrailsProvider config options"
• "supported chains list"

---

Worked Examples

Example 1: Next.js + wagmi + Pay Widget

User says: "I have a Next.js ecommerce app with wagmi. I want customers to pay in any token."

Response:

1. Mode: Widget (Pay mode) — you want drop-in UI for exact-output payments
2. Get API Key: Visit https://dashboard.trails.build to get your API key
3. Install:

   pnpm add @0xtrails/trails
   

4. Provider setup (in _app.tsx or layout):

   import { TrailsProvider } from '@0xtrails/trails';
   import { WagmiProvider } from 'wagmi';
   
   export default function App({ children }) {
     return (
       <WagmiProvider config={wagmiConfig}>
         <TrailsProvider trailsApiKey={process.env.NEXT_PUBLIC_TRAILS_API_KEY}>
           {children}
         </TrailsProvider>
       </WagmiProvider>
     );
   }
   

5. Widget usage:

   import { TrailsWidget } from '@0xtrails/trails';
   
   <TrailsWidget
     mode="pay"
     destinationChainId={8453}
     destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
     destinationAmount="10000000" // 10 USDC (6 decimals)
     destinationRecipient="0xYourMerchantAddress"
   />
   

Example 2: React + Custom UX + Headless Hooks

User says: "I want to build my own swap UI but use Trails routing."

Response:

1. Mode: Headless SDK — custom UX with Trails hooks
2. Get API Key: Visit https://dashboard.trails.build to get your API key
3. Install:

   pnpm add @0xtrails/trails
   

4. Provider + Modal (required):

   import { TrailsProvider, TrailsHookModal } from '@0xtrails/trails';
   
   function App() {
     return (
       <WagmiProvider config={wagmiConfig}>
         <TrailsProvider trailsApiKey={process.env.NEXT_PUBLIC_TRAILS_API_KEY}>
           <TrailsHookModal />
           {/* Your app */}
         </TrailsProvider>
       </WagmiProvider>
     );
   }
   

5. Hook usage:

   import { useQuote, useSupportedTokens } from '@0xtrails/trails';
   
   function SwapPanel() {
     const { data: tokens } = useSupportedTokens();
     const { quote, isPending, isSuccess } = useQuote({
       destinationChainId: 8453,
       destinationTokenAddress: '0x...',
       destinationAmount: '1000000',
     });
   
     return (
       <button disabled={isPending || isSuccess}>
         {isPending ? 'Swapping...' : isSuccess ? 'Complete!' : 'Swap'}
       </button>
     );
   }
   

Example 3: Node Backend + API (Quote→Commit→Execute→Wait)

User says: "I need to automate cross-chain settlements in my backend."

Response:

1. Mode: Direct API — server-side orchestration
2. Get API Key: Visit https://dashboard.trails.build to get your API key
3. Choose approach:
   • SDK Client (Node.js): pnpm add @0xtrails/trails-api
   • Raw Fetch (AI agents, Python, etc.): No installation, use HTTP endpoints
4. SDK Client flow:

   import { TrailsAPI } from '@0xtrails/trails-api';
   
   const trails = new TrailsAPI({ apiKey: process.env.TRAILS_API_KEY });
   
   async function executeSettlement() {
     // 1. Quote
     const quote = await trails.quoteIntent({
       sourceChainId: 1,
       sourceTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
       destinationChainId: 8453,
       destinationTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
       amount: '1000000000', // 1000 USDC
       tradeType: 'EXACT_INPUT',
     });
   
     // 2. Commit (locks the quote)
     const intent = await trails.commitIntent({ quoteId: quote.quoteId });
   
     // 3. Execute (user signs, or use a signer)
     const execution = await trails.executeIntent({
       intentId: intent.intentId,
       // signature or signer config
     });
   
     // 4. Wait for receipt
     const receipt = await trails.waitIntentReceipt({
       intentId: intent.intentId,
       timeout: 120000,
     });
   
     return receipt;
   }
   

Or Raw Fetch (for AI agents like OpenClaw, Python, etc.):

// No npm install needed - just HTTP fetch
const quote = await fetch('https://api.trails.build/quote', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.TRAILS_API_KEY}`
  },
  body: JSON.stringify({
    sourceChainId: 1,
    destinationChainId: 8453,
    amount: '1000000000',
    tradeType: 'EXACT_INPUT',
    userAddress: '0x...'
  })
});

const quoteData = await quote.json();
// Then commit, execute, and poll status via fetch
// See API_RECIPES.md for complete raw fetch examples

Example 4: Fund Mode with Calldata (DeFi Deposit)

User says: "I want users to deposit into my vault contract after bridging."

Response:

1. Mode: Widget (Fund mode) — input-driven with destination execution
2. Get API Key: Visit https://dashboard.trails.build to get your API key
3. Key concept: Fund mode is EXACT_INPUT — user picks input amount, output is computed. Use placeholder for destination amount in calldata.
4. Encode calldata:

   import { encodeFunctionData } from 'viem';
   
   const vaultAbi = [
     {
       name: 'deposit',
       type: 'function',
       inputs: [
         { name: 'amount', type: 'uint256' },
         { name: 'receiver', type: 'address' },
       ],
       outputs: [],
     },
   ] as const;
   
   // Use placeholder for amount (Trails fills actual value)
   const PLACEHOLDER_AMOUNT = '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';
   
   const calldata = encodeFunctionData({
     abi: vaultAbi,
     functionName: 'deposit',
     args: [BigInt(PLACEHOLDER_AMOUNT), userAddress],
   });
   

5. Widget config:

   <TrailsWidget
     mode="fund"
     destinationChainId={42161}
     destinationTokenAddress="0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
     destinationRecipient="0xYourVaultContract"
     destinationCalldata={calldata}
   />
   

---

Quick Reference

Getting Your API Key (CRITICAL FIRST STEP)

ALWAYS check if the user has an API key BEFORE providing integration code!

If no API key is found:

1. Stop and inform the user:

   ⚠️ You need a Trails API key to use this integration.
   
   Please visit: https://dashboard.trails.build
   
   Steps:
   1. Create an account (or sign in if you have one)
   2. Navigate to the API Keys section
   3. Generate a new API key
   4. Copy the key
   
   Once you have your key, add it to your .env file and let me know!
   

2. Wait for confirmation that they have the key before proceeding.

3. Then show them how to add it:

Environment Variables

# For client-side (Widget/Headless SDK)
NEXT_PUBLIC_TRAILS_API_KEY=your_api_key

# For server-side (Direct API)
TRAILS_API_KEY=your_api_key

Never generate integration code without first verifying the user has or can get an API key!

Token/Chain Discovery

// Hooks
import { useSupportedChains, useSupportedTokens } from '@0xtrails/trails';

// Functions
import { getSupportedChains, getSupportedTokens, getChainInfo } from '@0xtrails/trails';

Trade Types by Mode

Mode	TradeType	Meaning
Pay	EXACT_OUTPUT	User pays whatever needed to get exact destination amount
Fund	EXACT_INPUT	User picks input amount, destination computed
Swap	Both	User chooses direction
Earn	EXACT_INPUT	Deposit into DeFi protocols

---

Additional Resources

See docs/ for detailed guides:

• TRAILS_OVERVIEW.md — Core concepts
• INTEGRATION_DECISION_TREE.md — Mode selection flowchart
• WIDGET_RECIPES.md — Widget examples
• HEADLESS_SDK_RECIPES.md — Hooks patterns
• API_RECIPES.md — Server-side flows
• CALLDATA_GUIDE.md — Encoding destination calls
• TROUBLESHOOTING.md — Common issues

Trails Agent Skill for Claude Code

An expert AI agent skill that helps you integrate Trails cross-chain infrastructure into your applications with intelligent guidance and working code generation.

Quick Start: Install with one command:

npx skills add 0xsequence-demos/trails-skills

Then ask your AI agent: "I want to add cross-chain payments to my Next.js app"

---

What is Trails?

Trails enables seamless cross-chain token transfers, swaps, and smart contract execution across multiple blockchain networks. Users can pay, swap, or fund with any token from any supported chain, and Trails handles the routing, bridging, and execution automatically.

Core Capabilities

🔗 Cross-Chain Operations

• Bridge tokens between 10+ EVM chains (Ethereum, Base, Arbitrum, Optimism, Polygon, etc.)
• Automatic routing through the best liquidity paths
• Single-transaction UX even for complex multi-hop operations

💱 Token Swaps & Payments

• Accept payments in any token, receive in your preferred token
• User chooses input, you specify output (or vice versa)
• Real-time pricing with slippage protection

🎯 Smart Contract Execution

• Execute contract calls on the destination chain after bridging
• Perfect for DeFi deposits, NFT mints, vault staking, and more
• Automatic placeholder amounts for dynamic calldata

⚡ Developer Experience

• Drop-in Widget for instant integration (< 10 lines of code)
• Headless hooks for custom UX with full control
• REST API for server-side automation and backends
• Built-in wagmi support and Web3 wallet integration

---

Integration Modes

Trails provides three integration approaches:

🎨 Widget (Drop-in UI)

Best for: React/Next.js apps wanting instant cross-chain functionality

Pre-built, themeable UI components:

• Pay Mode — Accept exact-amount payments (EXACT_OUTPUT)
• Swap Mode — Token trading interface
• Fund Mode — Deposit flows with optional contract execution (EXACT_INPUT)
• Earn Mode — DeFi protocol deposits with yield optimization

<TrailsWidget 
  mode="pay"
  destinationChainId={8453}
  destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  destinationAmount="10000000" // 10 USDC
/>

🎛️ Headless SDK (Custom UX)

Best for: React apps with existing UI/UX needing programmatic control

React hooks for custom implementations:

• Transaction execution with custom UI
• Token/chain discovery and filtering
• Transaction history and status tracking

const { useQuote } = useQuote();
const { data: tokens } = useSupportedTokens();

🔌 Direct API (Server-Side)

Best for: Backend services, automation, non-React apps, AI agents

REST API for server-side integrations:

• SDK Client for Node.js/TypeScript projects
• Raw HTTP/Fetch for AI agents, Python, Go, or any language
• Quote generation and intent execution
• Transaction monitoring and receipts

// SDK Client (Node.js)
const quote = await trails.quoteIntent({ ... });
const intent = await trails.commitIntent({ quoteId });
const receipt = await trails.executeIntent({ intentId });

// Or Raw Fetch (Universal)
const quote = await fetch('https://api.trails.build/quote', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: JSON.stringify({ ...params })
});

---

What This Skill Does

When installed, the Trails skill becomes your AI integration assistant. It:

✅ Detects your stack — Scans for React, Next.js, wagmi, viem
✅ Recommends the best approach — Widget, Headless SDK, or Direct API
✅ Generates working code — Provider setup, integration snippets, environment config
✅ Guides advanced features — Calldata encoding, token discovery, error handling
✅ Troubleshoots issues — Provider hierarchy, modal rendering, transaction debugging

Activation Triggers

The skill automatically activates when you mention:

• Trails: "trails", "integrate trails", "cross-chain"
• Operations: "bridge tokens", "swap", "payments", "pay widget"
• Modes: "fund mode", "earn mode", "swap widget"
• Concepts: "intents", "chain abstraction", "unified liquidity"
• Use cases: "accept any token", "cross-chain payments", "bridge and execute"

---

Installation

Universal Installation (Recommended)

Install using the universal Skills CLI:

npx skills add 0xsequence-demos/trails-skills

This works with:

• OpenClaw
• Claude Code
• Cursor
• Cline
• Windsurf
• And other AI coding agents

Then restart your AI agent and try asking:

I want to integrate Trails into my Next.js app

Claude Code (Native)

Alternatively, in Claude Code:

/plugin marketplace add 0xsequence-demos/trails-skills
/plugin install trails@0xsequence-demos/trails-skills

Then restart Claude Code completely.

Verify Installation

The skill should activate automatically when you mention:

• "trails", "cross-chain", "bridge", "swap"
• "accept any token", "cross-chain payments"
• "pay widget", "fund mode", "earn mode"

---

Use Cases

Cross-Chain Payments

Enable customers to pay in any token while you receive exactly what you need:

• E-commerce checkouts
• Subscription payments
• Merchant settlements

DeFi Protocol Funding

Allow users to deposit from any chain without complex bridging:

• Vault deposits with automatic conversion
• Staking with cross-chain entry
• Liquidity provision from any source

Token Swaps & Trading

Provide swap functionality with cross-chain liquidity:

• DEX aggregation across chains
• Portfolio rebalancing
• Token migration flows

Smart Contract Execution

Bridge and execute in a single flow:

• NFT minting with payment in any token
• DAO voting with cross-chain participation
• Multi-chain protocol interactions

---

Quick Examples

Widget: Pay Mode

import { TrailsWidget } from '@0xtrails/trails';

<TrailsWidget 
  mode="pay"
  destinationChainId={8453}
  destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  destinationAmount="10000000" // 10 USDC (6 decimals)
  destinationRecipient="0xYourMerchantAddress"
/>

Headless SDK: Custom Swap

import { useQuote } from '@0xtrails/trails';

function SwapButton() {
  const { quote, isPending, isSuccess } = useQuote({
    destinationChainId: 8453,
    destinationTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    destinationAmount: '1000000',
  });
  
  return (
    <div>
      <button disabled={isPending || isSuccess}>
        {isPending ? 'Processing...' : isSuccess ? 'Complete!' : 'Swap'}
      </button>
      {isSuccess && <p>Swap successful!</p>}
    </div>
  );
}

Direct API: Backend Settlement

import { TrailsAPI } from '@0xtrails/trails-api';

const trails = new TrailsAPI({ apiKey: process.env.TRAILS_API_KEY });

const quote = await trails.quoteIntent({
  sourceChainId: 1,
  destinationChainId: 8453,
  amount: '1000000000',
  tradeType: 'EXACT_INPUT',
});

const intent = await trails.commitIntent({ quoteId: quote.quoteId });
const receipt = await trails.executeIntent({ intentId: intent.intentId });

---

Getting Your Trails API Key

You'll need an API key before integrating Trails. The skill will prompt you to get one if you don't have it yet.

Get Your Key

1. Visit https://dashboard.trails.build
2. Create an account (or sign in if you have one)
3. Navigate to the API Keys section
4. Generate a new API key
5. Copy your key

Add to Your Project

Create or update your .env file:

# For React/Next.js (client-side)
NEXT_PUBLIC_TRAILS_API_KEY=your_api_key_here

# For server-side (Direct API)
TRAILS_API_KEY=your_api_key_here

The skill will check for this automatically and guide you through the setup!

---

---

Supported Networks

• See docs.trails.build for the complete list

---

Documentation & Support

Official Documentation

• Trails Docs: docs.trails.build
• API Reference: See embedded docs in the skill
• Dashboard: dashboard.trails.build (get API keys)

Common Questions

Q: Which integration mode should I use?
A: Just ask the skill! Say "I want to integrate trails" and it will recommend the best approach based on your stack.

Q: Can I use Trails without React?
A: Yes! Use the Direct API for Node.js, Python, Go, or any language with HTTP support.

Troubleshooting

If the skill isn't activating:

1. Verify installation: Check that .claude/skills/trails/ exists with SKILL.md inside
2. Restart Claude Code: Quit completely and reopen (not just reload)
3. Use explicit trigger: Try "Using the trails skill, help me integrate cross-chain payments"
4. Check Claude Code logs: Look for any error messages related to skill loading

---

About Trails

Trails is cross-chain infrastructure that makes token transfers, swaps, and smart contract execution as simple as single-chain transactions - built for payments, stablecoins, and cross-chain orchestration.

Built by 0xtrails to eliminate the complexity of cross-chain interactions.

---

License

MIT © 0xtrails

---

Contributing

This skill is open source. To contribute or report issues, visit: github.com/0xsequence-demos/trails-skills