Introduction to Swap API

The Across Swap API is the primary integration point for enabling crosschain swaps in your application. It abstracts away the complexity of bridging, DEX routing, approvals, and calldata assembly, returning a ready-to-execute transaction instead of just a quote.

---

Key features

The Across Swap API is important because crosschain UX traditionally forces devs to stitch together multiple bridges and swaps. Swap API eliminates glue logic, reduces fragility, and ensures parity with best-in-class swap/bridge infra. Key features include:

• Crosschain swaps in one step (swap-bridge, bridge-swap, swap-bridge-swap).

• Native & ERC-20 support, with automatic ETH↔WETH wrap/unwrap.

• Application fee support (appFee + appFeeRecipient).

• Chain and token discovery endpoints (/swap/tokens, /swap/chains).

• Ready for production as the recommended API for integrators, replacing suggested-fees API in most cases.

Integrate Swap API Today Read the Full API Reference

---

What Developers Need to Know

To effectively use the Swap API, it's crucial to understand a few core concepts that dictate how transactions are quoted and executed.

tradeType

The tradeType parameter defines the execution strategy for a swap, specifying how input and output amounts are handled. The API supports three distinct types:

• exactInput: Use this when a user wants to send a fixed amount of an input token. The system calculates the amount of the output token they will receive after all fees and slippage are accounted for.

• minOutput: Use this when a user needs to receive at least a certain amount of the output token. The system calculates the required input amount to guarantee this minimum output. The user may receive slightly more than the minimum due to positive slippage (a surplus), but never less.

• exactOutput: Use this when a user needs to receive a precise amount of the output token, which is critical for interacting with contracts that require exact payment amounts (e.g., a specific mint price). The system calculates the necessary input, and if market conditions prevent delivering the exact amount, the transaction is refunded.

💡: If the tradeType is not possible, the Swap API will return a 4XX error.

when using exactOutput some routes may return more tokens than expected. So if you’re using exactOutput with embedded actions, and you need those actions to execute with the exact amount you specify, you should not use dynamic balance, instead, set the values explicitly to the exact amount.

crossSwapType

crossSwapType refers to the routing logic. Behind the scenes, the API intelligently routes your transaction through the most efficient path. It determines the optimal flow based on whether the input and output tokens are "bridgeable" (natively supported by the Across bridge, like USDC or ETH) or "any" token that requires a swap. The response will indicate which of the four paths was chosen:

• bridgeableToBridgeable: A direct bridge, as no swap is needed (e.g., USDC on Arbitrum to USDC on Optimism).

• anyToBridgeable: A swap on the origin chain followed by a bridge (e.g., APE on Optimism → USDC on Optimism → USDC on Arbitrum).

• bridgeableToAny: A bridge followed by a swap on the destination chain (e.g., USDC on Optimism → USDC on Arbitrum → GMX on Arbitrum).

• anyToAny: A swap on the origin, a bridge, and another swap on the destination (e.g., APE on Optimism → USDC on Optimism → USDC on Arbitrum → GMX on Arbitrum).

Liquidity Considerations

While performing a crosschain swap, if liquidity is not present for a particular swap, the Swap API will respond with the error bubbled up from the swap provider.

However for same-asset bridging, the Swap API will simply return a 400 error stating that the relayers donot have sufficient liquidity. This behavior is similar to /suggested-fees API but the Swap API will not return the maximum deposit limit here

Read the Full API Reference Here

---

Swap API vs. Suggested-Fees API

Aspect	Swap API	Suggested-Fees API
Output	Executable calldata for the transaction	Quote data only (requires dev assembly)
Swap Handling	Full swap-bridge-swap support (any → any)	Only bridgeable → bridgeable
App Fee Handling	Set app fee percentage and recipient using query parameters.	requires extra embedded action to charge fees
Use Cases	Should be default for integrators (wallets, dApps, aggregators)	Niche: teams wanting to control their own swap infra or manage custom swap routing

💡: Unless you specifically need to control swap infra, use Swap API. Suggested-fees remains for low-level or custom bridging flows.

---

Helper and Tracking Endpoints

To support integrations and provide visibility into transactions, the API includes several utility endpoints.

Helper Functions

These endpoints are designed to help you programmatically discover supported assets and chains, which is useful for building dynamic user interfaces like token and network selection menus.

• /swap/chains: Returns a comprehensive list of all blockchains supported by the Swap API.

• /swap/tokens: Returns a comprehensive list of all supported tokens for swapping on a given chain. This list is aggregated from multiple sources.

• /swap/sources: Returns a list of all supported sources that support crosschain swaps on Across Protocol. You can filter this by chainId .

Deposit Tracking Endpoints

After a transaction is submitted, these endpoints allow you to monitor its progress and retrieve historical data.

• /deposit/status: Tracks the complete lifecycle of a single deposit. You can query this endpoint with a transaction hash to get the current status, such as pending, filled, slowFillRequested , expired or refunded. This is crucial for providing users with near real-time updates on their transfer.

• /deposits: Fetches a list of all historical deposits for a specific wallet address (depositor). This is useful for building transaction history pages for your users.