Configuration

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

Configuration Overview

SwapKit’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 SwapKit instance, you can provide configuration options:

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

const swapKit = createSwapKit({
  config: {

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

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

    midgardUrls: {
      THOR: 'https:
      MAYA: 'https:
    },

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

API Keys

SwapKit API Key

The SwapKit API key unlocks enhanced features:

• Higher rate limits
• Advanced swap routes
• Priority support

Get your key at [api.swapkit.dev](https:

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

WalletConnect Project ID

Required for WalletConnect v2 integration:

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

Get your project ID at [cloud.walletconnect.com](https:

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](https:

RPC URLs

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

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

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

Midgard API Configuration

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

Custom Midgard URLs

Override the default Midgard endpoints:

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

const swapKit = createSwapKit({
  config: {
    midgardUrls: {
      [Chain.THORChain]: 'https:
      [Chain.Maya]: 'https:
    }
  }
});

API Headers for Authentication

Add custom headers for Midgard API authentication:

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

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

const swapKit = 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 '@swapkit/sdk';


SKConfig.setMidgardUrl(Chain.THORChain, 'https:


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


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

API Headers Configuration

SwapKit supports custom headers for all API endpoints (Midgard, THORNode, and SwapKit 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. SwapKit API (swapkitApi): Swap quotes, prices, and token data

Setting Headers

// @noErrorValidation
import { SKConfig } from "@swapkit/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:
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 '@swapkit/sdk';


SKConfig.setRpcUrl(Chain.Ethereum, 'https:


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 SwapKit’s behavior with environment flags:

// @noErrorValidation
const swapKit = 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:
});

Custom API Implementations

Provide custom API implementations for specific chains:

// @noErrorValidation
import { Chain } from "@swapkit/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 swapKit = createSwapKit({
  config: {
    apiKeys: {
      walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID,
      blockchair: process.env.BLOCKCHAIR_API_KEY,
      swapKit: process.env.SWAPKIT_API_KEY,
    },
  },
});

2. Configure by Environment

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

const swapKit = 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:
}), {});

SKConfig.set({ rpcUrls: evmRpcUrls });

Cosmos Chains

SKConfig.setRpcUrl(Chain.Cosmos, 'https:
SKConfig.setRpcUrl(Chain.THORChain, 'https:
SKConfig.setRpcUrl(Chain.Kujira, 'https:

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 '@swapkit/sdk';


const config = {

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


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


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



  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 swapKit = createSwapKit({ config });


if (userPrefersFastNode) {
  SKConfig.setRpcUrl(Chain.Ethereum, 'https:
}


if (userHasRadixWallet) {
  SKConfig.setIntegrationConfig('radix', {
    dAppDefinitionAddress: process.env.RADIX_DAPP_ADDRESS!,
    applicationName: 'My SwapKit 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:

API Key Validation

Verify your API keys are working:

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

try {
  const price = await SwapKitApi.getPrice("ETH");
  console.log("SwapKit API key is valid");
} catch (error) {
  console.error("SwapKit 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