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

## Quick Setup

<Steps>
  <Step title="Create Account">
    Sign up for a free Request Network account at [dashboard.request.network](https://dashboard.request.network)
  </Step>

  <Step title="Get API Keys">
    Generate your Client ID from the Dashboard
  </Step>

  <Step title="Create Your First Request">
    Use the API to create a payment request
  </Step>

  <Step title="Process Payment">
    Get payment calldata and execute the transaction
  </Step>
</Steps>

## Account Setup

### Request Dashboard Registration

<Card title="Create Your Account" icon="user">
  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
</Card>

### 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 API keys in environment variables
  * Never commit keys to version control
  * Rotate keys regularly
</Warning>

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

### 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
  }
}
```

<Info>
  **Note:** The `amount` is in human-readable format. No BigNumber conversions needed!
</Info>

### Setting Up Webhooks

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

```javascript theme={null}
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](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 API key management:

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

## What's Next?

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

<CardGroup cols={3}>
  <Card title="📚 API Features" href="/api-features/create-requests" icon="book">
    Learn about different payment types and features
  </Card>

  <Card title="🔍 Payment Detection" href="/api-features/payment-detection" icon="radar">
    Understand how payments are tracked
  </Card>

  <Card title="⚡ Integration Tutorial" href="/api-setup/integration-tutorial" icon="graduation-cap">
    Complete tutorial with backend + frontend
  </Card>
</CardGroup>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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)
  </Accordion>
</AccordionGroup>

<Check>
  **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/integration-tutorial).
</Check>