> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paycrest.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Setup Guide

> Complete step-by-step guide to become a Paycrest provider and run a provision node

This guide walks you through the complete process of becoming a Paycrest provider, from initial signup to running a production provision node. Follow these steps to start earning from stablecoin-to-fiat transactions.

### Step 1: Signup as a Provider

1. Visit [https://app.paycrest.io](https://app.paycrest.io)
2. Sign up as a **Provider**
3. Complete the registration process

### Step 2: Initiate KYB Process

* Complete the basic in-app Know-Your-Business (KYB) process
* This process can run concurrently with PSP account setup
* KYB approval is required for production access

### Step 3: Register with Payment Service Providers (PSPs)

Your provision node can support multiple payment service providers to ensure reliable transaction processing. The specific PSPs available to you will be shown in your provider dashboard so you can begin PSP account setup in parallel with your KYB process.

#### Obtain Required Credentials

You need two credential groups:

1. **Paycrest Aggregator Credentials** (from your Paycrest dashboard)
   * Go to **Provider Dashboard → Settings → Payout tab → API Keys**
   * Copy:
     * **API Key** -> set as `AGGREGATOR_CLIENT_ID`
     * **API Secret** -> set as `AGGREGATOR_SECRET_KEY`

2. **PSP Credentials** (from each PSP portal)
   * For each PSP you enable, collect the required fields (for example: API key, client secret, client assertion, account ID, base URL, callback URL, webhook secret)
   * Use the dashboard PSP setup page to see the exact environment variable keys to populate
   * Add these values to your node `.env`

### Step 4: Provision Node Setup

Choose your provision node hosting method:

#### Option A: Blockops (Recommended for Low Technical Skills)

* **Cost**: \$10/month
* Simplified setup with Paycrest partnership
* Video setup guide available
* Start here: [https://blockops.network](https://blockops.network)
* After setup, obtain the Host Identifier URL from Blockops
* In the app: **Settings → Payout tab → Configure Provision Node → Host identifier** — paste the URL and click **Update**

Choose this option if you want faster setup with minimal infrastructure management.

#### Option B: Self-Hosted Deployment (Recommended for Developers)

A Paycrest provision node is a backend service hosted on Docker Hub. The deployment process involves pulling the Docker image, configuring environment variables, and starting the server.

**Requirements:**

* Docker installed on your server
* Access to Docker Hub
* Server with internet connectivity
* Minimum 512MB RAM, 1 vCPU (tested on DigitalOcean \$5 droplet)

**Deployment Steps:**

1. **Pull the Docker Image**

```bash theme={null}
docker pull safaria/riverpod:latest
```

2. **Create Environment Configuration**
   Create a `.env` file with your configuration:

```bash theme={null}
# Server Config
DEBUG=False
ALLOWED_HOSTS=* # optional; used for trusted proxy configuration
SERVER_HOST=0.0.0.0 # optional (default: 0.0.0.0)
SERVER_PORT=8000 # optional (default: 8000)
CURRENCIES=KES # single currency
# CURRENCIES=NGN,KES,UGX # multiple currencies must be comma-separated
ENVIRONMENT=production # local, staging, production
SERVER_URL=https://your-server-domain-or-ip
EVM_PRIVATE_KEY= # required for onramp settlements

# Aggregator Config
AGGREGATOR_CLIENT_ID=your_paycrest_api_key # Provider Dashboard → Settings → Payout → API Keys
AGGREGATOR_SECRET_KEY=your_paycrest_api_secret # Provider Dashboard → Settings → Payout → API Keys
AGGREGATOR_BASE_URL=https://api.paycrest.io/v2/provider

# PSP Config - Only configure for PSPs you are using
# Example env prefix (Payaza — names shown in dashboard; availability varies by corridor/currency)
PAYAZA_API_KEY=
PAYAZA_BASE_URL=
PAYAZA_TRANSACTION_PIN=
PAYAZA_SUPPORTS_PAYIN=false
```

> **Credential Mapping**
>
> * `AGGREGATOR_CLIENT_ID` must be your Paycrest **API Key** (Settings → **Payout** → **API Keys**)
> * `AGGREGATOR_SECRET_KEY` must be your Paycrest **API Secret** (Settings → **Payout** → **API Keys**)
> * PSP variables (for example `PAYAZA_*`, `NOMBA_*`) use values issued by each PSP. Prefixes match PSPs listed in the dashboard; availability depends on your corridor and currency.

#### `EVM_PRIVATE_KEY` explained

* **What it is**: The private key for a dedicated EVM wallet (EOA) used by your provision node.
* **When you need it**: Required for onramp-related wallet/authorization flows. If you're running offramp-only operations, you can leave it unset.
* **How to generate it**: Create a new dedicated EVM wallet (do not reuse a personal wallet) and use that wallet's private key.
* **Security**: Treat this as a production secret. Never commit it to git, store it in a secure secret manager or protected `.env`, and rotate it immediately if exposed.

> **Important Notes:**
>
> * One node works for multiple currencies and can support multiple PSPs (for the same currency)
> * Only configure the variables for the PSPs you are using
> * If there is no comment on a credential key that has a value, DO NOT change that value
> * DO NOT change the value of `AGGREGATOR_BASE_URL`
> * The dashboard PSP setup page shows the exact environment variable keys per PSP
> * Retrieve the credential values from each PSP and place them in your `.env`

3. **Start the Service**

```bash theme={null}
docker run -d -p 8000:8000 --env-file .env safaria/riverpod:latest
```

4. **Verify Deployment**
   Check the info endpoint to confirm your node is running and reporting provider metadata:

```bash theme={null}
curl http://your-server-ip:8000/info
```

Expected response:

```json theme={null}
{
  "status": "success",
  "message": "Provider information",
  "data": {
    "serviceInfo": {
      "currencies": ["KES"],
      "totalPSPs": 1,
      "version": "..."
    }
  }
}
```

5. **Configure Host Identifier**

* Take the base URL of your server (e.g., `http://your-server-ip:8000`)
* In the app: **Settings → Payout tab → Configure Provision Node → Host identifier** — paste the URL and save
* Go live on your dashboard

**Benefits:**

* Complete control over infrastructure
* Custom security configurations
* No dependency on third-party services
* Potential cost savings at scale

### Step 5: Configure Trade Settings

#### Set Rates & Limits

**Rates: Choose between:**

* **Floating Rate (Recommended)**: Allows dynamic pricing with a margin
* **Fixed Rate**: Static pricing, less flexible

**Slippage**: It's advised to enable slippage to handle volatility

**Order Limits:**

* Set your minimum limit: Set the minimum amount (in USD) you can fulfill
* Set your maximum limit: Set an amount (in USD) based on the available fiat balance in your PSP account

#### Set Settlement Addresses

**Configure Networks**

* Add settlement addresses for all supported networks and tokens
* You can add a settlement address on multiple networks for flexibility

### Step 6: Node Testing & Launch

#### Testing in Private Mode

* After setting your settlement address(es), test your node in Private mode before going public
* With private mode, you can route a transaction to your node using Noblocks
* To go "LIVE" in Private Mode, switch your node to "Private Mode" on your dashboard

**Test with Noblocks:**
Use the Noblocks testing tool to verify your node in private mode:
`https://noblocks.xyz?provider=YOUR_PROVIDER_ID`
(Replace `YOUR_PROVIDER_ID` with your actual provider ID)

#### Go Live on Public Mode

* Once testing is successful, switch to Public Mode
* Ensure your PSP account is funded and active for transaction fulfillment

## Onboarding Checklist

Use this checklist to track your progress:

| Task                                                                                        | Status |
| ------------------------------------------------------------------------------------------- | ------ |
| Provider Account Created                                                                    | ⬜      |
| KYB Submitted                                                                               | ⬜      |
| PSP Accounts Created                                                                        | ⬜      |
| Paycrest API Key + API Secret copied (for `AGGREGATOR_CLIENT_ID` / `AGGREGATOR_SECRET_KEY`) | ⬜      |
| PSP credentials obtained and added to `.env`                                                | ⬜      |
| Node Deployed (Preferably Blockops)                                                         | ⬜      |
| Trade Settings Configured                                                                   | ⬜      |
| Settlement Addresses Added                                                                  | ⬜      |
| Node Tested in Private Mode                                                                 | ⬜      |
| Switched to Public Mode                                                                     | ⬜      |

## Technical Requirements

### Infrastructure Requirements

**Minimum Requirements:**

* **512MB RAM, 1 vCPU** (tested on DigitalOcean \$5 droplet)
* 50GB+ storage
* Stable internet connection
* Docker installed (for self-hosted deployment)

> **Note:** The minimum requirements are based on real-world testing. A DigitalOcean \$5 droplet (512MB RAM, 1 vCPU, 50GB bandwidth) is sufficient for running a Provision Node in production.

### Docker Installation (For Self-Hosted)

If you choose self-hosted deployment, install Docker on your server:

```bash theme={null}
# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Logout and login again for docker group changes to take effect
# Or run: newgrp docker
```

## Security Best Practices

### Network Security

* Use firewalls to restrict access
* Implement rate limiting
* Enable DDoS protection
* Use VPN for secure access

### Key Management

* Store API keys securely
* Rotate keys regularly
* Use environment variables
* Implement key encryption

### Monitoring and Alerting

* Set up log aggregation
* Configure performance alerts
* Monitor transaction volumes
* Track error rates

## Troubleshooting

### Common Issues

**Node Not Starting**

```bash theme={null}
# Check logs
docker logs <container_name>

# Verify environment variables
docker run --rm --env-file .env safaria/riverpod:latest echo "Environment loaded"

# Restart container
docker restart <container_name>
```

**API Connection Issues**

```bash theme={null}
# Test API connectivity
curl -X GET https://api.paycrest.io/v2/currencies
```

**Database Connection Errors**

```bash theme={null}
# Check container status
docker ps

# Verify environment variables
docker exec <container_name> env | grep DATABASE
```

### Getting Help

* **Documentation**: [docs.paycrest.io](https://docs.paycrest.io)
* **Community**: [Telegram](https://t.me/+Stx-wLOdj49iNDM0)
* **Support**: [support@paycrest.io](mailto:support@paycrest.io)
* **Blockops Support**: Available through Blockops platform

### When to Contact Support

Most providers can complete setup without support. Contact support only if:

* KYB remains pending beyond expected review time
* A required PSP is unavailable for your corridor
* Node status remains offline after valid `hostIdentifier` and `.env` setup
* API keys under **Settings → Payout → API Keys** are missing or cannot be copied/rotated

## Next Steps

After successfully deploying your Provision Node:

1. **Test Transactions**: Process test transactions to verify functionality
2. **Monitor Performance**: Track your node's performance and earnings
3. **Scale Up**: Consider deploying additional nodes for increased capacity
4. **Optimize**: Fine-tune pricing and configuration based on market conditions

For detailed API documentation and advanced configuration options, see the [API Reference](/api-reference/introduction).