Configuration

SwapDK uses a centralized configuration system called SKConfig that manages all settings across toolboxes, plugins, and integrations. This guide covers how to configure SwapDK for your application.

Configuration Overview

SwapDK’s configuration is managed through the SKConfig store, which handles:

• RPC URLs for blockchain connections
• API keys for external services
• Environment settings
• Integration configurations
• Custom API implementations
• Midgard API URLs for THORChain/Maya
• Custom API headers for authentication

Basic Configuration

When creating a SwapDK instance, you can provide configuration options:

// @noErrorValidation
import { createSwapKit } from '@swapdk/sdk';

const swapDK = createSwapKit({
  config: {

    apiKeys: {
      walletConnectProjectId: 'your-project-id',
      blockchair: 'your-blockchair-key',
      swapKit: 'your-swapdk-key'
    },

    rpcUrls: {
      ETH: 'https://eth-mainnet.g.alchemy.com/v2/your-key',
      AVAX: 'https://api.avax.network/ext/bc/C/rpc'
    },

    midgardUrls: {
      THOR: 'https://example.com'
      MAYA: 'https://example.com'
    },

    apiHeaders: {
      midgard: {
        'Authorization': 'Bearer your-token',
        'X-Custom-Header': 'custom-value'
      }
    }
  }
});

API Keys

SwapDK API Key

The SwapDK API key unlocks enhanced features:

• Higher rate limits
• Advanced swap routes
• Priority support

Get your key at api.swapdk.com

// @noErrorValidation
apiKeys: {
  swapKit: "your-swapdk-api-key";
}

WalletConnect Project ID

Required for WalletConnect v2 integration:

// @noErrorValidation
apiKeys: {
  walletConnectProjectId: "your-project-id";
}

Get your project ID at cloud.walletconnect.com

Blockchair API Key

Enables full functionality for UTXO chains (Bitcoin, Litecoin, Dogecoin, etc.):

// @noErrorValidation
apiKeys: {
  blockchair: "your-blockchair-key";
}

Without this key, UTXO chain functionality is limited. Get your key at blockchair.com/api

RPC URLs

SwapDK provides default RPC URLs for all supported chains, but you can override them:

// @noErrorValidation
import { createSwapKit, Chain } from '@swapdk/sdk';

const swapDK = createSwapKit({
  config: {
    rpcUrls: {
      [Chain.Ethereum]: 'https://example.com'
      [Chain.Avalanche]: 'https://example.com'
      [Chain.BinanceSmartChain]: 'https://example.com'
      [Chain.Polygon]: 'https://example.com'
    }
  }
});

Midgard API Configuration

Midgard provides historical data and liquidity information for THORChain and Maya. SwapDK allows you to configure custom Midgard endpoints and authentication headers.

Custom Midgard URLs

Override the default Midgard endpoints:

// @noErrorValidation
import { createSwapKit, Chain } from '@swapdk/sdk';

const swapDK = createSwapKit({
  config: {
    midgardUrls: {
      [Chain.THORChain]: 'https://example.com'
      [Chain.Maya]: 'https://example.com'
    }
  }
});

API Headers for Authentication

Add custom headers for Midgard API authentication:

// @noErrorValidation
import { SKConfig } from "@swapdk/sdk";

SKConfig.setApiHeaders("midgard", {
  "X-Client-ID": "your-client-id",
});

const swapDK = createSwapKit({
  config: {
    apiHeaders: {
      midgard: {
        "X-Client-ID": "your-client-id",
      },
      thornode: {
        "X-Client-ID": "your-client-id",
      },
      swapkitApi: {
        "X-API-Key": "additional-api-key",
      },
    },
  },
});

Runtime Updates

Update Midgard configuration at runtime:

// @noErrorValidation
import { SKConfig, Chain } from '@swapdk/sdk';


SKConfig.setMidgardUrl(Chain.THORChain, 'https://example.com');
SKConfig.setApiHeaders('midgard', {
  'X-Client-ID': 'new-client-id'
});


