What you can do with Request Network

• Easily add invoicing features to your app

• Enable crypto payments in just a few clicks

• Reconcile invoices and payments with 100% accuracy

Start Building with Request Network

EasyInvoice is a web application built with Next.js that allows users to create and manage invoices, and accept crypto payments via the Request Network API. It mimics Web2 apps in its functionalities, providing a user-friendly experience with Google login and real-time updates.

Key Features

Invoice Creation

• Invoice Creation: A simple form to create invoices.

  • Client name and email fields.

  • Items, amounts, and notes fields.

  • Invoice currency and payment currency options, supporting currency conversion via the Request Network API.

• Currency Conversion: uses on-chain price feeds to calculate the exact payment currency amount based on the invoice currency at the moment of payment so you always receive the correct amount.

Dashboard

• Dashboard: View key metrics and a table of your invoices.

Invoice Payment

• Invoice Payment:

  • View invoice details and initiate payment using transaction calldata provided by the Request Network API.

  • Compatible with 50+ different crypto wallets.

• Real-time Updates: The app receives webhooks from the Request Network API to update the invoice status in real-time.

Invoice Crosschain Payment

Crypto-to-fiat Payment

Batch Pay Invoices

Recurring Invoices

• Recurring Invoice: Automatically create new invoices based on the selected start date and frequency

Payout

• Payout: Send a payment without having to create a request first.

Batch Payout

InvoiceMe Link

• InvoiceMe Link: Prompt clients to send you an invoice prefilled with your name and email address.

Login

• Google Login: Securely log in to your account using Google OAuth.

Core Functionality

At its core, the Request Network API empowers you to:

• Create Requests: Define payment requests with information such as payee, payer (optional), amount, currency, and recurrence (optional).

• Facilitate Payments: Return transaction calldata, ready to be signed by end-users and sent to the blockchain for secure and transparent value transfer.

• Deliver Webhook Notifications: Receive instant updates on payment status changes, enabling your application to react dynamically to completed transactions.

• Fee Collection: When paying a request, you can specify a fee percentage (between 0 and 100) and a fee address, which will add the fee on top of the payment amount - meaning the payer will pay the original amount plus the fee percentage, with the fee portion being sent to the specified fee address.

• Partial Payment Support: Pay a portion of a request instead of the full amount at once. This unlocks powerful use cases such as:

  • Split payment: split a payment 50% USDC on Base and 50% with USDT on Optimism.

  • Gradual payment plans: Allow users to pay large invoices in smaller chunks.

  • Risk mitigation: Test with small amounts before completing large payments.

  The API automatically tracks payment progress, showing partially_paid status until the request is fully paid, and prevents overpayment by capping amounts to the remaining balance.

For detailed information on all available endpoints and their parameters, please refer to the full Request Network API Reference

Create and Pay Request Workflow

The following diagram illustrates the typical flow for creating and paying requests using the Request Network API:

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.

Supported Networks

Crosschain payments are supported on the following blockchain networks:

• Base

• Optimism

• Arbitrum

• Ethereum

Supported Stablecoins

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 1 - executing crosschain payments under 1 stablecoins is not allowed, even though creating requests has no restrictions on amount .

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

2. Payment route fetching

To display a list of possible routes for a given request and payer address, use the GET /v2/request/{requestId}/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.

Fee breakdown

When fetching payment routes, each route displays the total estimated fees in the payment currency. This fee represents the combined costs associated with processing the transaction, including:

1. Gas Fees:

   The total fee includes all gas costs incurred by the payment processor wallet for processing the transaction. This covers:

   - Transferring tokens from the payer's wallet.

   - Approving the payment execution smart contract.

   - Executing the crosschain payment transaction.

   For tokens supporting EIP-2612:

   - The payment processor wallet also covers for the onchain permit transaction.

   For tokens that do not support EIP-2612:

   - The payer must perform an onchain approval transaction and pay for the gas fee directly. This fee is not included in the total fee shown for the route.

2. Service Fees:

   The total fees also include any service fees charged by the crosschain infrastructure for facilitating transfers or swaps between different blockchains.

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 Base, and the payer has USDT on Base

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

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

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 /v2/request/{requestId}/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 /v2/request/{requestId}/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.

4. Signing the payment intent

The intents and calldata returned by the GET /v2/request/{requestId}/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.

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/{requestId}/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 /v2/request/payment-intents/{paymentIntentId} 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.

Custom fee configuration

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

Overview

