X-Chain Client

Overview

The X-Chain (Exchange Chain) Client provides an interface for interacting with Avalanche's Exchange Chain, which handles asset creation, trading, transfers, and UTXO management.

When to use: Use the X-Chain Client for asset operations, UTXO management, and X-Chain transaction queries.

Installation & Setup

For setup instructions, see the Getting Started guide.

import { createAvalancheClient } from "@avalanche-sdk/client";
import { avalanche } from "@avalanche-sdk/client/chains";

const client = createAvalancheClient({
  chain: avalanche,
  transport: { type: "http" },
});

const xChainClient = client.xChain;

Or create a standalone X-Chain client:

import { createXChainClient } from "@avalanche-sdk/client";

const xChainClient = createXChainClient({
  chain: avalanche,
  transport: { type: "http" },
});

Available Methods

The X-Chain Client provides methods for:

Balance Operations: getBalance and getAllBalances (removed in AvalancheGo v1.15.4)
Asset Operations: getAssetDescription, buildGenesis
UTXO Operations: getUTXOs
Block Operations: getHeight, getBlock, getBlockByHeight
Transaction Operations: getTx, getTxStatus (removed in AvalancheGo v1.15.4), getTxFee, issueTx

For complete method documentation with signatures, parameters, and examples, see the X-Chain Methods Reference.

Common Use Cases

Query Balances

Warning

Removed in AvalancheGo v1.15.4

getBalance and getAllBalances call avm.getBalance and avm.getAllBalances, which AvalancheGo v1.15.4 removes. Read the UTXOs with getUTXOs and add the output amounts instead. See getBalance.

// Get balance for specific asset
const balance = await client.xChain.getBalance({
  addresses: ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
  assetID: "AVAX",
});

console.log("Balance:", balance.balance);

// Get all balances for all assets
const allBalances = await client.xChain.getAllBalances({
  addresses: ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
});

console.log("All balances:", allBalances.balances);

Query Asset Information

// Get asset description
const asset = await client.xChain.getAssetDescription({
  assetID: "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
});

console.log("Asset name:", asset.name);
console.log("Asset symbol:", asset.symbol);
console.log("Denomination:", asset.denomination);

Query UTXOs

// Get UTXOs for address
const utxos = await client.xChain.getUTXOs({
  addresses: ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
  sourceChain: "P", // Optional: specify source chain
  limit: 100,
});

console.log("Number of UTXOs:", utxos.utxos.length);

// Paginate through UTXOs if needed
if (utxos.endIndex) {
  const moreUtxos = await client.xChain.getUTXOs({
    addresses: ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
    startIndex: utxos.endIndex,
    limit: 100,
  });
}

Query Transaction Information

// Get transaction
const tx = await client.xChain.getTx({
  txID: "11111111111111111111111111111111LpoYY",
  encoding: "hex",
});

// Get transaction status (removed in AvalancheGo v1.15.4: use getTx, which returns only accepted transactions)
const status = await client.xChain.getTxStatus({
  txID: "11111111111111111111111111111111LpoYY",
});

console.log("Transaction status:", status.status);

// Get transaction fees
const txFee = await client.xChain.getTxFee();
console.log("Transaction fee:", txFee.txFee);
console.log("Create asset fee:", txFee.createAssetTxFee);

Query Block Information

// Get current height
const height = await client.xChain.getHeight();
console.log("Current X-Chain height:", height);

// Get block by height
const block = await client.xChain.getBlockByHeight({
  height: Number(height),
  encoding: "hex",
});

// Get block by ID
const blockById = await client.xChain.getBlock({
  blockID: "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG",
  encoding: "hex",
});

Wallet Operations

For transaction operations (preparing and sending transactions), use the wallet client:

import { createAvalancheWalletClient } from "@avalanche-sdk/client";
import { privateKeyToAvalancheAccount } from "@avalanche-sdk/client/accounts";

const account = privateKeyToAvalancheAccount("0x...");
const walletClient = createAvalancheWalletClient({
  account,
  chain: avalanche,
  transport: { type: "http" },
});

// Prepare and send base transaction
const baseTxn = await walletClient.xChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
      amount: 1, // 1 AVAX
    },
  ],
});

const txID = await walletClient.sendXPTransaction(baseTxn);
console.log("Transaction sent:", txID);

For complete wallet operations documentation, see X-Chain Wallet Methods.

Next Steps

X-Chain Methods Reference - Complete method documentation
X-Chain Wallet Methods - Transaction preparation and signing
Wallet Client - Complete wallet operations
P-Chain Client - Validator and staking operations
C-Chain Client - EVM operations

On this page