const midgardUrls = SKConfig.get('midgardUrls');
const apiHeaders = SKConfig.get('apiHeaders');

API Headers Configuration

SwapDK supports custom headers for all API endpoints (Midgard, THORNode, and SwapDK API). This is useful for:

• Authentication with private API instances
• Custom client identification
• Additional API key management

Supported APIs

1. Midgard API (midgard): Historical data and liquidity information
2. THORNode API (thornode): Direct blockchain node access
3. SwapDK API (swapkitApi): Swap quotes, prices, and token data

Setting Headers

// @noErrorValidation
import { SKConfig } from "@swapdk/sdk";

SKConfig.set({
  apiHeaders: {
    midgard: {
      "X-Client-ID": "your-client-id",
    },
    thornode: {
      "X-Client-ID": "your-client-id",
    },
    swapkitApi: {
      "X-API-Key": "additional-api-key",
    },
  },
});

SKConfig.setApiHeaders("midgard", {
  "X-Client-ID": "new-client-id",
});

Common Use Cases

Private Instance Access

// @noErrorValidation

SKConfig.setMidgardUrl(Chain.THORChain, 'https://example.com');
SKConfig.setApiHeaders('midgard', {
  'X-Client-ID': 'your-client-id'
});


SKConfig.setApiHeaders('thornode', {
  'X-Client-ID': 'your-client-id'
});

Additional API Keys

// @noErrorValidation

SKConfig.setApiHeaders("swapkitApi", {
  "X-API-Key": "secondary-api-key",
});

Runtime Configuration

You can update configuration after initialization using SKConfig:

// @noErrorValidation
import { SKConfig, Chain } from '@swapdk/sdk';


SKConfig.setRpcUrl(Chain.Ethereum, 'https://example.com');
SKConfig.setApiKey('blockchair', 'new-api-key');


SKConfig.setEnv('isStagenet', true);


const currentRpcUrl = SKConfig.get('rpcUrls')[Chain.Ethereum];
const apiKeys = SKConfig.get('apiKeys');

Environment Settings

Control SwapDK’s behavior with environment flags:

// @noErrorValidation
const swapDK = createSwapKit({
  config: {
    envs: {
      isDev: true,

      isStagenet: true,
    },
  },
});

Integration Configurations

Radix Wallet

For Radix dApp integration:

// @noErrorValidation
SKConfig.setIntegrationConfig("radix", {
  dAppDefinitionAddress: "account_rdx...",
  applicationName: "My dApp",
  applicationVersion: "1.0.0",
  network: {
    networkId: 1,
    networkName: "mainnet",
  },
});

Chainflip Broker

Configure Chainflip integration:

// @noErrorValidation
SKConfig.setIntegrationConfig('chainflip', {
  useSDKBroker: true,
  brokerUrl: 'https://example.com'
});

Custom API Implementations

Provide custom API implementations for specific chains:

// @noErrorValidation
import { Chain } from "@swapdk/sdk";

const customBitcoinApi = {
  getBalance: async (address: string) => {},
  getTransactionData: async (txId: string) => {},
};

SKConfig.set({
  apis: {
    [Chain.Bitcoin]: customBitcoinApi,
  },
});

Configuration Best Practices

1. Use Environment Variables

// @noErrorValidation
const swapDK = createSwapKit({
  config: {
    apiKeys: {
      walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID,
      blockchair: process.env.BLOCKCHAIR_API_KEY,
      swapKit: process.env.SWAPDK_API_KEY,
    },
  },
});

2. Configure by Environment

// @noErrorValidation
const isDevelopment = process.env.NODE_ENV === "development";

const swapDK = createSwapKit({
  config: {
    envs: {
      isDev: isDevelopment,
      isStagenet: isDevelopment,
    },
    rpcUrls: isDevelopment
      ? {
          ETH: "https://eth-mainnet.g.alchemy.com/v2/your-key",
        }
      : {
          ETH: "https://eth-mainnet.g.alchemy.com/v2/your-key",
        },
  },
});