Batch payments enable you to process multiple payment requests efficiently in a single blockchain transaction, reducing gas costs and simplifying multi-recipient workflows.

Two Types of Batch Payments:

Batch Pay Invoices

Process previously created requests using their request IDs and receive payment calldata that can be executed on-chain to pay multiple requests simultaneously.

Batch Payouts

Submit new payment requests that are immediately processed, creating requests and returning payment calldata in a single API call for instant multi-recipient payments.

Key Benefits

• Gas Efficiency: Significantly reduce transaction costs by batching multiple payments

• Simplified UX: Process up to 200 payments in a single transaction

• Mixed Payment Types: Support ERC20, native tokens, and conversion payments in the same batch

• Atomic Execution: All payments succeed or fail together, ensuring consistency

Batch Processing Limits

The theoretical limit for batch payments is 100-200 payments per transaction, depending on:

• Payment complexity (ERC20 vs native tokens vs conversions)

• Available block gas limit on the target network

• Smart contract computational requirements

For optimal performance, we recommend starting with smaller batches (10-50 payments) and scaling based on your network conditions.

Batch Payment Workflow

Endpoints

Implementation Examples

The following examples demonstrate how to implement batch payment calldata execution in your application. Note: The API returns unsigned transaction calldata - your application must handle sending these transactions to the blockchain.

Batch Pay Invoices Example

import { ethers } from 'ethers';

// Get unsigned calldata to pay existing requests by their IDs
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key',
    'x-platform-id': 'your-platform-id'
  },
  body: JSON.stringify({
    requestIds: [
      "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
      "02f384fdd39e5c627e04b1f2e6fd60593783b8863c3c789197f5bd381527b8ecd"
    ],
    payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
  })
});

const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();

// Your app must implement sending these transactions to the blockchain
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

// 1. Handle ERC20 approvals if needed
for (const approval of ERC20ApprovalTransactions) {
  const tx = await signer.sendTransaction(approval);
  await tx.wait();
}

// 2. Send the batch payment transaction
const batchTx = await signer.sendTransaction(batchPaymentTransaction);
await batchTx.wait();

Batch Payouts Example

// Create new requests and process them immediately
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key',
    'x-platform-id': 'your-platform-id'
  },
  body: JSON.stringify({
    requests: [
      {
        payee: "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
        amount: "10",
        invoiceCurrency: "USD",
        paymentCurrency: "USDC-sepolia"
      },
      {
        payee: "0xb07D2398d2004378cad234DA0EF14f1c94A530e4",
        amount: "25.50",
        invoiceCurrency: "EUR", 
        paymentCurrency: "DAI-sepolia"
      }
    ],
    payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
  })
});

const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();

// Your app must implement the blockchain transaction execution
// (same pattern as Batch Pay Invoices example above)

Supported Payment Types

Batch payments support mixing different payment types in a single transaction:

• ERC20 Token Payments: Standard token transfers

• Native Token Payments: ETH, MATIC, etc.

• Conversion Payments: Requests denominated in one currency but paid in another (e.g., USD invoices paid with USDC)

Key Implementation Notes

Your Responsibility

• API Call: Your application calls the Request Network API to get transaction data

• Blockchain Execution: Your application executes the returned transaction data on the blockchain

• Error Handling: Your application handles transaction failures and retries

Best Practices

1. Validate Addresses: Always validate recipient addresses before submitting batch payments

2. Test on Testnets: Start with small batches on test networks before production deployment

3. Handle Failures Gracefully: Implement proper error handling for transaction failures

4. Gas Estimation: Consider gas costs when determining optimal batch sizes

5. User Experience: Provide clear progress indicators for multi-step approval processes

Error Handling

Common error scenarios and their solutions:

• Network Mismatch: Ensure all requests use the same blockchain network

• Insufficient Funds: Verify payer has sufficient balance for all payments plus gas

• Invalid Addresses: Validate all payee addresses before batch submission

• Gas Limit Exceeded: Reduce batch size if hitting network gas limits

Demo Application

See the batch payment feature in action in our EasyInvoice demo application:

EasyInvoice Batch Pay Invoices

EasyInvoice: Batch Payouts

For detailed information on all available endpoints and their parameters, please refer to the full Request Network API Reference.

For more implementation details, explore the EasyInvoice source code.

Crypto-to-fiat payments allow a Payer to pay a Request in cryptocurrency, while the Payee receives fiat currency directly in their bank account. This is achieved by combining the Request Network crypto payment with Request Tech offramp infrastructure. This requires prerequisite compliance (KYC/Agreement) and bank account registration (payment detail) flows.

