> ## Documentation Index
> Fetch the complete documentation index at: https://docs.request.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Crosschain Payments

> Multi-network payment routing with automatic bridging via LiFi

<Warning>
  **Breaking change (March 2026):** The crosschain payment flow has been redesigned. The old payment-intent signing flow (`POST /v2/request/payment-intents/:paymentIntentId`) has been removed. Crosschain payments now return executable transaction calldata directly. See updated steps below.
</Warning>

## Overview

Crosschain payments allow users to pay a request using a stablecoin from a different blockchain network than the one specified on the request. For example, a payer can pay a request for USDC on Base using USDT from their Optimism wallet. Crosschain routing is powered by [LiFi](https://li.fi/), which aggregates bridges and DEXs to find optimal routes.

<Info>
  Cross-chain routing uses the Across bridge (LiFi routes are restricted to Across for predictable, supported settlement). A circuit breaker automatically degrades gracefully if the LiFi routing service is impaired—routes may temporarily be unavailable during an outage, but payments remain detectable and the API stays responsive.
</Info>

## Benefits

* **Flexibility:** Payers can pay with their preferred stablecoin on any supported chain.
* **Cost-Effective:** Automated routing balances cost and speed.
* **Time-Saving:** Payers don't need to swap or bridge tokens manually.
* **Simplified UX:** Payment settlement requires only 1 or 2 transactions from the payer.

## Crosschain Payments Supported Chains and Currencies

For crosschain (and samechain) payments, the Request Network API supports USDC and USDT on 5 chains.

<Info>
  Bridged USDC (USDC.e) is **not** supported for crosschain payments. Only native USDC is supported.
</Info>

### Supported Chains

* Ethereum
* Arbitrum One
* Base
* OP Mainnet
* Polygon

### Supported Currencies

<Warning>
  Crosschain payments work only with mainnet funds (real money). Test networks are not supported.
</Warning>

* USDC
* USDT

## How It Works

<Steps>
  <Step title="Create the request">
    Create a request with a `paymentCurrency` in the supported stablecoins and networks. The `amount` must be greater than 1 USD equivalent (e.g., at least 1.01 USDC) — crosschain routes are not available for amounts of \$1 or less due to bridge minimums.

    Create the request via [POST /v2/request](https://api.request.network/open-api/#tag/v2request/POST/v2/request).
  </Step>

  <Step title="Fetch payment routes">
    Fetch available routes with [GET /v2/request/{requestId}/routes](https://api.request.network/open-api/#tag/v2request/GET/v2/request/\{requestId}/routes).

    **Required query parameters:**

    * `wallet` — the payer's wallet address

    **Optional query parameters:**

    * `feePercentage` and `feeAddress` — for platform fee inclusion in route calculations

    The API returns routes ranked by fees and speed. Each route includes:

    * `chain` and `token` — the source chain and token
    * `fee` — total fee as a decimal
    * `feeBreakdown[]` — detailed fee components (gas, crosschain, platform)
    * `speed` — `"FAST"` for same-chain, seconds estimate for crosschain

    The API may also return samechain routes when the payer has funds on the same chain as `paymentCurrency`.

    ```json Example routes response theme={null}
    {
      "routes": [
        {
          "id": "REQUEST_NETWORK_PAYMENT",
          "fee": 0,
          "feeBreakdown": [],
          "speed": "FAST",
          "chain": "BASE",
          "token": "USDC"
        },
        {
          "id": "ARBITRUM_BASE_USDT_USDC",
          "fee": 0.001,
          "feeBreakdown": [
            {
              "type": "crosschain",
              "stage": "sending",
              "provider": "lifi",
              "amount": "0.001",
              "amountInUSD": "0.001",
              "currency": "USDT"
            }
          ],
          "speed": 300,
          "chain": "ARBITRUM",
          "token": "USDT"
        }
      ]
    }
    ```
  </Step>

  <Step title="Get payment calldata">
    Once the payer selects a route, fetch executable transaction calldata with [GET /v2/request/{requestId}/pay](https://api.request.network/open-api/#tag/v2request/GET/v2/request/\{requestId}/pay).

    **Query parameters:**

    * `wallet` — the payer's wallet address
    * `chain` — the source chain from the selected route (e.g., `ARBITRUM`)
    * `token` — the source token from the selected route (e.g., `USDT`)

    <Info>
      Both `chain` and `token` must be provided together for crosschain payments. Omit both for same-chain payments.
    </Info>

    The API returns a `transactions` array with ready-to-execute calldata:

    ```json Example crosschain response theme={null}
    {
      "transactions": [
        {
          "data": "0x095ea7b3...",
          "to": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
          "value": "0x0"
        },
        {
          "data": "0xabcdef...",
          "to": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
          "value": "0x0"
        }
      ],
      "metadata": {
        "stepsRequired": 2,
        "needsApproval": true,
        "approvalTransactionIndex": 0,
        "paymentTransactionIndex": 1,
        "routeType": "crosschain",
        "quoteExpiresAt": 1742205771,
        "hasEnoughBalance": true,
        "sourceAmount": "10.02"
      }
    }
    ```

    **Metadata fields:**

    * `stepsRequired` — number of transactions to execute (1 or 2)
    * `needsApproval` — whether a token approval transaction is needed first
    * `approvalTransactionIndex` — index of the approval tx in the array (or `null`)
    * `paymentTransactionIndex` — index of the payment/bridge tx
    * `routeType` — `"crosschain"` or `"samechain"`
    * `quoteExpiresAt` — unix timestamp when the route quote expires
    * `hasEnoughBalance` — whether the payer has sufficient funds
    * `sourceAmount` — the amount the payer needs to send on the source chain (includes bridge fees)

    <Info>
      The API always includes approval transactions in crosschain calldata responses, even if the payer already has sufficient token allowance. This ensures USDT-style tokens (which require resetting allowance to zero before setting a new one) work correctly.
    </Info>
  </Step>

  <Step title="Execute the transactions">
    Send each transaction in the `transactions` array as a standard `eth_sendTransaction`. If `needsApproval` is true, execute the approval transaction first and wait for confirmation before sending the payment transaction.

    ```typescript theme={null}
    import { createWalletClient, createPublicClient, custom, http } from "viem";
    import { arbitrum } from "viem/chains";

    const walletClient = createWalletClient({
      chain: arbitrum,
      transport: custom(window.ethereum),
    });

    const publicClient = createPublicClient({
      chain: arbitrum,
      transport: http(),
    });

    const [account] = await walletClient.getAddresses();

    // Step 1: Send approval transaction (if needed)
    if (metadata.needsApproval && metadata.approvalTransactionIndex != null) {
      const approvalTx = transactions[metadata.approvalTransactionIndex];
      const approvalHash = await walletClient.sendTransaction({
        account,
        to: approvalTx.to,
        data: approvalTx.data,
        value: BigInt(approvalTx.value || 0),
      });
      // Wait for confirmation before proceeding
      await publicClient.waitForTransactionReceipt({ hash: approvalHash });
    }

    // Step 2: Send payment/bridge transaction
    const paymentTx = transactions[metadata.paymentTransactionIndex];
    const paymentHash = await walletClient.sendTransaction({
      account,
      to: paymentTx.to,
      data: paymentTx.data,
      value: BigInt(paymentTx.value || 0),
    });
    ```

    After the payer broadcasts the crosschain transaction, payment detection happens automatically. The API monitors the bridge execution and sends [webhook notifications](/api-features/webhooks-events) when the payment is confirmed on the destination chain.
  </Step>
</Steps>

## Custom fee configuration

Custom fee configuration is available.

See [Platform Fees](/api-features/platform-fees) for setup details (`feePercentage`, `feeAddress`) and implementation examples.