Connect SDK

Appearance

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:

ImportTrack
@swapped/connect-sdkCore - framework-agnostic. React is an optional peer and is not installed unless you use it.
@swapped/connect-sdk/reactReact - provider + hooks on top of a core client. Requires react >= 18.
@swapped/connect-sdk/formatDisplay/formatting helpers, both tracks
@swapped/connect-sdk/wallet-verificationStandalone address verification. Not checkout.
@swapped/connect-sdk/wallet-verification/reactProvider + hooks for wallet verification.

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.
  • Wallet verification is a separate product. Import createWalletVerification from @swapped/connect-sdk/wallet-verification, or WalletVerificationProvider from @swapped/connect-sdk/wallet-verification/react. It takes a public apiKey, not a sessionId. Do not reuse Connect client.wallets or client.coinbase. See Wallet verification.

Minimal working example (Core) ​

ts
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) ​

tsx
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

Wallet verification (standalone) ​

Not a Connect session. Prove the user controls customerId + address (reuse key - already verified returns verified immediately).

ts
import { createWalletVerification } from '@swapped/connect-sdk/wallet-verification'

const client = createWalletVerification({
  apiKey: 'your-public-api-key',
  environment: 'staging',
})

const prepared = await client.wallets.prepareVerify({
  network: 'evm',
  customerId: 'user-1234',
  provider: wallets[0].provider,
  address: '0xAb58…',
  onUri: ({ uri, deeplinkUrl }) => { /* WalletConnect QR */ },
  onDeeplinkUrl: ({ url }) => { /* browse QR */ },
})
const verification = await prepared.wait()
// or client.wallets.verify({ prepared, transport: 'injected', ... })

// Coinbase: startVerification() then openVerificationTab() from a click
// Same-tab: startVerification({ mode: 'redirect', redirectUrl }) then completeVerification() on the landing page
  • Signature: client.wallets.verify() one-shot, or prepareVerify() then verify({ prepared }) / verify({ verificationId }). prepareVerify needs address. Abort a prepare with prepared.cancel().
  • Coinbase: client.coinbase. New-tab default; redirect requires redirectUrl.
  • Statuses: pending (retry this step), verified (done), failed / expired (new verify). Invalid signature stays pending.
  • One verification at a time (WALLET_VERIFICATION_IN_PROGRESS). destroy() on teardown.
  • Guide: Wallet verification (Core) / React

Full references ​