EasyInvoice includes a reference implementation for this flow.

Getting Started with Crypto-to-fiat Payments

Sandbox Access - Get Started Today

All developers can immediately access the Crypto-to-fiat Sandbox to build and test their integration:

1. Create an account on the Request Network API Portal

2. Generate a Sandbox API key with crypto-to-fiat sandbox access

3. Start building with Sepolia testnet USDC, simulated KYC, and mock bank accounts

The sandbox provides a complete testing environment where you can:

• Test the full crypto-to-fiat flow without real funds

• Simulate payer KYC verification using mock documents

• Work with mock bank account data and fiat payment status

Production Access - Launch When Ready

When you're ready to go live with real transactions:

1. Book a call to request production access

2. Discuss your use case with our team to ensure the best integration approach

3. Complete the approval process - we'll work with you to get everything set up

4. Generate Production API keys once approved

Production access includes:

• Real USDC transactions on mainnet

• Actual KYC verification for payers

• Live bank account validation

• Fiat deposits to real bank accounts

Understanding clientUserId

Many /payer endpoints in the Request Network API require a clientUserId as a path parameter. This value is an arbitrary identifier chosen by your platform to represent a user (the payer) in your own system.

• You control the format: The clientUserId can be any unique string that makes sense for your application. It can be a UUID, email address, database ID, or anything unique per user on your platform.

• EasyInvoice Example: In the EasyInvoice demo app, clientUserId is set to the user's email address.

• Why is this useful? This approach allows you to integrate the Request Network API without having to change your existing user management logic. You simply pass your own identifier to the API, and all payer-related compliance, agreement, and payment detail records will be associated with that value.

Example usage:

GET /v2/payer/{clientUserId}
PATCH /v2/payer/{clientUserId}
POST /v2/payer/{clientUserId}/payment-details
GET  /v2/payer/{clientUserId}/payment-details

In each case, replace {clientUserId} with your chosen identifier for the user.

Compliance & Payer Onboarding

Before a payer can use crypto-to-fiat, they must complete compliance steps:

• KYC: The payer must submit a KYC application.

• Agreement: The payer must sign a compliance agreement (via an iframe flow).

• Bank Account: The payee's bank account must be associated with a payer for compliance reasons, even though the payee owns the account.

Compliance Flow Diagram

Flow Explanation

1. Submit KYC: The platform collects KYC information from the payer and submits it to the API.

2. KYC Review: The platform receives webhook updates as the KYC is processed (compliance.updated with kycStatus).

3. Agreement Signature: The platform displays an iframe for the payer to sign the compliance agreement. Once signed, the platform calls the API to update the agreement status.

4. Agreement Confirmation: The platform receives a webhook update when the agreement is completed (compliance.updated with agreementStatus).

Relevant Endpoints

• POST /payer: Submit KYC application.

• GET /payer/{clientUserId}: Get compliance status for a payer.

• PATCH /payer/{clientUserId}: Update agreement status after signature.

Setting Up a Crypto-to-Fiat Request (Payee Flow)

Before a payer can pay in crypto and the payee can receive fiat, the platform must:

• Submit the payee’s bank account details (associated with a payer for compliance).

• Wait for approval of those payment details (usually less than 60 seconds, confirmed via webhook).

• Create a new request with isCryptoToFiatAllowed = true.

Payment Details Flow Diagram

Flow Explanation

1. Submit Bank Account: The platform submits the payee’s bank account details, associating them with a payer. The Request Network API forwards these details to the offramp provider (Request Tech).

2. Approval: The platform receives a webhook (payment_detail.updated) indicating if the payment details are approved, failed, or pending.

3. Create Request: Once approved, the platform creates a new request as usual, but with the isCryptoToFiatAllowed flag set to true. This signals that the request is eligible for crypto-to-fiat payment.

Design Rationale & UX Constraints

While it is technically possible to create a crypto-to-fiat request before the payer has completed KYC, EasyInvoice intentionally requires the payer to complete KYC first. This decision is based on several practical and UX considerations:

• Bank Account Association: The payee’s bank account ("payment details") must be linked to a specific payer, which can only be done after the payer completes KYC. This ensures compliance and accurate association of payment details.

• Validation Complexity: Although the payee could submit their bank account details in advance, the platform cannot validate or approve these details until the payer’s KYC is complete. This would introduce additional communication steps and potential confusion.

