Asset Transfer API Reference¶

Install the Asset Transfer API

Learn how to install asset-transfer-api into a new or existing project.

Get started
Dive in with a tutorial

Ready to start coding? Follow along with a step-by-step tutorial.

How to use the Asset Transfer API

Asset Transfer API Class¶

Holds open an API connection to a specified chain within the ApiPromise to help construct transactions for assets and estimate fees.

For a more in-depth explanation of the Asset Transfer API class structure, check the source code.

Methods¶

Create Transfer Transaction¶

Generates an XCM transaction for transferring assets between chains. It simplifies the process by inferring what type of transaction is required given the inputs, ensuring that the assets are valid, and that the transaction details are correctly formatted.

After obtaining the transaction, you must handle the signing and submission process separately.

public async createTransferTransaction<T extends Format>(
  destChainId: string,
  destAddr: string,
  assetIds: string[],
  amounts: string[],
  opts: TransferArgsOpts<T> = {}
): Promise<TxResult<T>>;

Request parameters

destChainId string required

ID of the destination chain ('0' for relay chain, other values for parachains).

destAddr string required

Address of the recipient account on the destination chain.

assetIds string[] required

Array of asset IDs to be transferred.

When asset IDs are provided, the API dynamically selects the appropriate pallet for the current chain to handle these specific assets. If the array is empty, the API defaults to using the balances pallet.

amounts string[] required

Array of amounts corresponding to each asset in assetIds.

opts TransferArgsOpts<T>

Options for customizing the claim assets transaction. These options allow you to specify the transaction format, fee payment details, weight limits, XCM versions, and more.

format T extends Format

Specifies the format for returning a transaction.

Type Format

export type Format = "payload" | "call" | "submittable";

paysWithFeeOrigin string

The Asset ID to pay fees on the current common good parachain. The defaults are as follows:

Polkadot Asset Hub - 'DOT'
Kusama Asset Hub - 'KSM'

paysWithFeeDest string

Asset ID to pay fees on the destination parachain.

weightLimit { refTime?: string, proofSize?: string }

Custom weight limit option. If not provided, it will default to unlimited.

xcmVersion number

Sets the XCM version for message construction. If this is not present a supported version will be queried, and if there is no supported version a safe version will be queried.

keepAlive boolean

Enables transferKeepAlive for local asset transfers. For creating local asset transfers, if true this will allow for a transferKeepAlive as opposed to a transfer.

transferLiquidToken boolean

Declares if this will transfer liquidity tokens. Default is false.

assetTransferType string

The XCM transfer type used to transfer assets. The AssetTransferType type defines the possible values for this parameter.

Type AssetTransferType

export type AssetTransferType =
  | LocalReserve
  | DestinationReserve
  | Teleport
  | RemoteReserve;

Note

To use the assetTransferType parameter, which is a string, you should use the AssetTransferType type as if each of its variants are strings. For example: assetTransferType = 'LocalReserve'.

remoteReserveAssetTransferTypeLocation string

The remove reserve location for the XCM transfer. Should be provided when specifying an assetTransferType of RemoteReserve.

feesTransferType string

XCM TransferType used to pay fees for XCM transfer. The AssetTransferType type defines the possible values for this parameter.

Type AssetTransferType

export type AssetTransferType =
  | LocalReserve
  | DestinationReserve
  | Teleport
  | RemoteReserve;

Note

To use the assetTransferType parameter, which is a string, you should use the AssetTransferType type as if each of its variants are strings. For example: assetTransferType = 'LocalReserve'.

remoteReserveFeesTransferTypeLocation string

The remote reserve location for the XCM transfer fees. Should be provided when specifying a feesTransferType of RemoteReserve.

customXcmOnDest string

A custom XCM message to be executed on the destination chain. Should be provided if a custom XCM message is needed after transferring assets. Defaults to:

Xcm(vec![DepositAsset { assets: Wild(AllCounted(assets.len())), beneficiary }])

Response parameters

Promise<TxResult<T>

A promise containing the result of constructing the transaction.

dest string

The destination specName of the transaction.

origin string

The origin specName of the transaction.

format Format | 'local'

The format type the transaction is outputted in.

Type Format

export type Format = "payload" | "call" | "submittable";

xcmVersion number | null

The XCM version that was used to construct the transaction.

direction Direction | 'local'

The direction of the cross-chain transfer.

Enum Direction values

Local

Local transaction.

SystemToPara

System parachain to parachain.

SystemToRelay

System paracahin to system relay chain.

SystemToSystem

System parachain to System parachain chain.

SystemToBridge

System parachain to an external GlobalConsensus chain.

ParaToPara

Parachain to Parachain.

ParaToRelay

Parachain to Relay chain.

ParaToSystem

Parachain to System parachain.

