Migration Guide for API Users

Following migration to Native USDC on a given L2, API users and depositors of USDC will experience the following changes:

If you are making changes to how you query the Across API, then you should also take the opportunity to change how you handle the API responses. In particular, you should migrate to the new host at app.across.to/api and the new suggested-fees response format which deprecates redundant fields.

• /available-routes will replace Bridged USDC addresses with Native USDC addresses for any origin chains where CCTP is enabled. For example, the following route exists showing that a deposit from Bridged USDC on Polygon to USDC on Ethereum is available:

    ...{
      "originChainId": 137,
      "originToken": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
      "destinationChainId": 1,
      "destinationToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    },
    ...

  • Following migration to CCTP on Polygon, the above route will replace the originToken Bridged USDC address with the Native USDC address on Polygon.

• /available-routes will add routes with Native USDC as a possible destinationToken. For example, the following route shows that a deposit from USDC on Ethereum to Bridged USDC on Optimism is available:

   ...{
      "originChainId": 1,
      "originToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "destinationChainId": 10,
      "destinationToken": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607"
    },
    ...
   

  • Following migration to CCTP on Optimism, a new route will be available from USDC on Ethereum to Native USDC Optimism:

    ...{
      "originChainId": 1,
      "originToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "destinationChainId": 10,
      "destinationToken": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607"
    },
    {
      "originChainId": 1,
      "originToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "destinationChainId": 10,
      "destinationToken": "0x0b2c639c533813f4aa9d7837caf62653d097ff85"
    },

• /suggested-fees and /limits will add inputToken and outputToken as optional query parameters. token will become an optional parameter if inputToken and outputToken are set to valid addresses. The caller will need to set the new input and output parameters in order to get fees for Native USDC to Bridged USDC routes since these will not technically be the "equivalent" tokens. The API will infer that the token address is equal to the inputToken and also assume that outputToken should be equal to the equivalent token address. Therefore, token will only be able to be used to get fees for Native USDC to Native USDC routes.

  • For the forseeable future, the fees returned for routes with Native USDC as the output token and Bridged USDC as the output token will be equivalent. However, this can change so we encourage all API users to migrate as soon as possible to using the new input and output parameters instead of just setting token.

  • /limits will return different limits for Native USDC and Bridged USDC based on estimated relayer capacity. Since these are different tokens held on L2s by Relayers, these limits can differ quite a bit.

• Most API users today query limits and fees before submitting a deposit() function transaction directly to the Across contracts. This function only allows the caller to specify a single originToken address, which means that this function will not support Native USDC to Bridged USDC deposits. Users who want access to the new Native USDC to Bridged USDC routes should instead call depositV3() which allows the caller to specify inputToken and outputToken parameters. We encourage all direct smart contract users to eventually migrate to this new deposit function to get access to cross chain token swaps when they go live. You can think of Native USDC to Bridged USDC as the first cross chain token swap supported by Across. Note that token swaps are currently allowed at the smart contract level but most relayers will not support swaps yet. However, relayers will begin to support the Native USDC to Bridged USDC route upon CCTP migration.

• Deposit routes with Bridged USDC as the origin token will no longer be supported at the API and SpokePool contract level. We acknowledge that this might remove a popular route for some partners. We are making this change because we believe that most volume will eventually migrate to Native USDC bridging and some partners already implement origin token swapping before submitting an Across Bridge. For example, some partners already swap Native USDC to Bridged USDC before submitting an Across bridge. We hope that this infrastructure can be reused to swap Bridged USDC into Native USDC before submitting an Across Bridge, but we also acknowledge that this won't always be possible. Therefore, we are deploying the following SwapAndBridge contract to assist with swapping Bridged USDC to Native USDC before submitting an Across deposit. These contracts will be used by our own frontend dApp to continue to support routes with Bridged USDC as the origin token and they have been audited already. We understood that most partners will have to upgrade smart contracts to take advantage of this new flow but we anticipate most partners already either implement origin chain swapping or will be happy to replace Bridged USDC volume with Native USDC volume. If you have any issues or questions about this migration please reach out directly and will work with you to come up with a solution.