• UI Simplicity: EasyInvoice integrates payee bank account registration directly into the Create Invoice form. If the user clicks "Create" before the bank account is approved, a loading indicator appears until approval is granted. This avoids the need for a separate bank account management page and keeps the user experience straightforward.

• Protocol Fit: The crypto-to-fiat feature is integrated at the API level, not at the Request Network protocol level. Creating a request on the protocol does not require bank account details, because the protocol itself only handles crypto payments. The additional bank account and offramp logic is layered on top via the API, which transfers crypto to Request Tech, who then executes the offramp and sends fiat to the payee’s bank account. This separation adds some complexity, so the UI is intentionally kept simple.

• Future Flexibility: While some clients may want to allow payees to create requests before payer KYC, this is not currently supported in EasyInvoice to avoid increased complexity. We may revisit this if there is sufficient market demand.

This approach ensures a smooth, compliant, and user-friendly experience, even if it means some technical possibilities are not exposed in the current UI.

Relevant Endpoints

• POST /payer/{clientUserId}/payment-details: Create payment details (register bank account) for a payee.

• GET /payer/{clientUserId}/payment-details: Get payment details (bank accounts) for a payee.

• POST /v2/request with isCryptoToFiatAllowed = true: Create a new crypto-to-fiat request

Paying a Crypto-to-Fiat Request

The payer pays in crypto; Request Tech handles offramping and fiat payout.

Payment Flow Diagram

Flow Explanation

1. Get Payment Calldata: The platform fetches payment calldata for the request.

2. User Pays: The payer signs and submits the transaction, sending crypto to Request Tech.

3. Offramp Processing: Request Tech receives the crypto and begins the offramp process.

4. Status Updates: The platform receives webhook events as the offramp progresses (payment.processing, payment.failed), with subStatus indicating the current offramp stage.

5. Fiat Delivered: When the offramp is complete, the platform receives a final webhook (payment.processing with subStatus: fiat_sent), and then a payment.confirmed event.

Crypto-to-fiat Webhook Event Reference

Overview

The Request Network API Portal provides app developers with a platform to securely manage their API keys and webhook endpoints.

Key Features

API Key Management

• Create and Manage API Keys: Users can create new API keys for authentication.

• Toggle and Delete API Keys: API keys can be toggled on and off, or deleted if no longer needed, enhancing control over API access.

• Security Guidelines: API keys are sensitive and should never be shared publicly. In case of compromise, users are advised to create a new key, update their code, and delete the compromised key.

• Multiple Keys: Allows the creation of multiple API keys for different environments or applications.

Webhook Management

• Create and Manage Webhooks: App developers can configure webhook endpoints to receive real-time notifications for payment events.

• Security Guidelines: Each webhook request includes a signature in the `x-request-network-signature` header to ensure authenticity.

• Signature Verification: The signature is a SHA-256 HMAC of the request body, signed using the webhook secret.

Example Verification Code:

import express from 'express';
import crypto from 'node:crypto';

const app = express();
const WEBHOOK_SECRET = 'your_webhook_secret';

app.post('/payment', async (req, res) => {
  const signature = req.headers['x-request-network-signature'];
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).json({
      success: false,
      message: 'Invalid signature'
    });
  }

  // Business logic here
  return res.status(200).json({ success: true });
});

Usage

Creating API Keys

• Navigate to the "API Keys" section.

• Click on "Create new key."

• Store the key securely and never share it publicly.

Configuring Webhooks

• Navigate to the "Webhooks" section.

• Click on "Add webhook."

• Enter the endpoint URL and ensure the endpoint is secure and can handle incoming JSON payloads.

Security Considerations

• Keep API keys and webhook secrets secure. Never expose them in public repositories or client-side code.

• Verify all webhook signatures to ensure authenticity and integrity.

• Use HTTPS for all endpoints to encrypt communication.

The typical lifecycle of a request is as follows:

Create a request

• The payer or payee signs the request which contains the payee, payer, currency, amount, payment details, and arbitrary content data.

• The request can be optionally encrypted such that only the payee, payer, and approved 3rd parties can view the request contents.

• The request is persisted in IPFS.

• The IPFS Content-addressable ID (CID) is stored in a smart contract on Gnosis chain

Update a request

• The payee can optionally cancel the request or increase/decrease the expected amount.

• The payer can optionally accept the request, indicating that they intend to pay it.

• Both payee and payer can add 3rd party stakeholders if the request is encrypted.

Pay a request

• The payer derives a paymentReference from the request contents.

• The payer calls a function on the payment network smart contract, passing in the token address, to address, amount, and paymentReference.

