Getting Started

Installing and importing the SDK

Live Demo

Try the Trails widget live. Configure, preview, and copy code.

React Starter Kit

Minimal template for Trails with Earn, Swap, Pay, and Fund modes integrated.

Starter Kits

Prerequisites

• React 18+ (18.0 or newer)
• wagmi 2.16+

To install on your own application:

1. Install the SDK

   pnpm

   pnpm i 0xtrails
   

2. Import and Use the Widget

   Add the widget to your React application. Here are examples for different modes:

   Payment Mode (Exact Output)

   Send exactly 1 USDC to a recipient on Base:

   import { TrailsWidget } from '0xtrails/widget'
   
   export const PaymentExample = () => {
     return (
       <TrailsWidget
         toAddress="0x97c4A952b46bEcaD0663f76357d3776ba11566E1" // recipient address
         toAmount="1" 
         toChainId={8453}
         toToken="USDC"
         mode="pay"
         onCheckoutComplete={(result) => {
           console.log('Payment completed:', result)
         }}
       >
         <button className="pay-button">
           Pay 1 USDC
         </button>
       </TrailsWidget>
     )
   }
   

   Swap Mode

   Enable cross-chain token swapping:

   import { TrailsWidget } from '0xtrails/widget'
   
   export const SwapExample = () => {
     return (
       <TrailsWidget
         mode="swap"
         onCheckoutComplete={(result) => {
           console.log('Swap completed:', result)
         }}
       >
         <button className="swap-button">
           Swap Tokens
         </button>
       </TrailsWidget>
     )
   }
   

   Fund Mode

   Let users choose how much to deposit:

   import { TrailsWidget } from '0xtrails/widget'
   
   export const FundExample = () => {
     return (
       <TrailsWidget
         toAddress="0x97c4A952b46bEcaD0663f76357d3776ba11566E1"
         toChainId={8453}
         toToken="USDC"
         mode="fund"
         onCheckoutComplete={(result) => {
           console.log('Funding completed:', result)
         }}
       >
         <button className="fund-button">
           Add Funds
         </button>
       </TrailsWidget>
     )
   }
   

3. Handle Events (Optional)

   You can listen to various events during the transaction flow:

   import { TrailsWidget } from '0xtrails/widget'
   
   export const AdvancedExample = () => {
     return (
       <TrailsWidget
         toAddress="0x97c4A952b46bEcaD0663f76357d3776ba11566E1"
         toAmount="1"
         toChainId={8453}
         toToken="USDC"
         mode="pay"
         onCheckoutStatusUpdate={({ sessionId, transactionStates }) => {
           console.log('Transaction states updated:', sessionId, transactionStates)
         }}
         onCheckoutError={({ sessionId, error }) => {
           console.error('Transaction error:', sessionId, error)
         }}
         onCheckoutComplete={({ sessionId }) => {
           console.log('Transaction completed:', sessionId)
         }}
         gasless={true}
         theme="dark"
       >
         <button className="advanced-button">
           Send Payment
         </button>
       </TrailsWidget>
     )
   }
   

Available Modes

The widget supports several modes for different use cases:

• pay - Exact output amount (user pays exactly what’s specified)
• fund - Deposit/top-up (user chooses amount to send)
• swap - Cross-chain token swapping
• earn - Integrated yield farming and staking - bundled with existing integrations
• receive - Request payments via QR code

Script Import

While we recommend using the React component, you can also embed via a script tag in a non-React site.

You can load the Trails widget from various CDNs:

<div id="trails"></div>
<script src="https://cdn.jsdelivr.net/npm/0xtrails@latest/dist/umd/trails.min.js"></script>
<script>
  TrailsWidget.render(document.getElementById('trails'), {
    toAddress: '0x97c4A952b46bEcaD0663f76357d3776ba11566E1',
    toAmount: '0.1',
    toChainId: 8453,
    toToken: 'USDC',
    mode: 'pay'
  })
</script>

CDN Recommendations

• unpkg: https://unpkg.com/0xtrails@latest/dist/umd/trails.min.js
• jsDelivr: https://cdn.jsdelivr.net/npm/0xtrails@latest/dist/umd/trails.min.js
• Specific Version: Replace @latest with @1.0.0 (or your desired version) for production use

For production applications, we recommend pinning to a specific version rather than using @latest to ensure consistent behavior.