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), or Coinbase OAuth — driven by a sessionId your backend creates. No hosted iframe.

Two entry points, same underlying client:

Import	Track
@swapped/connect-sdk	Core — framework-agnostic
@swapped/connect-sdk/react	React — provider + hooks on top of a core client
@swapped/connect-sdk/format	Display/formatting helpers, both tracks

Non-obvious constraints

• 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.
• Only active sessions can pay. Gate any payment UI on the session view (getSessionView() / useSessionView()), not raw 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.
• 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), and Coinbase (OAuth) are three 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' });
await client.loadSession();

const view = client.getSessionView();
if (view.type === 'active') {
  const methods = await client.paymentMethods.get({ category: 'wallets' });
  // route into Wallets / Exchange Pay / 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' })
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, 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)
• Concepts — glossary and session lifecycle
• API reference — generated from source types