• An event is emitted containing the token address, to address, amount, and paymentReference.

Retrieve a request / Detect a payment

• The event is indexed by the payments subgraph

• An app can retrieve the request contents from IPFS and calculate the balance based on events from the payments subgraph.

Request Scan is an explorer for viewing requests and payments in Request Network. It enables users to explore and scrutinize requests, payments, and addresses within the Request Network ecosystem.

Intended Audience

Request Scan caters to a broad audience:

• Accountants: Audit and verify financial data on the request network.

• Developers: Easily access Request Network data for troubleshooting your applications.

• Analysts: Gain deep insights into network activity and trends.

• Researchers: Conduct in-depth studies on blockchain data.

• Enthusiasts: Stay informed about the latest happenings on the Request Network.

Usage

User Interface

• Search Bar: Located at the top, allows you to search for specific requests or addresses.

• Dashboard: Provides an overview of network statistics and recent activity.

• Requests: View a list of recent requests with details like payee, payer, amount, and timestamp.

• Payments: View a list of recent payments with details like blockchain transactions, amounts, fees, and timestamps.

• Address: View information about individual addresses, including their requests and payments.

• Request: View information about individual requests, including their details and table with actions and payments.

Searching for Data

• Request: Enter a request ID in the search bar to view its details.

• Address: Enter an address to see its requests and payment history.

Demo Video

The Request Network API V2 introduces significant improvements while maintaining backward compatibility. This guide provides a comprehensive overview of the breaking changes between V1 and V2, along with a step-by-step migration guide.

Breaking Changes from V1 to V2

Core Architectural Changes

Path Parameter Changes

• V1: Uses paymentReference as the path parameter

• V2: Uses requestId as the path parameter

Response Schema Standardization

• V1: Returns requestID (uppercase D) in create responses

• V2: Returns requestId (lowercase d) in create responses

Enhanced Validation

• V2: Stricter type checking and validation schemas

• V1: More permissive validation

API Interface Differences

Endpoint Structure Changes

Request Endpoints

Payment Endpoints

Request Schema Differences

Create Request Schema

V1 Schema:

V2 Schema:

Create Response Schema

V1 Response:

V2 Response:

Payment Query Parameter Differences

Pay Request Query Parameters

V1 Query Parameters:

V2 Query Parameters:

Step-by-Step Migration Guide

Phase 1: Assessment and Planning

1. Audit Your Current Integration

   • List all V1 endpoints you're currently using

   • Identify which features you need (basic payments vs advanced features)

2. Choose Migration Strategy

   • Incremental: Migrate endpoints one by one (recommended)

   • Full Migration: Switch all endpoints at once

   • Parallel: Run V1 and V2 side by side

Phase 2: Update Path Parameters

Before (V1):

After (V2):

Phase 3: Update Response Handling

Before (V1):

After (V2):

Phase 4: Update Error Handling

V2 has enhanced error responses with more specific error codes:

Phase 5: Testing and Validation

1. Test Core Functionality

   • Create requests using V2 endpoints

   • Verify payment flows work correctly

   • Check response formats match expectations

2. Enhanced Validation Testing

   • Test stricter type checking

   • Verify improved error responses

3. Performance Testing

   • Compare response times between V1 and V2

   • Test with realistic data volumes

Support and Resources

• GitHub Examples: Check the easy-invoice repository for V2 implementation examples

Backward Compatibility

V1 endpoints will continue to work during the migration period. However, we recommend migrating to V2 to access improvements and future features:

• Enhanced security and validation

• Better error handling and debugging

• Improved webhook events

• Access to new features as they are released

V2 is the foundation for all future Request Network API features and improvements.

Payment

Ethereum

Sepolia

Optimism

Arbitrum One

Base

zkSync Era

Gnosis

Polygon

BNB Smart Chain (BSC)

BNB Smart Chain (BSC) Testnet

Celo

Alfajores

Fantom

Tombchain

Core

Avalanche

Fuse

Moonbeam

Ronin

Mantle

NEAR

NEAR Testnet

Storage

Gnosis

Sepolia

Ethereum (Deprecated)

REQ Token and Burn Mechanism

Ethereum

Gnosis

The best way to access Request Network is using the Request Network SDK with a Request Node. In this way, the Request Node operator pays the protocol fee for creating requests and reduces the number of transactions signed by the end user resulting in a better user experience.

The Request Network SDK is split into multiple packages so that Builders can pick and choose the features they need.

SDK Packages

These are the packages that we think would be most commonly used by Builders to build applications.