3. Chain-Specific Configuration

EVM Chains

const evmChains = [Chain.Ethereum, Chain.Avalanche, Chain.Polygon];
const evmRpcUrls = evmChains.reduce((acc, chain) => ({
  ...acc,
  [chain]: `https://example.com`
}), {});

SKConfig.set({ rpcUrls: evmRpcUrls });

Cosmos Chains

SKConfig.setRpcUrl(Chain.Cosmos, 'https://example.com');
SKConfig.setRpcUrl(Chain.THORChain, 'https://example.com');
SKConfig.setRpcUrl(Chain.Kujira, 'https://example.com');

UTXO Chains

if (!SKConfig.get('apiKeys').blockchair) {
  console.warn('Blockchair API key not found. UTXO chain functionality will be limited.');
}

Complete Example

Here’s a production-ready configuration example:

// @noErrorValidation
import { createSwapKit, SKConfig, Chain } from '@swapdk/sdk';


const config = {

  apiKeys: {
    walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID!,
    blockchair: process.env.BLOCKCHAIR_API_KEY,
    swapKit: process.env.SWAPDK_API_KEY
  },


  envs: {
    isDev: process.env.NODE_ENV === 'development',
    isStagenet: process.env.USE_TESTNET === 'true'
  },


  rpcUrls: {
    [Chain.Ethereum]: process.env.ETH_RPC_URL || 'https://example.com'
    [Chain.Avalanche]: process.env.AVAX_RPC_URL || 'https://example.com'
    [Chain.BinanceSmartChain]: process.env.BSC_RPC_URL || 'https://example.com'
  },



  midgardUrls: process.env.MIDGARD_URL ? {
    [Chain.THORChain]: process.env.MIDGARD_URL,
    [Chain.Maya]: process.env.MAYA_MIDGARD_URL || process.env.MIDGARD_URL
  } : undefined,


  apiHeaders: {
    midgard: process.env.CLIENT_ID ? {
      'X-Client-ID': process.env.CLIENT_ID
    } : undefined,
    thornode: process.env.CLIENT_ID ? {
      'X-Client-ID': process.env.CLIENT_ID
    } : undefined,
    swapkitApi: process.env.ADDITIONAL_API_KEY ? {
      'X-API-Key': process.env.ADDITIONAL_API_KEY
    } : undefined
  }
};


const swapDK = createSwapKit({ config });


if (userPrefersFastNode) {
  SKConfig.setRpcUrl(Chain.Ethereum, 'https://example.com');
}


if (userHasRadixWallet) {
  SKConfig.setIntegrationConfig('radix', {
    dAppDefinitionAddress: process.env.RADIX_DAPP_ADDRESS!,
    applicationName: 'My SwapDK App',
    applicationVersion: '1.0.0',
    network: {
      networkId: config.envs.isStagenet ? 2 : 1,
      networkName: config.envs.isStagenet ? 'testnet' : 'mainnet'
    }
  });
}

Troubleshooting

RPC Connection Issues

If you’re experiencing connection issues:

// @noErrorValidation

const currentRpc = SKConfig.get('rpcUrls')[Chain.Ethereum];
console.log('Current Ethereum RPC:', currentRpc);


SKConfig.setRpcUrl(Chain.Ethereum, 'https://example.com');

API Key Validation

Verify your API keys are working:

// @noErrorValidation
import { SwapKitApi } from "@swapdk/sdk";

try {
  const price = await SwapKitApi.getPrice("ETH");
  console.log("SwapDK API key is valid");
} catch (error) {
  console.error("SwapDK API key issue:", error);
}

Next Steps

Now that you understand configuration:

1. Learn about Core Concepts like AssetValue and error handling
2. Explore Toolbox Usage for chain-specific operations
3. Start Connecting Wallets to your app