Installation

This guide walks you through setting up the OFFER-HUB Orchestrator for local development. You can also use the SDK without running your own instance - see Using the SDK below.

Prerequisites

Before you begin, make sure you have:

• Node.js v20 or later (nodejs.org)
• npm v10 or later
• Docker and Docker Compose (for PostgreSQL and Redis)
• A Trustless Work API key (for escrow)

Option 1: Full Local Setup

Step 1 - Clone the Repository

Step 2 - Install Dependencies

Step 3 - Start Infrastructure

Start PostgreSQL and Redis using Docker Compose:

This starts:

• PostgreSQL on port 5432
• Redis on port 6379

Step 4 - Configure Environment

Copy the example environment file:

Edit .env with your values. The minimum required variables for local development:

# Server
NODE_ENV=development
PORT=4000

# Database (Docker defaults)
DATABASE_URL=postgresql://offerhub:offerhub_password@localhost:5432/offerhub_db
DIRECT_URL=postgresql://offerhub:offerhub_password@localhost:5432/offerhub_db

# Redis (Docker default)
REDIS_URL=redis://localhost:6379

# Payment Provider
PAYMENT_PROVIDER=crypto
WALLET_ENCRYPTION_KEY=your-32-byte-hex-key

# Master Key (for creating API keys)
OFFERHUB_MASTER_KEY=your-secure-master-key

# Trustless Work (get from trustlesswork.com)
TRUSTLESS_API_KEY=your_trustless_api_key
TRUSTLESS_API_URL=https://dev.api.trustlesswork.com

# Stellar (testnet defaults)
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_USDC_ASSET_CODE=USDC
STELLAR_USDC_ISSUER=GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5

Step 5 - Run Database Migrations

Generate the Prisma client and apply migrations:

Step 6 - Bootstrap Platform User

Create the internal platform user required for escrow operations:

Step 7 - Start the API

The API starts on http://localhost:4000.

Step 8 - Verify Installation

Test that everything is working:

You should see:

{
  "status": "healthy",
  "timestamp": "2026-02-25T12:00:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

Option 2: Using the SDK Only

If you want to integrate with an existing OFFER-HUB Orchestrator instance (hosted by you or a partner), you only need the SDK:

Then configure it in your code:

import { OfferHubSDK } from '@offerhub/sdk';

const sdk = new OfferHubSDK({
  apiUrl: 'https://your-orchestrator-url.com',
  apiKey: 'ohk_live_your_api_key'
});

// Create a user
const user = await sdk.users.create({
  externalUserId: 'user-123',
  email: 'buyer@example.com'
});

See the SDK Guide for complete documentation.

Option 3: Using npm create (Coming Soon)

Creating Your First API Key

Once the server is running, create an API key using your master key:

curl -X POST http://localhost:4000/api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_OFFERHUB_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Marketplace", "scopes": ["read", "write"]}'

Response:

{
  "data": {
    "id": "key_abc123",
    "key": "ohk_live_xxxxxxxxxxxx",
    "name": "My Marketplace",
    "scopes": ["read", "write"]
  }
}

Troubleshooting

Database Connection Failed

Make sure Docker is running and the containers are up:

If containers aren't running, start them:

Prisma Migration Errors

If you see migration errors, try resetting the database:

Port Already in Use

If port 4000 is already in use, change the PORT in your .env file or stop the conflicting service.

Next Steps

• Configuration - Learn about all environment variables
• Quick Start - Create your first user and order
• API Reference - Explore all endpoints
• SDK Guide - Integrate using TypeScript