Installation

Choose the setup path that fits your workflow:

Option 1: Setup Wizard Recommended

create-offer-hub-orchestrator is a one-command interactive setup wizard. It configures your .env, runs database migrations, and bootstraps the platform user — so you can skip the manual steps entirely. For a full breakdown of each prompt, generated environment files, and the platform bootstrap step, see the Scaffolder Guide.

Step 1 — Clone and install

Step 2 — Run the setup wizard

The wizard prompts for:

The wizard then automatically:

1. Generates a secure OFFERHUB_MASTER_KEY
2. Generates a secure WALLET_ENCRYPTION_KEY (crypto mode)
3. Writes .env with all values filled in
4. Runs prisma migrate deploy
5. Runs npm run bootstrap — creates the platform Stellar wallet and writes PLATFORM_USER_ID into .env

Step 3 — Start the API

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

Step 4 — Verify installation

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

Option 2: Full Local Setup

Use this path when you need full manual control — custom Docker networks, CI/CD pipelines, or environments where running an interactive wizard isn't appropriate.

Prerequisites

• 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)

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 3: 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.

Creating Your First API Key

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

Option A: Using the CLI (Recommended)

The @offerhub/cli is the fastest way to create an API key:

This runs an interactive wizard that prompts for scopes and key name. See the CLI Guide for all available commands.

Option B: Using curl

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:

{
  "id": "key_abc123",
  "api_key": "ohk_live_xxxxxxxxxxxx",
  "name": "My Marketplace",
  "scopes": ["read", "write"],
  "created_at": "2026-01-12T10:00:00.000Z"
}

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

• Scaffolder Guide — In-depth reference for create-offer-hub-orchestrator
• Configuration — Learn about all environment variables
• Quick Start — Create your first user and order
• CLI Guide — Manage API keys and configuration
• API Reference — Explore all endpoints
• SDK Guide — Integrate using TypeScript