For AI agents

This page is a condensed reference for coding agents (Claude Code, Cursor, Codex, etc.) integrating @swapped/connect-sdk. It duplicates nothing you can't also get from the guide — it just puts the load-bearing facts in one place.

Prefer fetching content directly over browsing:

• /llms.txt — link index of every page on this site, one line each
• /llms-full.txt — the entire site concatenated into one file
• Any page as raw Markdown: append .md to its URL, e.g. /guide/core/getting-started.md
• Every rendered page also has Copy page / View as Markdown buttons under its title

What this SDK does

Framework-agnostic client for Swapped Connect: deposits via self-custodial wallets, exchange apps (Exchange Pay), Cash App, or Coinbase OAuth — driven by a sessionId your backend creates. No hosted widget UI. By default the SDK mounts a hidden {widgetBaseUrl}/gateway iframe (wallets / coinbase). Pass modules: ['exchangePay'] (and/or cashApp) to skip it.

Two entry points, same underlying client:

Import	Track
@swapped/connect-sdk	Core — framework-agnostic. React is an optional peer and is not installed unless you use it.
@swapped/connect-sdk/react	React — provider + hooks on top of a core client. Requires react >= 18.
@swapped/connect-sdk/format	Display/formatting helpers, both tracks

Non-obvious constraints

• 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 outside the browser. In Next.js, use a client component ('use client') or a client-only module.
• CSP: unless modules omits both wallets and coinbase, the SDK mounts a hidden iframe at {widgetBaseUrl}/gateway and opens a WebSocket to {apiBaseUrl}/swapped-connect. If the merchant site sends a Content-Security-Policy, allow those origins — see Browser requirements. WALLET_GATEWAY_NOT_READY usually means frame-src blocked the iframe; WEBSOCKET_CONNECTION_FAILED usually means connect-src blocked wss:.
• modules: omit to enable exchangePay, cashApp, coinbase, and wallets. A listed subset constructs only those modules (MODULE_NOT_ENABLED if you call one that was left out) and hides the other methods from paymentMethods.get() / useGetPaymentMethods().
• The sessionId must come from your backend. It's an HMAC-signed request that requires a secret key — never sign it in the browser. See Creating a session. Pair the session host with the client: environment: 'staging' (session POST https://staging-api.swapped.app/api/sessions) or production (default, POST https://connect-api.swapped.com/api/sessions). A staging session does not load against production — and getSessionView() / useSessionView() still report active when no session is loaded.
• Optional apiBaseUrl / widgetBaseUrl override that environment's defaults. apiBaseUrl is allow-listed to the official production and staging API hosts.
• Only active sessions can pay. Gate any payment UI on the session view (getSessionView() / useSessionView()), not raw SessionData.session.status. Calling a payment method while inactive throws SESSION_NOT_ACTIVE.
• Call loadSession() once, before rendering payment UI. In React, the provider does not load the session for you — do it once at bootstrap, outside the component tree. A second call uses the cache unless you pass { forceRefetch: true }. You almost never need that — sockets and payment completion already refresh the session.
• restartSession() before starting another payment after completion/expiry/failure — don't create a new client.
• Wallets (self-custodial connect), Exchange Pay (exchange-app QR/checkout), Cash App (Cash App / Lightning), and Coinbase (OAuth) are four distinct flows — see Concepts before assuming one covers the others.

Minimal working example (Core)

import { createSwappedConnectClient } from '@swapped/connect-sdk';

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

const view = client.getSessionView();
if (view.type === 'active') {
  const methods = await client.paymentMethods.get({ category: 'wallets' });
  // route into Wallets / Exchange Pay / Cash App / Coinbase based on `methods`
}

Minimal working example (React)

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
})
void client.loadSession() // outside the tree, once

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(m => <li key={m.id}>{m.name}</li>)}</ul>
}

Integration order

1. Backend: sign and create a session → Creating a session
2. createSwappedConnectClient → loadSession()
3. Gate UI on session view — Core / React
4. List payment methods — Core / React
5. Implement one deposit flow — Wallets, Exchange Pay, Cash App, or Coinbase (each has a React equivalent under /guide/react/)
6. Handle events and errors per-module
7. restartSession() for another payment, destroy() on teardown

Full references

• Getting started (Core) / Getting started (React)
• Client (Core) / Client (React) — config, modules, lifecycle
• Browser requirements — CSP, hidden gateway iframe, WebSocket
• Concepts — glossary and session lifecycle
• API reference — generated from source types