Getting Started

Installing and using the Trails 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.

NextJS Starter Kit

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

Get an API key: Sign up and create an API key on the Trails Dashboard

Prerequisites

• React 18+ (React 19.1+ recommended for best compatibility)

Install

pnpm

pnpm i 0xtrails

Focused components (recommended)

The SDK exports Pay, Fund, Swap, Withdraw, and Earn as purpose-built alternatives to TrailsWidget. Pick the component that matches what you’re building.

Pay

User pays a specific amount to a specific recipient:

import { Pay } from '0xtrails/widget'

export const PaymentExample = () => {
  return (
    <Pay
      apiKey="YOUR_API_KEY"
      to={{
        recipient: "0x97c4A952b46bEcaD0663f76357d3776ba11566E1",
        currency: "USDC",
        chain: "base",
        amount: "10",
      }}
      onPaymentSuccess={({ sessionId }) => {
        console.log('Payment completed:', sessionId)
      }}
    >
      <button>Pay 10 USDC</button>
    </Pay>
  )
}

Swap

User swaps from one token to another:

import { Swap } from '0xtrails/widget'

export const SwapExample = () => {
  return (
    <Swap
      apiKey="YOUR_API_KEY"
      from={{ currency: "ETH", chain: "ethereum" }}
      to={{ currency: "USDC", chain: "base" }}
      onSwapSuccess={({ sessionId }) => {
        console.log('Swap completed:', sessionId)
      }}
    >
      <button>Swap ETH to USDC</button>
    </Swap>
  )
}

Fund

User deposits funds into a wallet or protocol:

import { Fund } from '0xtrails/widget'

export const FundExample = () => {
  return (
    <Fund
      apiKey="YOUR_API_KEY"
      to={{
        recipient: "0x97c4A952b46bEcaD0663f76357d3776ba11566E1",
        currency: "USDC",
        chain: "base",
      }}
      onFundingSuccess={({ sessionId }) => {
        console.log('Funding completed:', sessionId)
      }}
    >
      <button>Add Funds</button>
    </Fund>
  )
}

Withdraw

User withdraws or off-ramps tokens:

import { Withdraw } from '0xtrails/widget'

export const WithdrawExample = () => {
  return (
    <Withdraw
      apiKey="YOUR_API_KEY"
      from={{ currency: "USDC", chain: "base" }}
      onWithdrawSuccess={({ sessionId }) => {
        console.log('Withdrawal completed:', sessionId)
      }}
    >
      <button>Withdraw</button>
    </Withdraw>
  )
}

Earn

User deposits into DeFi protocols for yield:

import { Earn } from '0xtrails/widget'

export const EarnExample = () => {
  return (
    <Earn
      apiKey="YOUR_API_KEY"
      onEarnSuccess={({ sessionId }) => {
        console.log('Deposit completed:', sessionId)
      }}
    />
  )
}

Lifecycle events

All focused components expose consistent lifecycle callbacks. Replace Xxx with Payment, Funding, Swap, Withdraw, or Earn:

<Pay
  apiKey="YOUR_API_KEY"
  to={{ recipient: "0x...", currency: "USDC", chain: "base", amount: "10" }}
  onPaymentStart={({ sessionId }) => {
    console.log('Started:', sessionId)
  }}
  onPaymentSuccess={({ sessionId }) => {
    console.log('Completed:', sessionId)
  }}
  onPaymentError={({ sessionId, error }) => {
    console.error('Failed:', sessionId, error)
  }}
/>

Script import

For non-React sites, embed the widget via CDN:

<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'), {
    apiKey: 'YOUR_API_KEY',
    toAddress: '0x97c4A952b46bEcaD0663f76357d3776ba11566E1',
    toAmount: '0.1',
    toChainId: 8453,
    toToken: 'USDC',
    mode: 'pay'
  })
</script>

CDN options:

• unpkg: https://unpkg.com/0xtrails@latest/dist/umd/trails.min.js
• jsDelivr: https://cdn.jsdelivr.net/npm/0xtrails@latest/dist/umd/trails.min.js

Pin to a specific version (e.g. @1.5.0) in production instead of @latest.

Available modes

Component	Trade type	Use when
<Pay />	EXACT_OUTPUT	Accepting payments for a fixed amount
<Fund />	EXACT_INPUT	Depositing into a wallet, chain, or protocol
<Swap />	Both	Cross-chain token exchange
<Withdraw />	Both	Off-ramping or moving funds out
<Earn />	EXACT_INPUT	DeFi yield deposits

Detailed configuration: Pay · Fund · Swap · Withdraw · Earn

If you need hooks: wrap your app with TrailsProvider. See the Hooks documentation.