RelayToSystem

Relay to System Parachain.

RelayToPara

Relay chain to Parachain.

RelayToBridge

Relay chain to an external GlobalConsensus chain.

method Methods

The method used in the transaction.

Type Methods

type Methods =
  | LocalTransferTypes
  | 'transferAssets'
  | 'transferAssetsUsingTypeAndThen'
  | 'limitedReserveTransferAssets'
  | 'limitedTeleportAssets'
  | 'transferMultiasset'
  | 'transferMultiassets'
  | 'transferMultiassetWithFee'
  | 'claimAssets';

Type LocalTransferTypes

type LocalTransferTypes =
  | 'assets::transfer'
  | 'assets::transferKeepAlive'
  | 'foreignAssets::transfer'
  | 'foreignAssets::transferKeepAlive'
  | 'balances::transfer'
  | 'balances::transferKeepAlive'
  | 'poolAssets::transfer'
  | 'poolAssets::transferKeepAlive'
  | 'tokens::transfer'
  | 'tokens::transferKeepAlive';

tx ConstructedFormat<T>

The constructed transaction.

Type ConstructedFormat<T>

export type ConstructedFormat<T> = T extends 'payload'
  ? GenericExtrinsicPayload
  : T extends 'call'
  ? `0x${string}`
  : T extends 'submittable'
  ? SubmittableExtrinsic<'promise', ISubmittableResult>
  : never;

The ConstructedFormat type is a conditional type that returns a specific type based on the value of the TxResult format field.

Payload format - if the format field is set to 'payload', the ConstructedFormat type will return a GenericExtrinsicPayload
Call format - if the format field is set to 'call', the ConstructedFormat type will return a hexadecimal string (0x${string}). This is the encoded representation of the extrinsic call
Submittable format - if the format field is set to 'submittable', the ConstructedFormat type will return a SubmittableExtrinsic. This is a Polkadot.js type that represents a transaction that can be submitted to the blockchain

Example

Request

import {
  AssetTransferApi,
  constructApiPromise,
} from "@substrate/asset-transfer-api";

