TypeScript package for building on top of the Across Protocol

Getting Started

The @across-protocol/app-sdk provides useful abstractions on top of Across' Smart Contracts and Quotes API.

To learn more visit our docs.

Installation

To get started, install the app sdk and its peer dependency viem.

pnpm i @across-protocol/app-sdk viem

Quick Start

1. Set up the AcrossClient

Firstly, you need to set up the AcrossClient and configure the chains you want to support.

import { createAcrossClient } from "@across-protocol/app-sdk";
import { mainnet, optimism, arbitrum } from "viem/chains";

const client = createAcrossClient({
  integratorId: "0xdead", // 2-byte hex string
  chains: [mainnet, optimism, arbitrum],
});

2. Retrieve a quote

Now, you can retrieve a quote for a given route with an arbitrary token pair.

import { parseEther } from "viem";

// USDC from Arbitrum -> ETH on Optimism
const route = {
  originChainId: arbitrum.id,
  destinationChainId: optimism.id,
  inputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
  outputToken: "0x0000000000000000000000000000000000000000", // Native ETH
};

const swapQuote = await client.getSwapQuote({
  route,
  amount: parseUnit("10", 6), // USDC decimals
});

Note that we provide additional utilities for retrieving available routes, chain details, and token infos. See here.

3. Execute a quote

After retrieving a quote, you are ready to execute it.

import { useWalletClient } from "wagmi";

const wallet = useWalletClient();

await client.executeSwapQuote({
  walletClient: wallet,
  swapQuote, // returned by `client.getSwapQuote`
  onProgress: (progress) => {
    if (progress.step === "approve" && progress.status === "txSuccess") {
      // if approving an ERC20, you have access to the approval receipt
      const { txReceipt } = progress;
    }
    if (progress.step === "deposit" && progress.status === "txSuccess") {
      // once deposit is successful you have access to depositId and the receipt
      const { depositId, txReceipt } = progress;
    }
    if (progress.step === "fill" && progress.status === "txSuccess") {
      // if the fill is successful, you have access the following data
      const { fillTxTimestamp, txReceipt, actionSuccess } = progress;
      // actionSuccess is a boolean flag, telling us if your cross chain messages were successful
    }
  },
});

The method will execute a quote by:

1. Approving the SpokePool or SpokePoolPeriphery contract if necessary
2. Depositing the input token on the origin chain (also facilitating an origin swap if necessary)
3. Waiting for the deposit to be filled on the destination chain

You can use the onProgress callback to act on different stages of the execution. Have a look at our example app for a more detailed usage of this method.

Cross-chain message handling

Across enables users to seamlessly interact with your dApp or chain using assets from other chains.

Example: Stake Native ETH on Destination Chain

This example shows you how to use the app-sdk to swap, bridge and stake native ETH across chains. You only need to specify the destination chain actions.

import { createAcrossClient } from "@across-protocol/app-sdk";
import { mainnet, optimism, arbitrum } from "viem/chains";
import { useWalletClient } from "wagmi";

const wallet = useWalletClient();

// Example Staking contract on OP
const stakingAddress = "0x733Debf51574c70CfCdb7918F032E16F686bd9f8";

// 1. Create client
const client = createAcrossClient({
  integratorId: "0xdead", // 2-byte hex string
  chains: [mainnet, optimism, arbitrum],
});

// 2. Retrieve quote for USDC from Arbitrum -> ETH on Optimism
const route = {
  originChainId: arbitrum.id,
  destinationChainId: optimism.id,
  inputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
  outputToken: "0x0000000000000000000000000000000000000000", // Native ETH
};
const swapQuote = await client.getSwapQuote({
  route,
  amount: parseUnit("10", 6), // USDC decimals
  actions: [
    {
      // Target contract of destination chain actions
      target: stakingAddress,
      // Human-readable ABI format of method to call
      functionSignature: "function stake(address stakerAddress)",
      // Args to above
      args: [{ value: wallet.address }],
      // Allows to set call value to available balance AFTER bridge
      populateCallValueDynamically: true,
    },
  ],
});

// 3. Execute quote
await client.executeSwapQuote({
  walletClient: wallet,
  swapQuote,
  onProgress: (progress) => {
    // handle progress
  },
});

Authentication

Some Across API features require authentication via an API key. You can provide the key at the client level or per-request.

Client-level API key

const client = createAcrossClient({
  integratorId: "0xdead",
  chains: [mainnet, optimism, arbitrum],
  apiKey: "your-api-key",
});

// All authenticated requests will use this key automatically
const quote = await client.getSwapQuote({ route, amount });

Per-request API key

// Override or provide the key for a single request
const quote = await client.getSwapQuote({
  route,
  amount,
  apiKey: "per-request-key",
});

The key is sent as a Bearer token in the Authorization header.

Deposit details

TODO

Error handling and debugging

TODO

Route, chain and token details

TODO

@across-protocol/app-sdk Reference

For the full detailed reference see here.

AcrossClient

Set Up

• createAcrossClient
• getAcrossClient

Chains and Routes

• getSwapChains
• getSwapTokens

Quotes, Fees and Limits

• getSwapQuote

Transaction Simulations and Executions

• executeSwapQuote

Deposit and Fill Status

• getDeposit
• waitForFillTx

Debugging via Tenderly

• simulateTxOnTenderly

Utilities

Integrator tag

• tagIntegratorId
• getIntegratorDataSuffix

Cross-chain message

• buildMulticallHandlerMessage