🔗iFrame Initialization

Need help with your integration? Click here to chat with our custom GPT for instant answers.

Required Parameters

• apiKey: Your publishable API key for customer identification and session validation. Also known as the public key. Can be found in the "Developers" section of the swapped.com dashboard.

• walletAddressThe crypto wallet where the user's funds will be sent. You can include one or more wallet entries, separated by commas. Format to follow: CURRENCY:NETWORK:ADDRESS:AMOUNT

  • CURRENCY – token symbol (e.g., BTC, SOL, ETH, USDT)

  • NETWORK – on‑chain network identifier (e.g., bitcoin, ethereum, solana)

  • ADDRESS – the on‑chain address itself (e.g., ltc1q2k0xaafhgt3s8qw03wmajjmlc8gcepdy0un0ah)

  • (OPTIONAL): AMOUNT – the minimum amount (in that token) a user must send to the address. Can't be 0; decimals are supported.

If using one address, it’ll look like this: walletAddress=LTC:litecoin:ltc1q2k0xaafhgt3s8qw03wmajjmlc8gcepdy0un0ah

If you want to accept multiple currencies, for example, Bitcoin, Litecoin, and Ethereum, format the walletAddress parameter as follows: walletAddress=BTC:bitcoin:yourBitcoinAddress,LTC:litecoin:yourLitecoinAddress,ETH:ethereum:yourEthereumAddress

To enforce a minimum transaction amount on a specific address, add it as the final value: walletAddress=LTC:litecoin:yourLitecoinAddress:5

Examples:

• BTC:bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:10 – Bitcoin address with a minimum of 10 BTC

• ETH:ethereum:0x742d35Cc6634C0532925a3b844Bc454e4438f44e:5 – Ethereum address with a minimum of 5 ETH

• ETH:ethereum:0x742d35Cc6634C0532925a3b844Bc454e4438f44e – Ethereum address with no minimum amount

• signature: A cryptographic signature to verify the authenticity of the request. See the Server-Side URL Signature section below for implementation details.

Optional Parameters

• baseCurrencyCode: The FIAT currency code for transactions (e.g., USD, EUR, GBP). See Supported Fiat currencies for more options.
• connection: The exchange platform or wallet to use (e.g., Binance, Coinbase, Kraken, Phantom, etc.). See supported connections for available platforms and wallets.
• style: The Styling ID and widget customization options can be configured on the “Widget Customizations” page within the Swapped.com Dashboard.
• baseCountry: (ISO) The country code for the user's location. If not provided, it will be detected automatically. See supported countries for more options.

Server-Side URL Signature

Generate a signature to prevent the URL from being modified. This is done using the query string, including '?' and the secret key shared with you.

Example with NodeJS

// Import the crypto module.
import crypto from 'crypto';

// Define the public API key.
const apiKey = 'your-api-key-12345';

// Define the secret API key.
const secretKey = 'your_secret_key';

// Define the wallet address.
const walletAddress = 'BTC:bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:10';

// Build URL with query parameters.
const originalUrl = `https://app.swapped.com?apiKey=${apiKey}&walletAddress=${walletAddress}`;

// Create a SHA-256 HMAC signature from the URL's search string, then encode in Base64.
const signature = crypto.createHmac('sha256', secretKey).update(new URL(originalUrl).search).digest('base64');

// Append the URL-encoded signature to the original URL.
const urlWithSignature = `${originalUrl}&signature=${encodeURIComponent(signature)}`;

// Output the final URL with the signature appended.
console.log(urlWithSignature);

Example with PHP

<?php

// Define the public API key.
$apiKey = 'your-api-key-12345';

// Define the secret API key.
$secretKey = 'your_secret_key';

// Define the wallet address.
$walletAddress = 'BTC:bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:10';

// Build URL with query parameters.
$originalUrl = "https://app.swapped.com?apiKey={$apiKey}&walletAddress={$walletAddress}";

// Parse the URL into its components.
$parsedUrl = parse_url($originalUrl);

// Create a SHA-256 HMAC signature from the query string, then encode in Base64.
$signature = base64_encode(hash_hmac('sha256', '?'.$parsedUrl['query'], $secretKey, true));

// Append the URL-encoded signature to the URL.
$urlWithSignature = "{$originalUrl}&signature=" . urlencode($signature);

// Output the final URL with the signature appended.
echo $urlWithSignature;

Example iFrame URL

Note: This is a test key, so your key will be different.

https://app.swapped.com/?apiKey=your-api-key-12345&walletAddress=BTC:bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:10&signature=RyvwgGPnBBfP2VwKz1beHveU4%2BTjPIwRYNj0s6hKNVU%3D

Example iFrame

The iFrame has been optimized for height: 585px; width: 445px.

<iframe
  allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment; clipboard-read; clipboard-write"
  src="https://app.swapped.com?apiKey={your-api-key}&walletAddress=BTC:bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:10&signature={your_signature}"
  title="Widget Title"
  style="height: 585px; width: 445px; border-radius: 0.75rem; margin: auto;">
</iframe>

Supported Networks

Below is a list of supported network identifiers — the values you supply in the NETWORK segment of your walletAddress parameter:

• Bitcoin: bitcoin

• Litecoin: litecoin

• Ethereum: ethereum

• Solana: solana

• Polygon: polygon

• Binance Smart Chain: bsc

• Base: base

• Tron: tron

• Avalanche: avalanche

• Arbitrum: arb

• Cronos: cronos

• Fantom: fantom

• Optimism: optimism

Error Handling

The system will return an appropriate error message if an invalid signature or API key is provided.

Common errors include:

• Unknown partner - The API key is not recognized

• Invalid signature - The signature does not match the expected value

• Partner '[name]' is disabled - This account is currently disabled. Please have an admin or higher contact our support for more information

Ensure all required parameters are included and the signature is generated correctly to avoid these errors.