Swap

API Reference: Get Action Submitting transactions differs by source chain VM. Reference available transaction types here. Examples below demonstrate the swap process for each VM. VmId: evm, solana,


alt-vm

(any non-named VM - e.g., Bitcoin, Ripple).

Create a swap transaction

Configure the transaction request

The recipient should only be different from the sender if you are:

Swapping across VMs that use incompatible key formats or cryptographic curves (e.g., EVM <> Solana)
Sending funds to another address

This example prepares a swap from USDC on Base to USDT on Arbitrum. To transact across non-EVM networks, simply update the chainId and token fields to your desired pairs, no further customizations required.

import { sendTransaction } from "@wagmi/core";
import { useAccount } from "wagmi";

const actionRequest = {
  actionType: "swap-action",
  sender: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045", // generally the user's connected wallet address
  srcToken: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // USDC on Base
  dstToken: "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", // USDT on Arbitrum
  srcChainId: 8453, // Base Chain ID
  dstChainId: 42161, // Arbitrum Chain ID
  slippage: 100, // bps
  swapDirection: "exact-amount-in",
  amount: 10000000n, // denominated in srcToken decimals
  recipient: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
};

Generate the transaction

Please visit the Get Action API reference for type definitions, including the ActionRequest and ActionResponse. This API endpoint will return a transaction object we will use to actually execute this transaction.

import { sendTransaction } from "@wagmi/core";
import { useAccount } from "wagmi";

const actionRequest: ActionRequest = {
  actionType: "swap-action",
  sender: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045", // generally the user's connected wallet address
  srcToken: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // USDC on Base
  dstToken: "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", // USDT on Arbitrum
  srcChainId: 8453, // Base Chain ID
  dstChainId: 42161, // Arbitrum Chain ID
  slippage: 100, // bps
  swapDirection: "exact-amount-in",
  amount: 10000000n, // denominated in srcToken decimals
  recipient: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
};

async function getAction({ actionRequest }): Promise<ActionResponse> {
  const url = new URL("https://api-v2.swaps.xyz/api/getAction");

  Object.entries(actionRequest).forEach(([key, value]) => {
    url.searchParams.set(key, String(value));
  });

  const requestOptions = {
    method: "GET",
    headers: { "x-api-key": SWAPS_API_KEY },
  };

  const response = await fetch(url.toString(), requestOptions);

  return await response.json();
}

Broadcast on EVM

In this step, we will broadcast the transaction we generated above on Base. This method will work for any EVM chain. View the EVM transaction type here.

Import the recommended libraries

This example uses Wagmi; however, you can use your preferred provider. The transaction we’ll generate is compatible with any library.

import { useAccount } from "wagmi";
import { sendTransaction, estimateGas } from "@wagmi/core";
import { wagmiConfig } from "../your_wagmi_config_path";

Broadcast the transaction

import { sendTransaction, estimateGas } from "@wagmi/core";
import { arbitrum, base } from "viem/chains";
import { wagmiConfig } from "../your_wagmi_config_path";

export async function broadcastOnEvm({ actionRequest }): Promise<Hash> {
  const account = useAccount({ config: wagmiConfig });
  const { tx } = await getAction({ actionRequest });
  const gas = await estimateGas(wagmiConfig, { account, ...tx });

  const txHash = await sendTransaction(wagmiConfig, {
    ...tx,
    gas,
  });

  return txHash;
}

Broadcast on Solana

Let’s assume we set Solana as the source chain in the actionRequest used to generate our transaction. Let’s see how we can broadcast it on Solana. View the Solana transaction type here.

Import the recommended libraries

We’ll use @solana/web3.js, which is the standard SDK for interacting with the Solana blockchain.

import {
  Connection,
  PublicKey,
  sendAndConfirmTransaction,
  Transaction,
} from "@solana/web3.js";

Broadcast the transaction

