Getting started (React)

Create a core client, wrap your tree with SwappedConnectProvider, then use hooks from @swapped/connect-sdk/react.

This SDK is browser only. Do not create a client or call SDK methods on the server (Node.js, SSR, RSC). createSwappedConnectClient throws BROWSER_REQUIRED if it is initialized outside the browser. In Next.js and similar frameworks, instantiate the client in a client component ('use client') or a module that only runs in the browser. Session creation stays on your backend — see Creating a session. If your site sends a Content-Security-Policy, allow the Swapped widget and API origins — see Browser requirements.

Install

npm install @swapped/connect-sdk

Required only for this track: react >= 18. The core package marks React as an optional peer, so a vanilla install does not pull it in.

Setup

import { createSwappedConnectClient } from '@swapped/connect-sdk'
import {
  SwappedConnectProvider,
  useGetPaymentMethods,
} from '@swapped/connect-sdk/react'

const client = createSwappedConnectClient({
  sessionId: 'your-session-id',
  environment: 'staging', // omit or 'production' for live
})

// Provider does not load the session — do it once at bootstrap
void client.loadSession()

function App() {
  return (
    <SwappedConnectProvider client={client}>
      <PaymentMethods />
    </SwappedConnectProvider>
  )
}

function PaymentMethods() {
  const { paymentMethods, isLoading } = useGetPaymentMethods({
    category: 'exchanges',
  })

  if (isLoading) return <p>Loading…</p>

  return (
    <ul>
      {paymentMethods.map(method => (
        <li key={method.id}>{method.name}</li>
      ))}
    </ul>
  )
}

Create the client once and pass it into the provider. Hooks only work under SwappedConnectProvider.

You need a Swapped Connect sessionId from your backend before creating the client — see Creating a session. Create that session against the same environment the client uses.

Config (environment, modules, apiBaseUrl, widgetBaseUrl), SwappedConnectProvider, useSwappedConnectClient, and client errors: Client.

Typical order of work

1. createSwappedConnectClient → loadSession → wrap with SwappedConnectProvider — Client
2. Gate UI on session view (useSessionView) — only active can pay. Read session data with useSession() / maintenance with useMaintenance()
3. List payment methods
4. Run a deposit flow — Wallets, Exchange Pay, Cash App, or Coinbase
5. Use event hooks as needed
6. restartSession() (via useSwappedConnectClient) for another payment, or destroy() when done

Entry points

Import	Purpose
@swapped/connect-sdk	Create the client
@swapped/connect-sdk/react	Provider and hooks
@swapped/connect-sdk/locales	Language
@swapped/connect-sdk/format	Display helpers

Prefer vanilla JS/TS? See the Core track.