Provision Node Setup

Liquidity providers run a provision node — a small always-on server that Liquidramp calls to execute fiat payouts (via your BaaS/PSP) and crypto transfers (via your EVM wallet). This guide is the low-cost Docker path on a single VM. You do not need this page if you only consume the Partner API (onramp, offramp, swap).

What you need first

KYB-approved provider account in the partner portal
API keys (pk_*, sk_*, enc_*) and your partner reference (liquidramp-client-id) — see Authentication
Provision node source (the Docker-ready liquidramp-node project)
At least one fulfilment rail:
- Fiat: PalmPay, BellBank, Korapay, or Nomba credentials
- Crypto: an EVM wallet private key plus the currencies/networks you will serve
A domain (for example node.yourcompany.com) pointed at the VM

Recommended host

Keep it small. The node is an HTTP process plus outbound API calls.

	Minimum	Comfortable
vCPU	1	1
RAM	1 GB	2 GB
Disk	20 GB SSD	25–40 GB SSD
OS	Ubuntu 24.04 LTS	Ubuntu 24.04 LTS
Monthly (typical)	~US$6–12	~US$12–20

Open only 22 (SSH), 80, and 443. Do not publish the node’s app port (3100) to the internet — terminate TLS on the host and proxy locally.

Production endpoint_url must be HTTPS. Saving the URL in the portal fails unless GET /health on that host returns 200.

1. Create a cheap VM

Pick one of the following. Both are single-server setups — no load balancer, Kubernetes, or managed container service required.

DigitalOcean Droplet

Create a Droplet: Ubuntu 24.04, Regular SSD, 1 vCPU / 2 GB RAM (Basic, ~US$12/mo). The 1 GB plan works for sandbox only.
Add your SSH key. Enable a Reserved IP if you want a stable address across rebuilds.
In your DNS provider, create an A record: node.yourcompany.com → the Droplet (or reserved) IPv4.
SSH in as root (or the user you created).

AWS Lightsail (lightweight AWS)

Lightsail is the low-cost AWS option. A t-family EC2 instance plus ALB is unnecessary for a single node.

In Lightsail, create an instance: OS Only → Ubuntu 24.04, plan $10/mo** (2 GB) or **$ 5/mo (1 GB, sandbox).
Create a static IP and attach it to the instance.
Networking firewall: allow SSH (22), HTTP (80), HTTPS (443).
Point node.yourcompany.com at the static IP.
SSH in with the Lightsail key pair.

2. Harden and install Docker

Run on the VM:

apt-get update && apt-get upgrade -y
apt-get install -y ca-certificates curl ufw

# SSH keys only — disable password logins in /etc/ssh/sshd_config if you have not already

ufw default deny incoming
ufw default allow outgoing
ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

# Docker Engine + Compose plugin
curl -fsSL https://get.docker.com | sh

Confirm:

docker --version
docker compose version

3. Place the node and environment file

Copy the provision node project onto the host (git clone of the repo you were given, or scp -r). Example layout:

/opt/liquidramp-node/
  Dockerfile
  docker-compose.yml   ← you create this (below)
  .env                 ← never commit this

Create /opt/liquidramp-node/docker-compose.yml:

services:
  provision-node:
    build: .
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:3100:3100"
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3100/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))",
        ]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

Binding 127.0.0.1:3100 keeps the app off the public interface. Caddy (next step) is the only public entrypoint. Create /opt/liquidramp-node/.env from the project’s .env.example. Required for every node:

NODE_ENV=production
HOST=0.0.0.0
PORT=3100
LOG_LEVEL=warn
TZ=UTC
HEARTBEAT_INTERVAL_SECS=1800

LIQUIDRAMP_API_BASE_URL=https://vibe-api.liquidramp.com
LIQUIDRAMP_CLIENT_ID=LR-ABC123
LIQUIDRAMP_SECRET_KEY=sk_test_...
LIQUIDRAMP_ENCRYPTION_KEY=enc_test_...

Use https://vibe-api.liquidramp.com with *_test_* keys on test, and https://api.liquidramp.com with *_live_* keys in production. LIQUIDRAMP_API_BASE_URL is the root host (no /v1). The node calls /v1/node-info and /v1/lp/orders/... itself.

Fiat provision (optional)

Set FIAT_CURRENCIES and only the BaaS you actually hold. Providers that are missing credentials are skipped at startup.

FIAT_CURRENCIES=NGN

# PalmPay
PALMPAY_APP_ID=
PALMPAY_MERCHANT_ID=
PALMPAY_ACCOUNT_NO=
PALMPAY_MERCHANT_PRIVATE_KEY=

# BellBank
BELLBANK_CONSUMER_KEY=
BELLBANK_CONSUMER_SECRET=

# Korapay
KORAPAY_ACCOUNT_NAME=
KORAPAY_ACCOUNT_NO=
KORAPAY_SECRET_KEY=

