@paraspell/sdk

@paraspell/sdk

SDK for handling XCM asset transfers across Polkadot, Kusama, Paseo and Westend ecosystems.

Supporting every XCM Active Parachain [list]

SDK documentation [here]

SDK starter template project [here]

Installation

Install dependencies

ParaSpell XCM SDK is the 🥇 in the ecosystem to support both PolkadotJS and PolkadotAPI.

This version of SDK uses PolkadotAPI if you wish to use PolkadotJS version please reffer to following package.

#Polkadot API peer dependencies
pnpm | npm install || yarn add polkadot-api 

Install SDK

pnpm | npm install || yarn add @paraspell/sdk

Importing package to your project

Builder pattern:

// Polkadot API version
import { Builder } from '@paraspell/sdk'

Other patterns:

// ESM
import * as paraspell from '@paraspell/sdk'

Interaction with further asset symbol abstraction:

import { Native, Foreign, ForeignAbstract } from '@paraspell/sdk'; //Only needed when advanced asset symbol selection is used.

Implementation

[!NOTE]

• Brand new asset decimal abstraction introduced. It can be turned on in Builder config. Will be turned on by default in next major release.
• V11 > V12 Migration guide https://paraspell.github.io/docs/migration/v11-to-v12.html

Latest news:

• You can now pass signer directly into senderAddress parameter
• The local transfers now have additional builder parameter called keepAlive
• Transact is here! Find out more: https://paraspell.github.io/docs/sdk/xcmPallet.html#transact

Sending XCM

For full documentation on XCM Transfers head over to official documentation.

Transfer assets from Substrate to Substrate

const builder = Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
      .from(TSubstrateChain)
      .to(TChain /*,customParaId - optional*/ | Location object /*Only works for PolkadotXCM pallet*/) 
      .currency({id: currencyID, amount: amount} | {symbol: currencySymbol, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Native('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Foreign('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: ForeignAbstract('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {location: AssetLocationString, amount: amount /*Use "ALL" to transfer everything*/ | AssetLocationJson, amount: amount /*Use "ALL" to transfer everything*/} | {location: Override('Custom Location'), amount: amount /*Use "ALL" to transfer everything*/} | [{currencySelection /*for example symbol: symbol or id: id, or location: location*/, amount: amount /*Use "ALL" to transfer everything*/}, {currencySelection}, ..]) 
      .address(address | Location object /*If you are sending through xTokens, you need to pass the destination and address Location in one object (x2)*/)
      .senderAddress(address | PAPI_SIGNER) // - OPTIONAL but strongly recommended as it is automatically ignored when not needed - Used when origin is AssetHub with feeAsset or when sending to AssetHub to prevent asset traps by auto-swapping to DOT to have DOT ED.
      /*.ahAddress(ahAddress) - OPTIONAL - used when origin is EVM chain and XCM goes through AssetHub (Multihop transfer where we are unable to convert Key20 to ID32 address eg. origin: Moonbeam & destination: Ethereum (Multihop goes from Moonbeam > AssetHub > BridgeHub > Ethereum)
        .feeAsset({symbol: 'symbol'} || {id: 'id'} || {location: 'location'}) // Optional parameter used when multiasset is provided or when origin is AssetHub - so user can pay in fees different than DOT
        .xcmVersion(Version.V3/V4/V5)  //Optional parameter for manual override of XCM Version used in call
        .customPallet('Pallet','pallet_function') //Optional parameter for manual override of XCM Pallet and function used in call (If they are named differently on some chain but syntax stays the same). Both pallet name and function required. Pallet name must be CamelCase, function name snake_case.*/

const tx = await builder.build()
// Or if you use signers in senderAddress:
// await builder.signAndSubmit() - Signs and submits the transaction; returns TX hash for tracking

//Make sure to disconnect the API after it is no longer used (eg, after a transaction)
await builder.disconnect()

/*
EXAMPLE:
const builder = Builder()
  .from('AssetHubPolkadot')
  .to('Polkadot')
  .currency({
    symbol: 'DOT',
    amount: '1000000000'
  })
  .address(address)

const tx = await builder.build()

//Disconnect API after TX
await builder.disconnect()
*/

Local transfers

const builder = Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
      .from(TSubstrateChain)
      .to(TChain) //Has to be the same as the origin (from)
      .currency({id: currencyID, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: currencySymbol, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Native('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Foreign('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: ForeignAbstract('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {location: AssetLocationString, amount: amount /*Use "ALL" to transfer everything*/ | AssetLocationJson, amount: amount /*Use "ALL" to transfer everything*/} | {location: Override('Custom Location'), amount: amount /*Use "ALL" to transfer everything*/} | [{currencySelection /*for example symbol: symbol or id: id, or location: location*/, amount: amount /*Use "ALL" to transfer everything*/}, {currencySelection}, ..])
      .address(address)
   /* .keepAlive(bool) - Optional: Allows draining the account below the existential deposit. */

const tx = await builder.build()

//Make sure to disconnect the API after it is no longer used (eg, after a transaction)
await builder.disconnect()

/*
EXAMPLE:
const builder = Builder()
  .from('Hydration')
  .to('Hydration')
  .currency({
    symbol: 'DOT',
    amount: '1000000000'
  })
  .address(address)

const tx = await builder.build()

//Disconnect API after TX
await builder.disconnect()
*/

Transact

const builder = Builder(/*client | builder_config | ws_url | [ws_url, ws_url,..] - Optional*/)
      .from(TSubstrateChain) // 'AssetHubPolkadot' | 'Hydration' | 'Moonbeam' | 'Polkadot' |  ... https://paraspell.github.io/docs/sdk/AssetPallet.html#import-chains-as-types
      .to(TChain) // Has to be same as origin (from)
      .currency(CURRENCY_SPEC) // Refer to currency spec options below
      .senderAddress(senderAddress | PAPI SIGNER)
      .address(address)
      .transact(hex, /* originType, TWeight - Optional */)

const tx = await builder.build()
// Or if you use signers in senderAddress:
// await builder.signAndSubmit() - Signs and submits the transaction; returns TX hash for tracking

//Disconnect API after TX
await builder.disconnect()

Dry run your XCM Calls:

//Builder pattern
const result = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
        .from(TSubstrateChain)
        .to(TChain)
        .currency({id: currencyID, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: currencySymbol, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Native('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Foreign('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: ForeignAbstract('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {location: AssetLocationString, amount: amount /*Use "ALL" to transfer everything*/ | AssetLocationJson, amount: amount /*Use "ALL" to transfer everything*/} | {location: Override('Custom Location'), amount: amount /*Use "ALL" to transfer everything*/} | {[{currencySelection, isFeeAsset?: true /* for example symbol: symbol or id: id, or Location: Location*/, amount: amount /*Use "ALL" to transfer everything*/}]})
        /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in same fee asset as selected currency.*/
        .address(ADDRESS)
        .senderAddress(address | PAPI_SIGNER)
        .dryRun()

//Check Parachain for DryRun support - returns true/false
import { hasDryRunSupport } from "@paraspell/sdk";

const result = hasDryRunSupport(TChain)

Dry run preview:

//Builder pattern
const result = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
        .from(TSubstrateChain)
        .to(TChain)
        .currency({id: currencyID, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: currencySymbol, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Native('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Foreign('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: ForeignAbstract('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {location: AssetLocationString, amount: amount /*Use "ALL" to transfer everything*/ | AssetLocationJson, amount: amount /*Use "ALL" to transfer everything*/} | {location: Override('Custom Location'), amount: amount /*Use "ALL" to transfer everything*/} | {[{currencySelection, isFeeAsset?: true /* for example symbol: symbol or id: id, or Location: Location*/, amount: amount /*Use "ALL" to transfer everything*/}]})
        /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in same fee asset as selected currency.*/
        .address(ADDRESS)
        .senderAddress(address | PAPI_SIGNER)
        .dryRunPreview(/*{ mintFeeAssets: true } - false by default - Mints fee assets also, if user does not have enough to cover fees on origin.*/)

Batch calls

const builder = Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
      .from(TSubstrateChain) //Ensure, that origin chain is the same in all batched XCM Calls.
      .to(TChain2) //Any compatible Parachain
      .currency({currencySelection, amount}) //Currency to transfer - options as in scenarios above
      .address(address | Location object)
      .addToBatch()

      .from(TSubstrateChain) //Ensure, that origin chain is the same in all batched XCM Calls.
      .to(TChain3) //Any compatible Parachain
      .currency({currencySelection, amount}) //Currency to transfer - options as in scenarios above
      .address(address | Location object)
      .addToBatch()
      
const tx = await builder.buildBatch({ 
          // This settings object is optional and batch all is the default option
          mode: BatchMode.BATCH_ALL //or BatchMode.BATCH
      })

//Make sure to disconnect the API after it is no longer used (eg, after a transaction)
await builder.disconnect()

Asset claim:

//Claim XCM trapped assets from the selected chain
const builder = Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
      .claimfrom(TSubstrateChain)
      .currency({id: currencyID, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: currencySymbol, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Native('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Foreign('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: ForeignAbstract('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {location: AssetLocationString, amount: amount /*Use "ALL" to transfer everything*/ | AssetLocationJson, amount: amount /*Use "ALL" to transfer everything*/} | [{currencySelection /*for example symbol: symbol or id: id, or location: location*/, amount: amount /*Use "ALL" to transfer everything*/}, {currencySelection}, ..]
)
      .address(address | Location object)
      /*.xcmVersion(Version.V3) Optional parameter, by default chain specific version. XCM Version ENUM if a different XCM version is needed (Supported V3 & V4 & V5). Requires importing Version enum.*/

const tx = await builder.build()

//Make sure to disconnect the API after it is no longer used (eg, after a transaction)
await builder.disconnect()

Localhost test setup

const builder = await Builder({
  development: true, // Optional: Enforces overrides for all chains used
  decimalAbstraction: true // Abstracts decimals, so 1 as input amount equals 10_000_000_000 if selected asset is DOT.
  xcmFormatCheck: true // Dryruns each call under the hood with dryrun bypass to confirm message passes with fictional balance
  apiOverrides: {
    Hydration: // "wsEndpointString" | papiClient
    BridgeHubPolkadot: // "wsEndpointString" | papiClient
    //ChainName: ...
  }
})
  .from(TSubstrateChain)
  .to(TChain)
  .currency({id: currencyID, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: currencySymbol, amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Native('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: Foreign('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {symbol: ForeignAbstract('currencySymbol'), amount: amount /*Use "ALL" to transfer everything*/} | {location: AssetLocationString, amount: amount /*Use "ALL" to transfer everything*/ | AssetLocationJson, amount: amount /*Use "ALL" to transfer everything*/} | {location: Override('Custom Location'), amount: amount /*Use "ALL" to transfer everything*/} | [{currencySelection, isFeeAsset?: true /* for example symbol: symbol or id: id, or Location: Location*/, amount: amount /*Use "ALL" to transfer everything*/}])
  .address(address) //You can also use prederived accounts - //Alice, //Bob... //Alith, //Balthathar...
  .senderAddress(address | PAPI_SIGNER) //You can also use prederived accounts //Alice, //Bob... //Alith, //Balthathar...

const tx = await builder.build()
//Or if you use prederived account as senderAddress:
//await builder.signAndSubmit()

//Disconnect API after TX
await builder.disconnect()

XCM Fee queries

For full documentation with output examples of XCM Fee queries, head to official documentation.

XCM Fee (Origin and Dest.)

const fee = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
          .from(TSubstrateChain)
          .to(TChain)
          .currency(CURRENCY_SPEC)
          /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in the same fee asset as selected currency.*/
          .address(RECIPIENT_ADDRESS)
          .senderAddress(address | PAPI_SIGNER)
          .getXcmFee(/*{disableFallback: true / false}*/)  //Fallback is optional. When fallback is disabled, you only get notified of a DryRun error, but no Payment info query fallback is performed. Payment info is still performed if Origin or Destination chain do not support DryRun out of the box.

XCM Fee (Origin only)

const fee = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
          .from(TSubstrateChain)
          .to(TChain)
          .currency(CURRENCY_SPEC)
          /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in the same fee asset as selected currency.*/
          .address(RECIPIENT_ADDRESS)
          .senderAddress(address | PAPI_SIGNER)
          .getOriginXcmFee(/*{disableFallback: true / false}*/)  //Fallback is optional. When fallback is disabled, you only get notified of a DryRun error, but no Payment info query fallback is performed. Payment info is still performed if Origin do not support DryRun out of the box.

XCM Transfer info

const info = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
          .from(TSubstrateChain)
          .to(TChain)
          .currency(CURRENCY_SPEC)
          /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in the same fee asset as selected currency.*/
          .address(RECIPIENT_ADDRESS)
          .senderAddress(address | PAPI_SIGNER)
          .getTransferInfo()

Transferable amount

const transferable = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
          .from(TSubstrateChain)
          .to(TChain)
          .currency(CURRENCY_SPEC)
          /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in the same fee asset as selected currency.*/
          .address(RECIPIENT_ADDRESS)
          .senderAddress(address | PAPI_SIGNER)
          .getTransferableAmount()

Minimal transferable amount

const transferable = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
          .from(TSubstrateChain)
          .to(TChain)
          .currency(CURRENCY_SPEC)
          /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in the same fee asset as selected currency.*/
          .address(RECIPIENT_ADDRESS)
          .senderAddress(address | PAPI_SIGNER)
          .getMinTransferableAmount()

Receivable amount

const receivable = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
          .from(TSubstrateChain)
          .to(TChain)
          .currency(CURRENCY_SPEC)
          /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in the same fee asset as selected currency.*/
          .address(RECIPIENT_ADDRESS)
          .senderAddress(address | PAPI_SIGNER)
          .getReceivableAmount()

Verify ED on destination

const ed = await Builder(/*chain api/builder_config/ws_url_string/ws_url_array - optional*/)
          .from(TSubstrateChain)
          .to(TChain)
          .currency(CURRENCY_SPEC)
          /*.feeAsset(CURRENCY) - Optional parameter when origin === AssetHubPolkadot and TX is supposed to be paid in the same fee asset as selected currency.*/
          .address(RECIPIENT_ADDRESS)
          .senderAddress(address | PAPI_SIGNER)
          .verifyEdOnDestination()

Asset balance

import { getBalance } from "@paraspell/sdk";

//Retrieves the asset balance for a given account on a specified chain (You do not need to specify if it is native or foreign).
const balance = await getBalance({ADDRESS, TChain, CURRENCY_SPEC /*- {id: currencyID} | {symbol: currencySymbol} | {symbol: Native('currencySymbol')} | {symbol: Foreign('currencySymbol')} | {symbol: ForeignAbstract('currencySymbol')} | {location: AssetLocationString | AssetLocationJson}*/, api /* api/ws_url_string optional */});

Ethereum bridge fees

import { getParaEthTransferFees } from "@paraspell/sdk";

const fees = await getParaEthTransferFees(/*api - optional (Can also be WS port string or array o WS ports. Must be AssetHubPolkadot WS!)*/)

Existential deposit queries

import { getExistentialDeposit } from "@paraspell/sdk";

//Currency is an optional parameter. If you wish to query a native asset, the currency parameter is not necessary.
//Currency can be either {symbol: assetSymbol}, {id: assetId}, {location: assetLocation}.
const ed = getExistentialDeposit(Tchain, CURRENCY_SPEC?)

Convert SS58 address

import { convertSs58 } from "@paraspell/sdk";

let result = convertSs58(ADDRESS, TChain) // returns converted address in string

Asset queries

For full documentation with output examples of asset queries, head over to official documentation.

import { getSupportedDestinations, getFeeAssets, getAssetsObject, getAssetId, getRelayChainSymbol, getNativeAssets, getNativeAssets, getOtherAssets, getAllAssetsSymbols, hasSupportForAsset, getAssetDecimals, getParaId, getTChain, getAssetLocation, CHAINS, findAssetInfo, findAssetInfoOrThrow } from  '@paraspell/sdk'

//Get chains that support the specific asset related to origin
getSupportedDestinations(TChain, CURRENCY)

//Get reserve chain for specific asset on specific chain
getAssetReserveChain(chain: TSubstrateChain, location: TLocation)

//Find out whether asset is registered on chain and return its entire parameters. If not found, returns null.
findAssetInfo(TChain, CURRENCY, DESTINATION?)

//Find out whether asset is registered on chain and return its entire parameters. If not found, returns error.
findAssetInfoOrThrow(TChain, CURRENCY, DESTINATION?)

// Retrieve Fee asset queries (Assets accepted as XCM Fee on specific chain)
getFeeAssets(TChain)

// Get Location for asset ID or symbol on a  specific chain
getAssetLocation(TChain, { symbol: symbol } | { id: assetId })

// Retrieve assets object from assets.json for a particular chain, including information about native and foreign assets
getAssetsObject(TChain)

// Retrieve foreign assetId for a particular chain and asset symbol
getAssetId(TChain, ASSET_SYMBOL)

// Retrieve the symbol of the relay chain for a particular chain. Either "DOT" or "KSM"
getRelayChainSymbol(TChain)

// Retrieve string array of native assets symbols for a  particular chain
getNativeAssets(TChain)

// Retrieve object array of foreign assets for a particular chain. Each object has a symbol and an  assetId property
getOtherAssets(TChain)

// Retrieve string array of all asset symbols. (native and foreign assets are merged into a single array)
getAllAssetsSymbols(TChain)

// Check if a chain supports a particular asset. (Both native and foreign assets are searched). Returns boolean
hasSupportForAsset(TChain, ASSET_SYMBOL)

// Get decimals for specific asset
getAssetDecimals(TChain, ASSET_SYMBOL)

// Get specific chain id
getParaId(TChain)

// Get specific TChain from chainID
getTChain(paraID: number, ecosystem: 'Polkadot' | 'Kusama' | 'Ethereum' | 'Paseo' | 'Westend') //When the Ethereum ecosystem is selected, please fill chainID as 1 to select Ethereum.

// Import all compatible chains as constant
CHAINS

Parachain XCM Pallet queries

For full documentation with output examples of pallet queries, head over to official documentation.

import { getDefaultPallet, getSupportedPallets, getPalletIndex, getNativeAssetsPallet, getOtherAssetsPallets, SUPPORTED_PALLETS } from  '@paraspell/sdk';

//Retrieve default pallet for specific Parachain 
getDefaultPallet(chain: TChain)

// Returns an array of supported pallets for a specific Parachain
getSupportedPallets(chain: TChain)

//Returns index of XCM Pallet used by Parachain
getPalletIndex(chain: TChain)

//Returns all pallets for local transfers of native assets for specific chain.
getNativeAssetsPallet(chain: TChain)

//Returns all pallets for local transfers of foreign assets for specific chain.
getOtherAssetsPallets(chain: TChain)

// Print all pallets that are currently supported
console.log(SUPPORTED_PALLETS)

💻 Tests

• Run compilation using pnpm compile

• Run linter using pnpm lint

• Run unit tests using pnpm test

• Run end-to-end tests using pnpm test:e2e

• Run full end-to-end tests using pnpm test:e2e:chopsticks

• Run all core tests and checks using pnpm runAll

[!NOTE] XCM SDK can be tested in Playground.

Contribute to XCM Tools and earn rewards 💰

We run an open Bug Bounty Program that rewards contributors for reporting and fixing bugs in the project. More information on bug bounty can be found in the official documentation.

Get Support 🚑

• Contact form on our landing page.
• Message us on our X.
• Support channel on telegram.

License

Made with 💛 by ParaSpell✨

Published under MIT License.

Supported by