Skip to content

docs(crosschain-payments): replace AI-generated content with comprehensive implementation guide #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aimensahnoun wants to merge 1 commit into
base: 03-02-docs_api-features_align_create-requests_page_with_verified_api_behavior_refactor_the_create_requests_docs_to_keep_the_mintlify_layout_while_replacing_ai-generated_uncertain_content_with_verified_guidance_from_legacy_docs._-_remo
Choose a base branch
from
Open

docs(crosschain-payments): replace AI-generated content with comprehensive implementation guide #56

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 130 additions & 58 deletions api-features/crosschain-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,69 +3,141 @@ title: "Crosschain Payments"
description: "Multi-network payment routing with automatic bridging and optimization"
---

## 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.

## 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.

## Crosschain Payments Supported Chains and Currencies

For crosschain (and samechain) payments, the Request Network API supports 12 stablecoins: USDC, USDT, and DAI on 4 chains (Ethereum, Arbitrum One, Base, OP Mainnet).
Copy link

@greptile-apps greptile-apps bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wording could be clearer: states "12 stablecoins" but only 3 stablecoin types are listed (USDC, USDT, DAI). Consider: "3 stablecoins (USDC, USDT, and DAI) across 4 chains, totaling 12 currency-chain pairs"


### Crosschain Payments Supported Chains

Crosschain payments are supported on the following blockchain networks:

- Ethereum
- Arbitrum One
- Base
- OP Mainnet

### Crosschain Payments Supported Currencies

<Warning>
**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions).
Crosschain payments work only with mainnet funds (real money). Test networks are not supported.
</Warning>

## Overview
The following stablecoins are supported for crosschain payments on both the sending and receiving networks:

Crosschain payments enable seamless transactions across different blockchain networks, allowing payers to send from their preferred chain while payees receive on their preferred network.
- USDC
- USDT
- DAI

## How It Works

```mermaid
graph LR
A[Payer: USDC on Polygon] --> B[Bridge Protocol]
B --> C[Payee: USDC on Base]
<Steps>
<Step title="Request creation">
To enable crosschain payments, the request must be created with:

- `paymentCurrency` in the supported stablecoins and supported networks
- `amount` greater than 1 (crosschain execution under 1 stablecoin is not allowed)
Copy link

@greptile-apps greptile-apps bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ambiguous amount requirement: "greater than 1" typically means > 1, but "under 1 is not allowed" suggests >= 1 is valid. Clarify whether the minimum is 1 or 1.01


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

<Step title="Payment route fetching">
Fetch possible routes with [GET /v2/request/{requestId}/routes](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}/routes). The API returns routes based on payer balances.

The API ranks routes by:

- transaction fees
- processing speed

Each route includes fee estimates and breakdowns:

1. **Gas fees** for transfer/approval/execution on the processor side
2. **Service fees** for crosschain infrastructure

For tokens that do not support EIP-2612, payer approval gas is paid directly by the payer and is not included in route total fees.

The API may also return samechain routes when payer funds are on the same chain as `paymentCurrency`.
</Step>

<Step title="Getting payment calldata">
Once a route is selected, fetch unsigned payloads using [GET /v2/request/{requestId}/pay](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}/pay).

- For crosschain routes: returns payment intent + approval payload (permit/calldata)
- For direct samechain routes: returns payment calldata and approval data only when needed
</Step>

<Step title="Signing the payment intent">
Sign the returned payloads with the payer wallet. Approval handling depends on EIP-2612 support.

```typescript
import { ethers } from "ethers";

const ethersProvider = new ethers.providers.Web3Provider(
walletProvider as ethers.providers.ExternalProvider,
);
Comment on lines +84 to +86
Copy link

@greptile-apps greptile-apps bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses deprecated ethers v5 syntax (ethers.providers.Web3Provider). The Integration Tutorial uses wagmi. Consider updating to ethers v6 syntax or wagmi for consistency:

// Ethers v6 syntax
import { BrowserProvider } from "ethers";
const ethersProvider = new BrowserProvider(walletProvider);

Or align with the wagmi pattern from /api-setup/integration-tutorial

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

const signer = await ethersProvider.getSigner();

const paymentIntent = JSON.parse(paymentData.paymentIntent);
Comment on lines +82 to +89
Copy link

@greptile-apps greptile-apps bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code example references undefined variables walletProvider and paymentData. Add context showing where these come from (e.g., from the /v2/request/{requestId}/pay API response)

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,
};
```
</Step>

<Step title="Sending the signed data">
Send signed payment data with [POST /v2/request/payment-intents/{paymentIntentId}](https://api.request.network/open-api/#tag/v2request/POST/v2/request/payment-intents/{paymentIntentId}).

The API processes the payment and sends webhook lifecycle updates, including completion events.
</Step>
</Steps>

## Custom fee configuration

Custom fee configuration is available.

**Benefits:**
- Access to funds across multiple chains
- Automatic routing optimization
- No manual bridging required

## Samechain Payments

A special case of crosschain infrastructure that converts currencies on the same network (e.g., ETH → USDC on Ethereum).

## Supported Networks

<CardGroup cols={2}>
<Card title="Layer 1" icon="link">
Ethereum, BSC, Avalanche, Fantom
</Card>

<Card title="Layer 2" icon="layers">
Polygon, Arbitrum, Base, Optimism
</Card>
</CardGroup>

## Bridge Protocols

- **LayerZero:** Ultra Light Node security
- **Stargate:** Liquidity-based bridging
- **Automatic Selection:** Optimal route chosen

## Used In

<CardGroup cols={4}>
<Card title="Checkout" href="/use-cases/checkout">
Flexible payment options
</Card>

<Card title="Invoicing" href="/use-cases/invoicing">
Accept from any chain
</Card>

<Card title="Payouts" href="/use-cases/payouts">
Send to preferred networks
</Card>

<Card title="Payroll" href="/use-cases/payroll">
Multi-chain employee payments
</Card>
</CardGroup>

## Implementation Details

See [API Reference - Crosschain Payments](/api-reference/crosschain-payments) for complete technical documentation.
See [Platform Fees](/api-features/platform-fees) for setup details (`feePercentage`, `feeAddress`) and implementation examples.