> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trails.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Installing and using the Trails SDK

> [card] [Live Demo](https://demo.trails.build/widget)
>
> Try the Trails widget live. Configure, preview, and copy code.

> [card] [React Starter Kit](https://github.com/0xsequence-demos/trails-starter)
>
> Minimal template for Trails with Earn, Swap, Pay, and Fund modes integrated.

> [card] [NextJS Starter Kit](https://github.com/0xsequence-demos/trails-nextjs-starter)
>
> Minimal NextJS template for Trails with Earn, Swap, Pay, and Fund modes integrated.

> [!NOTE]
>
> **Get an API key**: Sign up and create an API key on the [Trails Dashboard](https://dashboard.trails.build/landing)

## Prerequisites

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

## Install

```shell pnpm theme={null}
pnpm i 0xtrails
```

```shell npm theme={null}
pnpm add 0xtrails
```

```shell yarn theme={null}
yarn add 0xtrails
```

```shell bun theme={null}
bun add 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:

```tsx theme={null}
import { Pay } from '0xtrails/widget'

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

### Swap

User swaps from one token to another:

```tsx theme={null}
import { Swap } from '0xtrails/widget'

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

### Fund

User deposits funds into a wallet or protocol:

```tsx theme={null}
import { Fund } from '0xtrails/widget'

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

### Withdraw

User withdraws or off-ramps tokens:

```tsx theme={null}
import { Withdraw } from '0xtrails/widget'

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

### Earn

User deposits into DeFi protocols for yield:

```tsx theme={null}
import { Earn } from '0xtrails/widget'

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

## Lifecycle events

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

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

## Script import

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

```html theme={null}
<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`

> [!NOTE]
>
> 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](https://docs.trails.build/sdk/modes/pay.md) · [Fund](https://docs.trails.build/sdk/modes/fund.md) · [Swap](https://docs.trails.build/sdk/modes/swap.md) · [Withdraw](https://docs.trails.build/sdk/modes/withdraw.md) · [Earn](https://docs.trails.build/sdk/modes/earn.md)

If you need hooks: wrap your app with `TrailsProvider`. See the [Hooks documentation](https://docs.trails.build/sdk/hooks.md#trailsprovider).