# Nomba
NOMBA_CLIENT_ID=
NOMBA_CLIENT_SECRET=
NOMBA_ACCOUNT_ID=
NOMBA_ACCOUNT_NO=
# NOMBA_SUB_ACCOUNT_ID=

BaaS payment webhooks are registered against the Liquidramp API (/v1/webhooks/baas/...), not against your VM. You do not need extra inbound webhook ports on the node.

Crypto provision (optional)

CRYPTO_CURRENCIES=USDC,USDT
CRYPTO_NETWORKS=BSC,BASE,POLYGON
EVM_WALLET_PRIVATE_KEY=0x...

Optional RPC keys improve reliability: ALCHEMY_API_KEY, INFURA_PROJECT_ID, ANKR_API_KEY, DRPC_API_KEY.

EVM_WALLET_PRIVATE_KEY and BaaS secrets must never be committed or pasted into chat logs. Creating a new Liquidramp key set in the portal revokes the previous set — update .env and recreate the container.

If you use an IP whitelist on the partner profile, add this VM’s egress IPv4 so heartbeat and fulfilment callbacks to the Liquidramp API are not blocked.

4. HTTPS with Caddy

Caddy obtains Let’s Encrypt certificates automatically.

apt-get install -y caddy

/etc/caddy/Caddyfile:

node.yourcompany.com {
    reverse_proxy 127.0.0.1:3100
}

systemctl reload caddy

Wait until DNS has propagated. Then:

cd /opt/liquidramp-node
docker compose up -d --build
curl -sS https://node.yourcompany.com/health

Expected: HTTP 200 with "message": "Healthy" (no HMAC required on /health).

5. Register the URL in the portal

Liquidramp does not discover your node. You must save the public URL.

Open Settings → Node Server in the partner portal.
Enter the URL, for example https://node.yourcompany.com.
- Include https://
- No trailing slash
- Do not append /health or /v1
Save. The platform immediately calls GET {endpoint_url}/health. If that fails, the URL is rejected.
After a successful save, the Node Server page shows status, version, environment, and client ID. Use Refresh to re-fetch GET /node-info.

You cannot create liquidity provisions until endpoint_url is set and the node is reachable.

6. Confirm it is live

Check	How
Health	`curl https://node.yourcompany.com/health` → 200
Portal	Settings → Node Server shows healthy
Heartbeat	Container logs show `Heartbeat sent successfully` (default every 30 minutes)
Outbound	Node can reach `LIQUIDRAMP_API_BASE_URL` (firewall/DNS/whitelist)

Heartbeat payload includes node info, wallet address (if configured), BaaS accounts, and balances. The platform uses that to route orders to you.

Operations

docker compose logs -f for live logs; docker compose restart after .env changes (--force-recreate if env did not pick up).
restart: unless-stopped brings the node back after a reboot.
Keep Ubuntu patched. Prefer SSH keys only.
Rotate Liquidramp and BaaS credentials on a schedule; rotate enc_* together with sk_*.
Alert if /health fails or heartbeat errors persist — an offline node stops receiving assignments.

Troubleshooting

Symptom	Likely cause
Portal save fails / “Node request failed”	DNS not pointing here, Caddy not serving 443, or container not listening on 3100
`401` on `/node-info`	Expected without HMAC. Portal and platform sign with your `enc_*` key. Health is the unsigned check.
Heartbeat fails	Wrong `LIQUIDRAMP_*` keys, API host mismatch (test vs live), or IP whitelist missing this VM
BaaS provider skipped at boot	Missing env vars for that provider — check container logs
Crypto transfers fail	Invalid `EVM_WALLET_PRIVATE_KEY`, empty `CRYPTO_NETWORKS`, or RPC connectivity

Introduction

Getting Started

Quickstarts

Liquidity Providers

Resources

Provision Node Setup

What you need first

Recommended host

1. Create a cheap VM

DigitalOcean Droplet

AWS Lightsail (lightweight AWS)

2. Harden and install Docker

3. Place the node and environment file

Fiat provision (optional)

Crypto provision (optional)

4. HTTPS with Caddy

5. Register the URL in the portal

6. Confirm it is live

Operations

Troubleshooting

​What you need first

​Recommended host

​1. Create a cheap VM

​DigitalOcean Droplet

​AWS Lightsail (lightweight AWS)

​2. Harden and install Docker

​3. Place the node and environment file

​Fiat provision (optional)

​Crypto provision (optional)

​4. HTTPS with Caddy

​5. Register the URL in the portal

​6. Confirm it is live

​Operations

​Troubleshooting

​Related

What you need first

Recommended host

1. Create a cheap VM

DigitalOcean Droplet

AWS Lightsail (lightweight AWS)

2. Harden and install Docker

3. Place the node and environment file

Fiat provision (optional)

Crypto provision (optional)

4. HTTPS with Caddy

5. Register the URL in the portal

6. Confirm it is live

Operations

Troubleshooting

Related