import {
  Connection,
  PublicKey,
  sendAndConfirmTransaction,
  Transaction,
} from "@solana/web3.js";

export async function broadcastOnSolana({ actionRequest }): Promise<string> {
  const { tx } = await getAction({ actionRequest });

  const connection = new Connection("https://api.mainnet-beta.solana.com");
  const senderKeypair = ... // Your wallet's keypair (use secure storage)

  const transaction = Transaction.from(Buffer.from(tx.rawTransaction, "base64"));

  const signature = await sendAndConfirmTransaction(connection, transaction, [senderKeypair]);

  return signature;
}

Broadcast on Alt VMs

Let’s assume we set Bitcoin as the source chain in the actionRequest used to generate our transaction. Let’s see how we can broadcast it on Bitcoin. View the alt VM transaction type here. Alt VM transactions are all deposits: the transaction will transfer funds from the sender to the to field specified in the AltVmTransaction response. This transfer triggers the swap transaction and funds will ultimately be delivered to the recipient.

Install recommended package

pnpm i bitcoinjs-lib

Import the recommended libraries

We’ll use bitcoinjs-lib to sign the Bitcoin transaction.

import * as bitcoin from "bitcoinjs-lib";

Broadcast the transaction

This example provides sample code to construct a Bitcoin transaction given the actionResponse transaction object and broadcast it to the network.

import { prepareBtcTx } from "./prepareBtcTx";

export async function sendTransaction() {
  const { tx } = await getAction({ actionRequest });
  const privateKeyWIF = "YOUR_PRIVATE_KEY_IN_WIF_FORMAT";

const keyPair = ECPair.fromWIF(privateKeyWIF, NET);
const payment = bitcoin.payments.p2wpkh({
pubkey: keyPair.publicKey,
network: NET,
});

const utxos = await getUtxosForAddress(payment.address);
const rawTransaction = prepareBtcTx({
tx,
privateKeyWIF,
utxos,
feeRate: 15,
});

const response = await fetch("https://blockstream.info/api/tx", {
method: "POST",
headers: { "Content-Type": "text/plain" },
body: rawTransaction,
});

if (!response.ok) {
const errorText = await response.text();
throw new Error(`Broadcast failed: ${response.status} - ${errorText}`);
}

return await response.text();
}

import * as bitcoin from "bitcoinjs-lib";
import * as ecc from "tiny-secp256k1";
import { ECPairFactory } from "ecpair";

bitcoin.initEccLib(ecc);
const ECPair = ECPairFactory(ecc);

const NET = bitcoin.networks.bitcoin;
const P2WPKH_DUST = 294;
const RBF_SEQUENCE = 0xfffffffd;

interface UTXO {
  txid: string;
  vout: number;
  value: number;
  address: string;
}

interface TxData {
  to: string;
  value: string;
  chainId: number;
  chainKey: string;
}

function estimateVsize(inputs: number, outputs: number): number {
  return 10 + 68 * inputs + 31 * outputs;
}

function selectUtxos(utxos: UTXO[], target: number) {
  const selected = [];
  let total = 0;
  for (const utxo of utxos) {
    selected.push(utxo);
    total += utxo.value;
    if (total >= target) break;
  }
  return { selected, total };
}

