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

# Getting Started

> Quick setup guide to get your Client ID and start building with Request Network

## 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 your Client ID, and making your first payment.

## Quick Setup

**1. Create Account**

Sign up for a free Request Network account at [dashboard.request.network](https://dashboard.request.network)

**2. Get Your Client ID**

Generate your Client ID from the Dashboard

**3. Create Your First Request**

Use the API to create a payment request

**4. Process Payment**

Get payment calldata and execute the transaction

## Account Setup

### Request Dashboard Registration

> [card] Create Your Account
>
> Sign up at [dashboard.request.network](https://dashboard.request.network) to get started. All accounts include:
>
> * Free API access with generous limits
> * API documentation and tools
> * Community support

### Client ID Generation

1. Log in to [Request Dashboard](https://dashboard.request.network)
2. **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.
3. Open **Manage Destination → Client IDs**
4. Click **Generate your first Client ID** (or **Generate New Client ID** if you already have one)
5. Copy and securely store the Client ID

> [!WARNING]
>
> **Security Best Practices**
>
> * Store your Client ID and webhook secret in environment variables
> * Never commit credentials to version control
> * Rotate credentials 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:

```bash theme={null}
mkdir request-api-demo
cd request-api-demo
npm init -y
npm install dotenv
```

Create a `.env` file:

```bash theme={null}
RN_CLIENT_ID=your_client_id_here
RN_API_URL=https://api.request.network/v2
```

`RN_CLIENT_ID` is used server-side only — it's sent as the `x-client-id` header on API requests and should never be exposed in client-side code.

### Create a Payment

Create an `index.js` file:

```javascript theme={null}
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:

```bash theme={null}
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

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

> [!NOTE]
>
> **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. Always verify against the **raw** request body, before it's parsed as JSON — re-serializing the parsed body will produce a different signature and fail verification.

```javascript theme={null}
const crypto = require('crypto');
const express = require('express');

const app = express();
// Capture the raw body alongside JSON parsing so we can verify against
// the exact bytes Request Network signed.
app.use(express.json({
  verify: (req, _res, buf) => {
    req.rawBody = buf;
  }
}));

// 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 against the RAW body (not JSON.stringify(req.body))
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.rawBody)
    .digest('hex');

  const expected = Buffer.from(expectedSignature, 'hex');
  const received = Buffer.from(signature || '', 'hex');
  const isValid = expected.length === received.length &&
    crypto.timingSafeEqual(expected, received);

  if (!isValid) {
    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.partial':
      console.log('Partial payment received...');
      break;
    case 'payment.processing':
      console.log('Payment processing...');
      break;
  }

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

#### Testing Webhooks Locally

Since webhooks can't reach your local server directly, use [ngrok](https://ngrok.com/):

```bash theme={null}
ngrok http 3000
```

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

```bash theme={null}
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`:

```bash theme={null}
RN_WEBHOOK_SECRET=your_webhook_secret_here
```

## Environment Configuration

Set up environment variables for secure credential management:

```bash .env theme={null}
# 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
```

```javascript config.js theme={null}
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:

> [card] [📚 API Features](https://docs.request.network/api-features/create-requests.md)
>
> Learn about different payment types and features

> [card] [🔍 Payment Detection](https://docs.request.network/api-features/payment-detection.md)
>
> Understand how payments are tracked

> [card] [⚡ Integration Tutorial](https://docs.request.network/api-setup/integration-tutorial.md)
>
> Complete tutorial with backend + frontend

## Troubleshooting

### Common Issues

> [accordion] 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

> [accordion] 400 Bad Request
>
> * Check required fields: `payee`, `amount`, `invoiceCurrency`, `paymentCurrency`
> * Ensure `amount` is a string (e.g., "0.1")
> * Verify currency IDs are valid

> [accordion] 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)

> [!TIP]
>
> **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](https://docs.request.network/api-setup/integration-tutorial.md).


## Related topics

- [Supported Chains and Currencies](https://docs.request.network/resources/supported-chains-and-currencies.md)
- [Request Network Docs](https://docs.request.network/use-cases/welcome.md)
- [Quickstart](https://docs.request.network/use-cases/quickstart.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.