> ## Documentation Index
> Fetch the complete documentation index at: https://anypay-docs-update-resources-2026-06-29.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Installing and using the Trails SDK

<div className="not-prose grid gap-x-4 gap-y-2 sm:grid-cols-2 md:grid-cols-3">
  <Card title="Live Demo" icon="bolt" href="https://demo.trails.build/widget">
    Try the Trails widget live. Configure, preview, and copy code.
  </Card>

  <Card title="React Starter Kit" icon="code" href="https://github.com/0xsequence-demos/trails-starter">
    Minimal template for Trails with Earn, Swap, Pay, and Fund modes integrated.
  </Card>

  <Card title="NextJS Starter Kit" icon="code" href="https://github.com/0xsequence-demos/trails-nextjs-starter">
    Minimal NextJS template for Trails with Earn, Swap, Pay, and Fund modes integrated.
  </Card>
</div>

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

## Prerequisites

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

## Install

<CodeGroup>
  ```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
  ```
</CodeGroup>

## 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={({ sessionId }) => {
        console.log('Payment completed:', sessionId)
      }}
    >
      <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={({ sessionId }) => {
        console.log('Swap completed:', sessionId)
      }}
    >
      <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={({ sessionId }) => {
        console.log('Funding completed:', sessionId)
      }}
    >
      <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={({ sessionId }) => {
        console.log('Withdrawal completed:', sessionId)
      }}
    >
      <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={({ sessionId }) => {
        console.log('Deposit completed:', sessionId)
      }}
    />
  )
}
```

## 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={({ sessionId }) => {
    console.log('Completed:', sessionId)
  }}
  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`.
</Note>

## 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](/sdk/modes/pay) · [Fund](/sdk/modes/fund) · [Swap](/sdk/modes/swap) · [Withdraw](/sdk/modes/withdraw) · [Earn](/sdk/modes/earn)

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