export function prepareBtcTx({
  tx,
  privateKeyWIF,
  utxos,
  feeRate = 15,
}: {
  tx: TxData;
  privateKeyWIF: string;
  utxos: UTXO[];
  feeRate?: number;
}): string {
  const outputValue = Number.parseInt(tx.value, 10);
  if (!Number.isFinite(outputValue) || outputValue <= 0) {
    throw new Error(`Invalid tx.value: ${tx.value}`);
  }

  // Validate destination address
  bitcoin.address.toOutputScript(tx.to, NET);

  // Derive change address
  const keyPair = ECPair.fromWIF(privateKeyWIF, NET);
  const payment = bitcoin.payments.p2wpkh({
    pubkey: keyPair.publicKey,
    network: NET
  });

  if (!payment.address) {
    throw new Error("Could not derive P2WPKH address from private key");
  }

  // Estimate fee and select UTXOs
  const vsize2 = estimateVsize(utxos.length, 2);
  const fee2 = Math.ceil(vsize2 * feeRate);
  let target = outputValue + fee2;
  let { selected, total } = selectUtxos(utxos, target);

  // If insufficient, try with single output (no change)
  if (total < target) {
    const vsize1 = estimateVsize(utxos.length, 1);
    const fee1 = Math.ceil(vsize1 * feeRate);
    const target1 = outputValue + fee1;
    const retry = selectUtxos(utxos, target1);

    if (retry.total < target1) {
      throw new Error(`Insufficient funds. Need ${target1} sats, have ${retry.total}`);
    }
    selected = retry.selected;
    total = retry.total;
  }

  // Calculate final outputs
  const inputsCount = selected.length;
  const feeTwoOut = Math.ceil(estimateVsize(inputsCount, 2) * feeRate);
  let change = total - outputValue - feeTwoOut;

  // Handle dust change
  if (change > 0 && change < P2WPKH_DUST) {
    const feeOneOut = Math.ceil(estimateVsize(inputsCount, 1) * feeRate);
    change = total - outputValue - feeOneOut;
    if (change < 0) {
      throw new Error("Fee calculation error");
    }
  }

  // Build transaction
  const psbt = new bitcoin.Psbt({ network: NET });

  // Add inputs
  for (const utxo of selected) {
    psbt.addInput({
      hash: utxo.txid,
      index: utxo.vout,
      sequence: RBF_SEQUENCE,
      witnessUtxo: {
        script: bitcoin.address.toOutputScript(utxo.address, NET),
        value: utxo.value,
      },
    });
  }

  // Add outputs
  psbt.addOutput({ address: tx.to, value: outputValue });

  if (change >= P2WPKH_DUST) {
    psbt.addOutput({ address: payment.address, value: change });
  }

  // Sign all inputs
  for (let i = 0; i < selected.length; i++) {
    psbt.signInput(i, keyPair);
  }

  psbt.finalizeAllInputs();
  return psbt.extractTransaction().toHex();
}

Broadcast on HyperCore

Let’s assume we set HyperCore as the source chain in the actionRequest used to generate our transaction. Let’s see how we can broadcast it on HyperCore. View the HyperCore transaction type here.

Install recommended package

pnpm i @nktkas/hyperliquid viem

Import the recommended libraries

We’ll use the HyperLiquid SDK for interacting with the HyperCore network.

import * as HyperLiquid from "@nktkas/hyperliquid";
import { createWalletClient, custom } from "viem";

Broadcast the transaction

import * as HyperLiquid from "@nktkas/hyperliquid";
import { createWalletClient, custom } from "viem";

export async function broadcastOnHyperCore({ actionRequest }): Promise<string> {
  const { tx } = await getAction({ actionRequest });

  const [account] = await window.ethereum.request({
    method: "eth_requestAccounts",
  });
  const wallet = createWalletClient({
    account,
    transport: custom(window.ethereum),
  });

  const transport = new HyperLiquid.HttpTransport();
  const exchClient = new HyperLiquid.ExchangeClient({ wallet, transport });

  return await exchClient.usdSend({
    destination: tx.destination,
    amount: tx.amount,
  });
}

Getting started

Guides

Resources

Create a swap transaction

Broadcast on EVM

Broadcast on Solana

Broadcast on Alt VMs

Broadcast on HyperCore

​Create a swap transaction

​Broadcast on EVM

​Broadcast on Solana

​Broadcast on Alt VMs

​Broadcast on HyperCore

Create a swap transaction

Broadcast on EVM

Broadcast on Solana

Broadcast on Alt VMs

Broadcast on HyperCore