Install the SDK

The Cross-chain SDK is a React library with ready-made widgets for payments, funding, earn, and swaps, plus hooks for building your own UI. It runs in the browser and authenticates with your OMS publishable key (pk_...) from the OMS Dashboard.

Install

npm install 0xtrails

pnpm add 0xtrails

yarn add 0xtrails

The SDK requires React 18 or later, viem 2, and @tanstack/react-query 5. Widgets need no provider. Import one from 0xtrails/widget, pass your key, and set the destination.

import { Pay } from "0xtrails/widget";

export function CheckoutButton() {
  return (
    <Pay
      apiKey="pk_..."
      to={{ recipient: "0xYOUR_ADDRESS", token: "USDC", chain: "polygon", amount: "25" }}
      onPaymentSuccess={({ intentId }) => console.log("Paid", intentId)}
    />
  );
}

Widget	Use it to
`Pay`	Receive an exact amount. See accept crypto at checkout.
`Fund`	Let the customer choose how much to send. See fund accounts.
`Earn`	Deposit into a yield market. See earn.
`Swap`	Convert tokens across chains. See swap and bridge.

Widgets open as a modal by default. Set renderInline to embed one in the page. For appearance and callbacks, see configuration.

Set up the provider for hooks

Hooks such as useQuote and useEarnMarkets need TrailsProvider above them, inside a QueryClientProvider.

"use client";

import { TrailsProvider } from "0xtrails";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <TrailsProvider config={{ trailsApiKey: "pk_..." }}>{children}</TrailsProvider>
    </QueryClientProvider>
  );
}

See React hooks.

Connect your users’ wallets

Widgets include their own wallet connection. If your app already manages wallets, pass them in with the adapters prop so the widget uses the same session. For apps using wagmi, install @0xtrails/adapter-wagmi and pass wagmiAdapter. For any other EIP-1193 provider, use evmAdapter from 0xtrails/widget.

Without React

For sites without React, see the CDN example.

Overview

Guides

SDK

API reference

Install

Add a widget

Set up the provider for hooks

Connect your users’ wallets

Without React

​Install

​Add a widget

​Set up the provider for hooks

​Connect your users’ wallets

​Without React

Install

Add a widget

Set up the provider for hooks

Connect your users’ wallets

Without React