\n\n \n\n# Getting Started\n\nThe `@across-protocol/app-sdk` provides useful abstractions on top of Across' Smart Contracts and Quotes API.\n\nTo learn more visit our [docs](https://docs.across.to/).\n\n## Installation\n\nTo get started, install the app sdk and its peer dependency [viem](https://viem.sh/).\n\n```bash\npnpm i @across-protocol/app-sdk viem\n```\n\n## Quick Start\n\n### 1. Set up the `AcrossClient`\n\nFirstly, you need to set up the `AcrossClient` and configure the chains you want to support.\n\n```ts\nimport { createAcrossClient } from \"@across-protocol/app-sdk\";\nimport { mainnet, optimism, arbitrum } from \"viem/chains\";\n\nconst client = createAcrossClient({\n integratorId: \"0xdead\", // 2-byte hex string\n chains: [mainnet, optimism, arbitrum],\n});\n```\n\n### 2. Retrieve a quote\n\nNow, you can retrieve a quote for a given route with an arbitrary token pair.\n\n```ts\nimport { parseEther } from \"viem\";\n\n// USDC from Arbitrum -> ETH on Optimism\nconst route = {\n originChainId: arbitrum.id,\n destinationChainId: optimism.id,\n inputToken: \"0xaf88d065e77c8cC2239327C5EDb3A432268e5831\", // USDC\n outputToken: \"0x0000000000000000000000000000000000000000\", // Native ETH\n};\n\nconst swapQuote = await client.getSwapQuote({\n route,\n amount: parseUnit(\"10\", 6), // USDC decimals\n});\n```\n\nNote that we provide additional utilities for retrieving available routes, chain details, and token infos.\nSee [here](#chains-and-routes).\n\n### 3. Execute a quote\n\nAfter retrieving a quote, you are ready to execute it.\n\n```ts\nimport { useWalletClient } from \"wagmi\";\n\nconst wallet = useWalletClient();\n\nawait client.executeSwapQuote({\n walletClient: wallet,\n swapQuote, // returned by `client.getSwapQuote`\n onProgress: (progress) => {\n if (progress.step === \"approve\" && progress.status === \"txSuccess\") {\n // if approving an ERC20, you have access to the approval receipt\n const { txReceipt } = progress;\n }\n if (progress.step === \"deposit\" && progress.status === \"txSuccess\") {\n // once deposit is successful you have access to depositId and the receipt\n const { depositId, txReceipt } = progress;\n }\n if (progress.step === \"fill\" && progress.status === \"txSuccess\") {\n // if the fill is successful, you have access the following data\n const { fillTxTimestamp, txReceipt, actionSuccess } = progress;\n // actionSuccess is a boolean flag, telling us if your cross chain messages were successful\n }\n },\n});\n```\n\nThe method will execute a quote by:\n\n1. Approving the `SpokePool` or `SpokePoolPeriphery` contract if necessary\n2. Depositing the input token on the origin chain (also facilitating an origin swap if necessary)\n3. Waiting for the deposit to be filled on the destination chain\n\nYou can use the `onProgress` callback to act on different stages of the execution.\nHave a look at our [example app](../../apps/example) for a more detailed usage of this method.\n\n## Cross-chain message handling\n\nAcross enables users to seamlessly interact with your dApp or chain using assets from other chains.\n\n### Example: Stake Native ETH on Destination Chain\n\nThis example shows you how to use the app-sdk to swap, bridge and stake native ETH across chains.\nYou only need to specify the destination chain actions.\n\n```ts\nimport { createAcrossClient } from \"@across-protocol/app-sdk\";\nimport { mainnet, optimism, arbitrum } from \"viem/chains\";\nimport { useWalletClient } from \"wagmi\";\n\nconst wallet = useWalletClient();\n\n// Example Staking contract on OP\nconst stakingAddress = \"0x733Debf51574c70CfCdb7918F032E16F686bd9f8\";\n\n// 1. Create client\nconst client = createAcrossClient({\n integratorId: \"0xdead\", // 2-byte hex string\n chains: [mainnet, optimism, arbitrum],\n});\n\n// 2. Retrieve quote for USDC from Arbitrum -> ETH on Optimism\nconst route = {\n originChainId: arbitrum.id,\n destinationChainId: optimism.id,\n inputToken: \"0xaf88d065e77c8cC2239327C5EDb3A432268e5831\", // USDC\n outputToken: \"0x0000000000000000000000000000000000000000\", // Native ETH\n};\nconst swapQuote = await client.getSwapQuote({\n route,\n amount: parseUnit(\"10\", 6), // USDC decimals\n actions: [\n {\n // Target contract of destination chain actions\n target: stakingAddress,\n // Human-readable ABI format of method to call\n functionSignature: \"function stake(address stakerAddress)\",\n // Args to above\n args: [{ value: wallet.address }],\n // Allows to set call value to available balance AFTER bridge\n populateCallValueDynamically: true,\n },\n ],\n});\n\n// 3. Execute quote\nawait client.executeSwapQuote({\n walletClient: wallet,\n swapQuote,\n onProgress: (progress) => {\n // handle progress\n },\n});\n```\n\n## Authentication\n\nSome Across API features require authentication via an API key. You can provide the\nkey at the client level or per-request.\n\n### Client-level API key\n\n```ts\nconst client = createAcrossClient({\n integratorId: \"0xdead\",\n chains: [mainnet, optimism, arbitrum],\n apiKey: \"your-api-key\",\n});\n\n// All authenticated requests will use this key automatically\nconst quote = await client.getSwapQuote({ route, amount });\n```\n\n### Per-request API key\n\n```ts\n// Override or provide the key for a single request\nconst quote = await client.getSwapQuote({\n route,\n amount,\n apiKey: \"per-request-key\",\n});\n```\n\nThe key is sent as a `Bearer` token in the `Authorization` header.\n\n## Deposit details\n\nTODO\n\n## Error handling and debugging\n\nTODO\n\n## Route, chain and token details\n\nTODO\n\n# `@across-protocol/app-sdk` Reference\n\nFor the full detailed reference see [here](./docs/README.md).\n\n## `AcrossClient`\n\n### Set Up\n\n- [`createAcrossClient`](./docs/functions/createAcrossClient.md)\n- [`getAcrossClient`](./docs/functions/getAcrossClient.md)\n\n### Chains and Routes\n\n- [`getSwapChains`](./docs/classes/AcrossClient.md#getswapchains)\n- [`getSwapTokens`](./docs/classes/AcrossClient.md#getswaptokens)\n\n### Quotes, Fees and Limits\n\n- [`getSwapQuote`](./docs/classes/AcrossClient.md#getswapquote)\n\n### Transaction Simulations and Executions\n\n- [`executeSwapQuote`](./docs/classes/AcrossClient.md#executeswapquote)\n\n### Deposit and Fill Status\n\n- [`getDeposit`](./docs/classes/AcrossClient.md#getdeposit)\n- [`waitForFillTx`](./docs/classes/AcrossClient.md#waitforfilltx)\n\n### Debugging via Tenderly\n\n- [`simulateTxOnTenderly`](./docs/classes/AcrossClient.md#simulatetxontenderly)\n\n## Utilities\n\n### Integrator tag\n\n- [`tagIntegratorId`](./docs/functions/tagIntegratorId.md)\n- [`getIntegratorDataSuffix`](./docs/functions/getIntegratorDataSuffix.md)\n\n### Cross-chain message\n\n- [`buildMulticallHandlerMessage`](./docs/functions/buildMulticallHandlerMessage.md)\n","readmeFilename":"README.md"}
![\"across](\"https://raw.githubusercontent.com/across-protocol/toolkit/refs/heads/master/.github/across-logo-dark.png\"){kind=logo}
\n ![\"Version\"](\"https://img.shields.io/npm/v/@across-protocol/app-sdk?colorA=21262d&colorB=21262d&style=flat\")
![\"MIT](\"https://img.shields.io/badge/license-AGPL-21262d?style=flat\"){kind=icon}