Component Packages

These packages offer pre-built components for quickly integrating certain Request Network features.

Import the packages

The Request Client library can be imported as ES6 or CommonJS modules.

Internal SDK Packages

This page will introduce the primary operations provided by Request Network’s SDK while using the Web3SignatureProvider to sign requests with a private key stored inside a wallet.

This approach works well for Browser environments with access to a web3 wallet.

Create a request

To create an unencrypted ERC-20 request, first connect to an ethers v5 Provider and Signer or wagmi / viem WalletClient.

Then, construct a Web3SignatureProvider, passing in the ethers Provider or viem WalletClient.

Then, construct a RequestNetwork, passing in the:

• Request Node URL. In this example, we use the Sepolia Request Node Gateway.

• Web3SignatureProvider constructed in the previous step.

Then, prepare the Request creation parameters:

Then, call createRequest() to prepare a Request object.

Finally, call request.waitForConfirmation() to wait until:

• The request contents are persisted in IPFS

• The Content-addressable ID (CID) is stored on-chain

• The resulting on-chain event is indexed by the storage subgraph.

CodeSandBox: Create a request

Pay a request

First, construct a RequestNetwork object and connect it to a Request Node. In this example, we use the Sepolia Request Node Gateway:

Then, retrieve the request and get the request data. Take note of the current request balance, to be used later for payment detection.

Then, construct an ethers v5 Provider and Signer. These allow you to read and write to the chain, respectively.

Then, check that the payer has sufficient funds using hasSufficientFunds()

Then, in the case of an ERC-20 request, check that the payer has granted sufficient approval using hasErc20Approval(). If not, submit an approval transaction using approveErc20. Wait for an appropriate number of block confirmations. On Sepolia or Ethereum, 2 block confirmations should suffice. Other chains may require more.

Finally, pay the request using payRequest()

You can detect that the payment was successful by polling the request and waiting until the request balance is greater than or equal to the expected amount.

CodeSandBox: Create and pay a request and detect a payment

Video: Create and pay a request and detect a payment

Retrieve a user's requests

First, construct a RequestNetwork object and connect it to a Request Node. In this example, we use the Sepolia Request Node Gateway:

Then, call fromIdentity() to get an array of Request objects or fromRequestId() to get a single Request object. This function retrieves the Requests stored in IPFS and queries on-chain events to determine the balances paid so far. Finally, call getData() on each Request to get the request contents.

CodeSandBox: Retrieve a user's requests

Video: Retrieve a user's requests

This page will introduce the primary operations provided by Request Network’s SDK while using the EthereumPrivateKeySignatureProvider to sign requests with a private key that is managed outside of a wallet.

This approach works well for Node.js environments without access to a Web3 wallet.

Repository

Create a request

To create an unencrypted ERC-20 request, first construct an EthereumPrivateKeySignatureProvider with a private key.

Then, first construct a RequestNetwork, passing in the:

• Request Node URL. In this example, we use the Sepolia Request Node Gateway.

• EthereumPrivateKeySignatureProvider constructed in the previous step.

Prepare the Request creation parameters:

Then, call createRequest() to create the request and waitForConfirmation() to wait until the request is persisted in IPFS and the CID hash is stored on-chain.

Altogether it looks like this:

Pay a request / Detect a payment

First, construct a RequestNetwork object and connect it to a Request Node. In this example, we use the Sepolia Request Node Gateway:

Then, retrieve the request and get the request data. Take note of the current request balance, to be used later for payment detection.

Then, construct an ethers v5 Provider and Wallet using a private key. These allow you to read and write to the chain, respectively.

Then, check that the payer has sufficient funds using hasSufficientFunds()

Then, in the case of an ERC-20 request, check that the payer has granted sufficient approval using hasErc20Approval(). If not, submit an approval transaction using approveErc20. Wait for an appropriate number of block confirmations. On Sepolia or Ethereum, 2 block confirmations should suffice. Other chains may require more.

Finally, pay the request using payRequest()

Detect that the payment was successful by polling the request and waiting until the request balance is greater than or equal to the expected amount.

Altogether it looks like this:

Retrieve a user's requests

First, construct a RequestNetwork object and connect it to a Request Node. In this example, we use the Sepolia Request Node Gateway:

Then, call fromIdentity() to get an array of Request objects or fromRequestId() to get a single Request object. This function retrieves the Requests stored in IPFS and queries on-chain events to determine the balances paid so far. Finally, call getData() on each Request to get the request contents.

Altogether it looks like this: