Creating a session

Every Swapped Connect integration starts with a sessionId created on your backend — never compute the signature below in a browser, since it requires your secret key.

This is the same request used to build the hosted iframe URL. If you already have that working, generating a session for the SDK is the same signed request against a different path — sent as a POST, with no iframe to embed.

Endpoint

POST https://connect-api.swapped.com/api/sessions

Parameters are passed as a query string on the POST request (not a JSON body) — identical to the iframe URL's query string.

Param	Required	Notes
apiKey	Yes	Your publishable API key, from the "Developers" section of the Swapped dashboard
walletAddress	Yes	Destination wallet(s): CURRENCY:NETWORK:ADDRESS[:AMOUNT], comma-separated for multiple currencies. AMOUNT is an optional minimum deposit (must be > 0)
signature	Yes	HMAC-SHA256 of the query string, signed with your secret key (see below)
baseCurrencyCode	No	Fiat currency code for transactions (e.g. USD, EUR, GBP)
connection	No	Exchange platform or wallet to use (e.g. Binance, Coinbase, Kraken, Phantom)
destinationTag	No	Numeric destination tag (XRP) or text memo (TON)
baseCountry	No	ISO country code for the user's location; auto-detected if omitted
webhookUrl	No	URL-encoded HTTPS URL to receive transaction webhooks
payWalletAddress	No	Wallet for Exchange Pay products, same format as walletAddress
externalCustomerId	No	Your own customer identifier
preferredCurrencyToReceive	No	Default currency for Exchange Pay products: CURRENCY:NETWORK
name	No	URL-encoded merchant name shown in the Connect interface
logo	No	URL-encoded, publicly accessible HTTPS URL to a merchant logo (PNG/SVG)

NETWORK in walletAddress / payWalletAddress is one of: bitcoin, litecoin, ethereum, solana, polygon, bsc, ripple, base, tron, avalanche, arb, cronos, fantom, optimism.

Sign the request

Same signing scheme as the iframe URL: HMAC-SHA256 over the query string (including the leading ?), Base64-encoded, then URL-encoded when appended.

import crypto from 'crypto';

const apiKey = 'your-api-key';
const secretKey = 'your-secret-key'; // backend only
const walletAddress = 'BTC:bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:10';

const params = new URLSearchParams({ apiKey, walletAddress });
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(`?${params.toString()}`)
  .digest('base64');

params.append('signature', signature);

const response = await fetch(
  `https://connect-api.swapped.com/api/sessions?${params.toString()}`,
  { method: 'POST' },
);

const { sessionId } = await response.json();

Use the sessionId

Pass the returned sessionId straight to the SDK — no redirect, no iframe:

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

const client = createSwappedConnectClient({ sessionId });
await client.loadSession();

Continue with Getting started or the React track.

Errors

Status	Meaning
403	Unknown apiKey, invalid signature, or the partner account is disabled
422	Missing or malformed parameters (e.g. walletAddress empty)
500	Unexpected server error

Related

• Session (Core) / Session (React) — reading status once loaded
• Getting started (Core)
• Iframe initialization — the embeddable-widget equivalent of this same request