Crosschain Payments

Pay requests using stablecoins from any supported network, without manual bridging or token swaps.

Talk to an expert Discover how Request Network API can enhance your app's features - book a call with us.

Warning: Crosschain payments are currently only available in our staging environment at https://api.stage.request.network and are not ready for production use. Use with caution.

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 Polygon wallet.

Benefits

• Flexibility: Payers can pay with their preferred currency.

• 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 signatures from the Payer.

Supported Networks

Crosschain payments are supported on the following blockchain networks:

• Polygon

• Base

• Optimism

• Arbitrum

• Ethereum

Supported Stablecoins

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

The following stablecoins are supported for crosschain payments on both the sending and receiving networks.

• USDC

• USDT

• DAI

How it works

1. Request creation

To enable crosschain payments, the request must be created with the following parameters:

• paymentCurrency included in the Supported Stablecoins and Supported Networks.

• amount greater than 2 - executing crosschain payments under 2 stablecoins is not allowed, even though creating requests has no restrictions on amount .

For more details about creating requests, please see the POST /v1/request endpoint.

2. Payment route fetching

To display a list of possible routes for a given request and payer address, use the GET /v1/request/{paymentReference}/routes endpoint. It returns all of the possible routes based on the payer's token balances.

Route Ranking

The API automatically ranks available payment routes based on the following factors:

• Transaction fees

• Processing speed

Routes that offer a balanced combination of lower fees and faster processing times are ranked higher in the results.

Samechain routes

The API may return samechain routes if the payer address has supported currencies on the same chain as the paymentCurrency .

• Example: paymentCurrency is USDC on Polygon, and the payer has USDT on Polygon

• Gassless transactions - the transaction fees are added on top of the request amount

• No native token (ETH, POL, etc..) needed for gas

Get payment routes

get

Get the payment routes for a request

Path parameters

paymentReferencestringrequired

The payment reference of the request

Example: 0xb3581f0b0f74cc61

Query parameters

walletstringrequired

The wallet address of the payer

Example: 0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7

Header parameters

x-api-keystringrequired

API key for authentication

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.request.network/v1/request/{paymentReference}/routes?wallet=0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7' \
  --header 'x-api-key: text'

200

400

401

404

429

200

Only request network route

Cross chain possible

No routes available

Only request network route

{
  "routes": [
    {
      "id": "REQUEST_NETWORK_PAYMENT",
      "fee": 0,
      "speed": "FAST",
      "price_impact": 0,
      "chain": "MAINNET",
      "token": "REQ"
    }
  ]
}

Available payment routes

3. Getting payment calldata

Once the route is selected, the payer needs to fetch the unsigned payment calldata or intents. If the selected route is a crosschain payment, the GET /v1/request/{paymentReference}/pay endpoint returns an unsigned payment intent. It will also return an unsigned approval permit or unsigned approval calldata, depending on whether the paymentCurrency supports EIP-2612 Permit. For crosschain payments, this endpoint is NOT approval aware - it will return an approval permit or approval calldata even if approval has already been granted.

If the selected route is a direct payment, the GET /v1/request/{paymentReference}/pay returns an unsigned payment calldata. It may also return an approval calldata. For direct payments, this endpoint IS approval aware - it will omit the approval calldata if sufficient approval has already been granted.

Get payment calldata

get

Get the calldata needed to pay a request. For cross-chain payments, returns a payment intent that needs to be signed. For same-chain payments, returns transaction calldata

Path parameters

paymentReferencestringrequired

The payment reference of the request

Example: 0xb3581f0b0f74cc61

Query parameters

walletstringoptional

The wallet address of the payer , required for cross chain payment, optional for regular payments

Example: 0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7

chainstring · enumoptional

The source chain of the cross chain payment

Available options:

tokenstring · enumoptional

The source token of the cross chain payment

Available options:

Header parameters

x-api-keystringrequired

