Getting Started

Welcome to Request Network

Get started with Request Network in just a few minutes. This guide will walk you through setting up your account, obtaining API keys, and making your first payment.

Quick Setup

Create Account

Get API Keys

Generate your Client ID from the Dashboard

Create Your First Request

Use the API to create a payment request

Process Payment

Get payment calldata and execute the transaction

Account Setup

Request Dashboard Registration

Create Your Account

Free API access with generous limits
API documentation and tools
Community support

Client ID Generation

Log in to Request Dashboard
Create a payment destination first if you haven’t — the Client IDs section is only available once a destination exists. From the Home page, click Set up payment destination and pick the chain + token you want to receive on.
Open Manage Destination → Client IDs
Click Generate your first Client ID (or Generate New Client ID if you already have one)
Copy and securely store the Client ID

Security Best Practices

Store API keys in environment variables
Never commit keys to version control
Rotate keys regularly

Your First Integration

Let’s create a simple Node.js server that integrates with the Request Network API to create payments and track their status.

Project Setup

Create a new project and install dependencies:

mkdir request-api-demo
cd request-api-demo
npm init -y
npm install dotenv

Create a .env file:

RN_CLIENT_ID=your_client_id_here
RN_API_URL=https://api.request.network/v2

Create a Payment

Create an index.js file:

require('dotenv').config();

async function createPayment() {
  try {
    const response = await fetch(`${process.env.RN_API_URL}/payouts`, {
      method: 'POST',
      headers: {
        'x-client-id': process.env.RN_CLIENT_ID,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        payee: '0x...', // Your wallet address
        amount: '0.1',
        invoiceCurrency: 'ETH-sepolia-sepolia',
        paymentCurrency: 'ETH-sepolia-sepolia'
      })
    });

    if (!response.ok) {
      const errorText = await response.text();
      console.error('API Error:', errorText);
      return;
    }

    const data = await response.json();
    console.log('Payment created:', {
      requestId: data.requestId,
      paymentReference: data.paymentReference,
      transactions: data.transactions,
      metadata: data.metadata
    });
    
    return data;
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

createPayment();

Run it:

node index.js

The response will include:

requestId — Unique identifier for the request
paymentReference — Used to track the payment
transactions — Array of transaction calldata to execute
metadata — Additional info like stepsRequired and needsApproval

Understanding the Response

{
  "requestId": "011d9f76e07a678b8321ccfaa300efd4d80832652b8bbc07ea4069ca71006210b5",
  "paymentReference": "0xe23a6b02059c2b30",
  "transactions": [
    {
      "data": "0xb868980b000000000000000000000000...",
      "to": "0xe11BF2fDA23bF0A98365e1A4c04A87C9339e8687",
      "value": {
        "type": "BigNumber",
        "hex": "0x02c68af0bb140000"
      }
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "paymentTransactionIndex": 0
  }
}

Note: The amount is in human-readable format. No BigNumber conversions needed!

Setting Up Webhooks

To track payment status in real-time, set up a webhook endpoint:

const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.json());

// Webhook handler
app.post('/webhooks', async (req, res) => {
  const signature = req.headers['x-request-network-signature'];
  const webhookSecret = process.env.RN_WEBHOOK_SECRET;

  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send({ error: 'Invalid signature' });
  }

  const { requestId, event } = req.body;
  console.log(`Webhook: ${event} for request ${requestId}`);
  
  // Handle different events
  switch (event) {
    case 'payment.confirmed':
      console.log('Payment confirmed!');
      // Update your database, send email, etc.
      break;
    case 'payment.pending':
      console.log('Payment pending...');
      break;
  }

  res.send({ code: 200, message: 'Webhook received' });
});

Testing Webhooks Locally

Since webhooks can’t reach your local server directly, use ngrok:

ngrok http 3000

Copy the HTTPS URL (e.g., https://abc123.ngrok.io/webhooks) and register it via the Auth API:

curl -X POST "https://auth.request.network/v1/webhook" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $RN_CLIENT_ID" \
  -d '{ "url": "https://abc123.ngrok.io/webhooks" }'

The response includes a one-time secret — copy it to your .env:

RN_WEBHOOK_SECRET=your_webhook_secret_here

Environment Configuration

Set up environment variables for secure API key management:

# Request Network Configuration
RN_CLIENT_ID=your_client_id_here
RN_API_URL=https://api.request.network/v2

# Webhook Configuration (optional)
RN_WEBHOOK_SECRET=your_webhook_secret_here

module.exports = {
  requestNetwork: {
    clientId: process.env.RN_CLIENT_ID,
    apiUrl: process.env.RN_API_URL || 'https://api.request.network/v2',
    webhookSecret: process.env.RN_WEBHOOK_SECRET,
  }
};

What’s Next?

Now that you’ve made your first API call, explore more features:

📚 API Features

Learn about different payment types and features

🔍 Payment Detection

Understand how payments are tracked

⚡ Integration Tutorial

Complete tutorial with backend + frontend

Troubleshooting

Common Issues

401 Unauthorized

Verify Client ID is correct
Check that you’re using the right header: x-client-id
Ensure the Client ID hasn’t been revoked

400 Bad Request

Check required fields: payee, amount, invoiceCurrency, paymentCurrency
Ensure amount is a string (e.g., “0.1”)
Verify currency IDs are valid

Webhook not receiving events

Verify webhook URL is publicly accessible
Check webhook signature verification
Ensure the webhook is active (toggle via PUT /v1/webhook/:id on the Auth API)

You’re all set! You’ve created your first payment request with Request Network. For a complete working example with frontend, check out the Integration Tutorial.

🔑 API Setup

⚙️ API Features

📚 API Reference

Welcome to Request Network

Quick Setup

Account Setup

Request Dashboard Registration

Create Your Account

Client ID Generation

Your First Integration

Project Setup

Create a Payment

Understanding the Response

Setting Up Webhooks

Testing Webhooks Locally

Environment Configuration

What’s Next?

📚 API Features

🔍 Payment Detection

⚡ Integration Tutorial

Troubleshooting

Common Issues

​Welcome to Request Network

​Quick Setup

​Account Setup

​Request Dashboard Registration

Create Your Account

​Client ID Generation

​Your First Integration

​Project Setup

​Create a Payment

​Understanding the Response

​Setting Up Webhooks

​Testing Webhooks Locally

​Environment Configuration

​What’s Next?

📚 API Features

🔍 Payment Detection

⚡ Integration Tutorial

​Troubleshooting

​Common Issues

Welcome to Request Network

Quick Setup

Account Setup

Request Dashboard Registration

Client ID Generation

Your First Integration

Project Setup

Create a Payment

Understanding the Response

Setting Up Webhooks

Testing Webhooks Locally

Environment Configuration

What’s Next?

Troubleshooting

Common Issues