async function main() {
  const { api, specName, safeXcmVersion } = await constructApiPromise(
    "wss://wss.api.moonbeam.network"
  );
  const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion);

  let callInfo;
  try {
    callInfo = await assetsApi.createTransferTransaction(
      "2004",
      "0xF977814e90dA44bFA03b6295A0616a897441aceC",
      [],
      ["1000000000000000000"],
      {
        format: "call",
        keepAlive: true,
      }
    );

    console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`);
  } catch (e) {
    console.error(e);
    throw Error(e as string);
  }
}

main()
  .catch((err) => console.error(err))
  .finally(() => process.exit());

Response

Call data: { "origin": "moonbeam", "dest": "moonbeam", "direction": "local", "xcmVersion": null, "method": "balances::transferKeepAlive", "format": "call", "tx": "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600" }

Claim Assets¶

Creates a local XCM transaction to retrieve trapped assets. This function can be used to claim assets either locally on a system parachain, on the relay chain, or on any chain that supports the claimAssets runtime call.

public async claimAssets<T extends Format>(
  assetIds: string[],
  amounts: string[],
  beneficiary: string,
  opts: TransferArgsOpts<T>
): Promise<TxResult<T>>;

Request parameters

assetIds string[] required

Array of asset IDs to be claimed from the AssetTrap.

amounts string[] required

Array of amounts corresponding to each asset in assetIds.

beneficiary string required

Address of the account to receive the trapped assets.

opts TransferArgsOpts<T>

Options for customizing the claim assets transaction. These options allow you to specify the transaction format, fee payment details, weight limits, XCM versions, and more.

format T extends Format

Specifies the format for returning a transaction.

Type Format

export type Format = "payload" | "call" | "submittable";

paysWithFeeOrigin string

The Asset ID to pay fees on the current common good parachain. The defaults are as follows:

Polkadot Asset Hub - 'DOT'
Kusama Asset Hub - 'KSM'

paysWithFeeDest string

Asset ID to pay fees on the destination parachain.

weightLimit { refTime?: string, proofSize?: string }

Custom weight limit option. If not provided, it will default to unlimited.

xcmVersion number

Sets the XCM version for message construction. If this is not present a supported version will be queried, and if there is no supported version a safe version will be queried.

keepAlive boolean

Enables transferKeepAlive for local asset transfers. For creating local asset transfers, if true this will allow for a transferKeepAlive as opposed to a transfer.

transferLiquidToken boolean

Declares if this will transfer liquidity tokens. Default is false.

assetTransferType string

The XCM transfer type used to transfer assets. The AssetTransferType type defines the possible values for this parameter.

Type AssetTransferType

export type AssetTransferType =
  | LocalReserve
  | DestinationReserve
  | Teleport
  | RemoteReserve;

Note

To use the assetTransferType parameter, which is a string, you should use the AssetTransferType type as if each of its variants are strings. For example: assetTransferType = 'LocalReserve'.

remoteReserveAssetTransferTypeLocation string

The remove reserve location for the XCM transfer. Should be provided when specifying an assetTransferType of RemoteReserve.

feesTransferType string

XCM TransferType used to pay fees for XCM transfer. The AssetTransferType type defines the possible values for this parameter.

Type AssetTransferType

export type AssetTransferType =
  | LocalReserve
  | DestinationReserve
  | Teleport
  | RemoteReserve;

Note

To use the assetTransferType parameter, which is a string, you should use the AssetTransferType type as if each of its variants are strings. For example: assetTransferType = 'LocalReserve'.

remoteReserveFeesTransferTypeLocation string

The remote reserve location for the XCM transfer fees. Should be provided when specifying a feesTransferType of RemoteReserve.

customXcmOnDest string

A custom XCM message to be executed on the destination chain. Should be provided if a custom XCM message is needed after transferring assets. Defaults to:

Xcm(vec![DepositAsset { assets: Wild(AllCounted(assets.len())), beneficiary }])

Response parameters

Promise<TxResult<T>>

A promise containing the result of constructing the transaction.

dest string

The destination specName of the transaction.

origin string

The origin specName of the transaction.

format Format | 'local'

The format type the transaction is outputted in.

Type Format

export type Format = "payload" | "call" | "submittable";

xcmVersion number | null

The XCM version that was used to construct the transaction.

direction Direction | 'local'

The direction of the cross-chain transfer.

Enum Direction values

Local

Local transaction.

SystemToPara

System parachain to parachain.

SystemToRelay

System paracahin to system relay chain.

SystemToSystem

System parachain to System parachain chain.

SystemToBridge

System parachain to an external GlobalConsensus chain.

ParaToPara

Parachain to Parachain.

ParaToRelay

Parachain to Relay chain.

ParaToSystem

Parachain to System parachain.

RelayToSystem

Relay to System Parachain.

RelayToPara

Relay chain to Parachain.

RelayToBridge

Relay chain to an external GlobalConsensus chain.

method Methods

The method used in the transaction.

Type Methods

type Methods =
  | LocalTransferTypes
  | 'transferAssets'
  | 'transferAssetsUsingTypeAndThen'
  | 'limitedReserveTransferAssets'
  | 'limitedTeleportAssets'
  | 'transferMultiasset'
  | 'transferMultiassets'
  | 'transferMultiassetWithFee'
  | 'claimAssets';

Type LocalTransferTypes

type LocalTransferTypes =
  | 'assets::transfer'
  | 'assets::transferKeepAlive'
  | 'foreignAssets::transfer'
  | 'foreignAssets::transferKeepAlive'
  | 'balances::transfer'
  | 'balances::transferKeepAlive'
  | 'poolAssets::transfer'
  | 'poolAssets::transferKeepAlive'
  | 'tokens::transfer'
  | 'tokens::transferKeepAlive';

tx ConstructedFormat<T>

The constructed transaction.

Type ConstructedFormat<T>

export type ConstructedFormat<T> = T extends 'payload'
  ? GenericExtrinsicPayload
  : T extends 'call'
  ? `0x${string}`
  : T extends 'submittable'
  ? SubmittableExtrinsic<'promise', ISubmittableResult>
  : never;

The ConstructedFormat type is a conditional type that returns a specific type based on the value of the TxResult format field.

Payload format - if the format field is set to 'payload', the ConstructedFormat type will return a GenericExtrinsicPayload
Call format - if the format field is set to 'call', the ConstructedFormat type will return a hexadecimal string (0x${string}). This is the encoded representation of the extrinsic call
Submittable format - if the format field is set to 'submittable', the ConstructedFormat type will return a SubmittableExtrinsic. This is a Polkadot.js type that represents a transaction that can be submitted to the blockchain

Example

Request

import {
  AssetTransferApi,
  constructApiPromise,
} from "@substrate/asset-transfer-api";

async function main() {
  const { api, specName, safeXcmVersion } = await constructApiPromise(
    "wss://westend-rpc.polkadot.io"
  );
  const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion);

  let callInfo;
  try {
    callInfo = await assetsApi.claimAssets(
      [
        `{"parents":"0","interior":{"X2":[{"PalletInstance":"50"},{"GeneralIndex":"1984"}]}}`,
      ],
      ["1000000000000"],
      "0xf5d5714c084c112843aca74f8c498da06cc5a2d63153b825189baa51043b1f0b",
      {
        format: "call",
        xcmVersion: 2,
      }
    );

    console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`);
  } catch (e) {
    console.error(e);
    throw Error(e as string);
  }
}

main()
  .catch((err) => console.error(err))
  .finally(() => process.exit());

Response

Call data: { "origin": "0", "dest": "westend", "direction": "local", "xcmVersion": 2, "method": "claimAssets", "format": "call", "tx": "0x630c0104000002043205011f00070010a5d4e80100010100f5d5714c084c112843aca74f8c498da06cc5a2d63153b825189baa51043b1f0b" }

Decode Extrinsic¶

Decodes the hex of an extrinsic into a string readable format.

public decodeExtrinsic<T extends Format>(
  encodedTransaction: string,
  format: T
): string;

Request parameters

encodedTransaction string required

A hex encoded extrinsic.

format T extends Format required

Specifies the format for returning a transaction.

Type Format

export type Format = "payload" | "call" | "submittable";

Response parameters

string

Decoded extrinsic in string readable format.

Example

Request

import {
  AssetTransferApi,
  constructApiPromise,
} from "@substrate/asset-transfer-api";

async function main() {
  const { api, specName, safeXcmVersion } = await constructApiPromise(
    "wss://wss.api.moonbeam.network"
  );
  const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion);

  const encodedExt = "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600";

  try {
    const decodedExt = assetsApi.decodeExtrinsic(encodedExt, "call");
    console.log(
      `Decoded tx:\n ${JSON.stringify(JSON.parse(decodedExt), null, 4)}`
    );
  } catch (e) {
    console.error(e);
    throw Error(e as string);
  }
}

main()
  .catch((err) => console.error(err))
  .finally(() => process.exit());

Response

Decoded tx: { "args": { "dest": "0xF977814e90dA44bFA03b6295A0616a897441aceC", "value": "100,000" }, "method": "transferKeepAlive", "section": "balances" }

Fetch Fee Info¶

Fetch estimated fee information for an extrinsic.

public async fetchFeeInfo<T extends Format>(
  tx: ConstructedFormat<T>,
  format: T
): Promise<RuntimeDispatchInfo | RuntimeDispatchInfoV1 | null>;

Request parameters

tx ConstructedFormat<T> required

The constructed transaction.

Type ConstructedFormat<T>

export type ConstructedFormat<T> = T extends 'payload'
  ? GenericExtrinsicPayload
  : T extends 'call'
  ? `0x${string}`
  : T extends 'submittable'
  ? SubmittableExtrinsic<'promise', ISubmittableResult>
  : never;

The ConstructedFormat type is a conditional type that returns a specific type based on the value of the TxResult format field.

Payload format - if the format field is set to 'payload', the ConstructedFormat type will return a GenericExtrinsicPayload
Call format - if the format field is set to 'call', the ConstructedFormat type will return a hexadecimal string (0x${string}). This is the encoded representation of the extrinsic call
Submittable format - if the format field is set to 'submittable', the ConstructedFormat type will return a SubmittableExtrinsic. This is a Polkadot.js type that represents a transaction that can be submitted to the blockchain

format T extends Format required

Specifies the format for returning a transaction.

Type Format

export type Format = "payload" | "call" | "submittable";

Response parameters

Promise<RuntimeDispatchInfo | RuntimeDispatchInfoV1 | null>

A promise containing the estimated fee information for the provided extrinsic.

Type RuntimeDispatchInfo

export interface RuntimeDispatchInfo extends Struct {
  readonly weight: Weight;
  readonly class: DispatchClass;
  readonly partialFee: Balance;
}

For more information on the underlying types and fields of RuntimeDispatchInfo, check the RuntimeDispatchInfo source code.

Type RuntimeDispatchInfoV1

export interface RuntimeDispatchInfoV1 extends Struct {
  readonly weight: WeightV1;
  readonly class: DispatchClass;
  readonly partialFee: Balance;
}

For more information on the underlying types and fields of RuntimeDispatchInfoV1, check the RuntimeDispatchInfoV1 source code.

Example

Request

import {
  AssetTransferApi,
  constructApiPromise,
} from "@substrate/asset-transfer-api";

async function main() {
  const { api, specName, safeXcmVersion } = await constructApiPromise(
    "wss://wss.api.moonbeam.network"
  );
  const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion);

  const encodedExt = "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600";

  try {
    const decodedExt = await assetsApi.fetchFeeInfo(encodedExt, "call");
    console.log(`Fee info:\n${JSON.stringify(decodedExt, null, 4)}`);
  } catch (e) {
    console.error(e);
    throw Error(e as string);
  }
}

main()
  .catch((err) => console.error(err))
  .finally(() => process.exit());

Response

Fee info: { "weight": { "refTime": 163777000, "proofSize": 3581 }, "class": "Normal", "partialFee": 0 }