API key for authentication

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.request.network/v1/request/{paymentReference}/pay' \
  --header 'x-api-key: text'

200

400

401

404

429

200

Native currency payment (e.g., ETH)

ERC20 token payment (requires approval)

Cross chain payment with a currency that supports EIP-2612

Cross chain payment with a currency that does not support EIP-2612

Native currency payment (e.g., ETH)

{
  "transactions": [
    {
      "data": "0xb868980b...00",
      "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687",
      "value": {
        "type": "BigNumber",
        "hex": "0x038d7ea4c68000"
      }
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "approvalTransactionIndex": null,
    "hasEnoughBalance": true,
    "hasEnoughGas": true
  }
}

Payment calldata retrieved successfully

4. Signing the payment intent

The intents and calldata returned by the GET /v1/request/{paymentReference}/pay endpoint in the previous step must be signed by the payer's wallet to authorize the crosschain payment. The process for signing the approval varies depending on whether the paymentCurrency supports EIP-2612 Permit, indicated by the metadata response parameter.

    "metadata": {
        "supportsEIP2612": true
    }

If the token does not support EIP-2612 Permit, the payer must sign and submit a standard ERC20 approval transaction.

Ethers V5

import { ethers } from "ethers";

const ethersProvider = new ethers.providers.Web3Provider(
  // Connected wallet provider
  walletProvider as ethers.providers.ExternalProvider,
);
const signer = await ethersProvider.getSigner();

// Response from the `GET /request/{paymentReference}/pay` endpoint
const response = ...

const paymentIntent = JSON.parse(paymentData.paymentIntent);
const supportsEIP2612 = paymentData.metadata.supportsEIP2612;
let approvalSignature = undefined;
let approval = undefined;

if (supportsEIP2612) {
  approval = JSON.parse(paymentData.approvalPermitPayload);

  approvalSignature = await signer._signTypedData(
    approval.domain,
    approval.types,
    approval.values,
  );
} else {
  const tx = await signer.sendTransaction(paymentData.approvalCalldata);
  await tx.wait();
}

const paymentIntentSignature = await signer._signTypedData(
  paymentIntent.domain,
  paymentIntent.types,
  paymentIntent.values,
);

const signedData = {
  signedPaymentIntent: {
    signature: paymentIntentSignature,
    nonce: paymentIntent.values.nonce.toString(),
    deadline: paymentIntent.values.deadline.toString(),
  },
  signedApprovalPermit: approvalSignature
    ? {
      signature: approvalSignature,
      nonce: approval.values.nonce.toString(),
      deadline: approval?.values?.deadline
        ? approval.values.deadline.toString()
        : approval.values.expiry.toString(),
    }
    : undefined,
};

5. Sending the signed data

Finally, the signed payment intent (and possibly the signed approval permit) are sent back to execute the crosschain payment via the POST /v1/request/{paymentIntentId}/send endpoint. It will handle all the necessary steps to complete the payment. A payment.complete event will be sent to the platform's webhooks when the payment is completed.

Send a payment intent

post

Send a payment intent

Path parameters

paymentIntentIdstringrequired

The payment intent ID

Example: 01JNZYZPK7B4YBPD44TM72NDNJ

Header parameters

x-api-keystringrequired

API key for authentication

Body

signedPaymentIntentobjectrequired

The signed payment intent data.

signedApprovalPermitobjectoptional

The EIP2612 gasless token approval data that allows Permit2 to access user tokens

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.request.network/v1/request/{paymentIntentId}/send' \
  --header 'x-api-key: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "signedPaymentIntent": {
      "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "nonce": "1",
      "deadline": "1715222400"
    },
    "signedApprovalPermit": {
      "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "nonce": "1",
      "deadline": "1715222400"
    }
  }'

401

404

429

401

No body

Unauthorized

Custom fee configuration

It will be possible in the future to add a custom fee to the payment, this is currently under development.