Getting Started

Learn how OFFER-HUB works and how to integrate it into your marketplace in minutes.

OFFER-HUB Orchestrator is a self-hosted payments and escrow backend for service marketplaces. It handles the financial plumbing — escrow, balance management, dispute resolution, and USDC transactions on Stellar — so you can focus on building your marketplace product.

Overview

OFFER-HUB solves the hardest problems in marketplace payments:

Challenge	Orchestrator Solution
Holding buyer funds securely	Non-custodial escrow via Trustless Work smart contracts
Preventing double-spending	Atomic balance operations + idempotency keys
Handling "seller didn't deliver"	Built-in dispute workflow with SPLIT resolution
Managing crypto wallets for non-crypto users	Invisible Stellar wallets (Web2 UX)
Tracking payment state	State machine with full audit log
Real-time notifications	SSE event stream

Tip

Without the Orchestrator, building all of this could take 6-12 months. With it, you can integrate in a few days.

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Purpose
Node.js	18+	Runtime environment
npm or pnpm	Latest	Package management
PostgreSQL	14+	Database
Redis	6+	Caching and queues
Git	Latest	Version control

You'll also need:

A Stellar testnet account (for development)
Basic familiarity with REST APIs
A marketplace application to integrate with

Note

For production, you'll need a Stellar mainnet account with USDC trustline and a Trustless Work API key.

Installation

Clone the Repository

git clone https://github.com/OFFER-HUB/offer-hub-monorepo.git

cd offer-hub-monorepo

Install Dependencies

npm install

Set Up the Database

Create a PostgreSQL database:

createdb offerhub_dev

Run migrations:

npm run db:migrate

Start the Development Server

npm run dev

The API will be available at http://localhost:4000.

Tip

Run npm run dev:watch for auto-reload during development.

Configuration

Create a .env file in the project root:

bash

# Database
DATABASE_URL=postgresql://localhost:5432/offerhub_dev

# Redis
REDIS_URL=redis://localhost:6379

# Stellar Network
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

# Trustless Work (Escrow Provider)
TRUSTLESS_WORK_API_URL=https://api.trustlesswork.com
TRUSTLESS_WORK_SECRET=your_secret_here

# API Security
OFFERHUB_MASTER_KEY=your_master_key_here
JWT_SECRET=your_jwt_secret_here

# Payment Provider (crypto or airtm)
PAYMENT_PROVIDER=crypto

Key Configuration Options

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`REDIS_URL`	Yes	Redis connection string
`STELLAR_NETWORK`	Yes	`testnet` or `mainnet`
`TRUSTLESS_WORK_SECRET`	Yes	API key for escrow contracts
`OFFERHUB_MASTER_KEY`	Yes	Master key for creating API keys
`PAYMENT_PROVIDER`	No	`crypto` (default) or `airtm`

Warning

Never commit your .env file to version control. Add it to .gitignore.

See Configuration for the complete list of environment variables.

Your First Escrow

Let's walk through creating your first escrow transaction.

1. Create an API Key

First, generate an API key using your master key:

bash

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

Save the returned key value — it's only shown once.

2. Create Users

Create a buyer and seller:

bash

# Create buyer
curl -X POST http://localhost:4000/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "buyer_123", "email": "buyer@example.com"}'

# Create seller
curl -X POST http://localhost:4000/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "seller_456", "email": "seller@example.com"}'

3. Fund the Buyer's Account

Get the buyer's deposit address:

bash

curl -X GET http://localhost:4000/api/v1/users/buyer_123/wallet/deposit \
  -H "Authorization: Bearer YOUR_API_KEY"

Send testnet USDC to the returned address. The balance will update automatically.

4. Create an Order

bash

curl -X POST http://localhost:4000/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-001" \
  -d '{
    "buyer_id": "buyer_123",
    "seller_id": "seller_456",
    "amount": "100.00",
    "currency": "USD",
    "description": "Website development project"
  }'

5. Fund the Escrow

Reserve the buyer's funds in escrow:

bash

curl -X POST http://localhost:4000/api/v1/orders/ORDER_ID/escrow/fund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: fund-001"

The funds are now locked in a smart contract on Stellar.

6. Release to Seller

When the work is complete, release the funds:

bash

curl -X POST http://localhost:4000/api/v1/orders/ORDER_ID/resolution/release \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: release-001"

The seller's balance is now credited with the payment amount.

Tip

Use the same Idempotency-Key if you need to retry a request. The Orchestrator will return the cached response instead of processing a duplicate.

TypeScript Example

Here's the same flow using the TypeScript SDK:

import { OfferHubClient } from '@offer-hub/sdk';

const client = new OfferHubClient({
  baseUrl: 'http://localhost:4000',
  apiKey: 'YOUR_API_KEY',
});

// Create an order
const order = await client.orders.create({
  buyerId: 'buyer_123',
  sellerId: 'seller_456',
  amount: '100.00',
  currency: 'USD',
  description: 'Website development project',
});

// Fund the escrow
await client.orders.fundEscrow(order.id);

// Release to seller when complete
await client.orders.release(order.id);

Next Steps

Now that you've completed your first escrow, explore these guides:

Orchestrator Guide — Deep dive into the Orchestrator architecture
Escrow Flows — Learn about escrow states and transitions
Orders Guide — Complete order lifecycle documentation
Disputes — Handle disputes and resolutions
API Reference — Full REST API documentation
SDK Quick Start — Use the TypeScript SDK

Note

Need help? Join our Discord community or open an issue on GitHub.

Edit this page on GitHub

Getting Started

Learn how OFFER-HUB works and how to integrate it into your marketplace in minutes.

Overview

OFFER-HUB solves the hardest problems in marketplace payments:

Challenge	Orchestrator Solution
Holding buyer funds securely	Non-custodial escrow via Trustless Work smart contracts
Preventing double-spending	Atomic balance operations + idempotency keys
Handling "seller didn't deliver"	Built-in dispute workflow with SPLIT resolution
Managing crypto wallets for non-crypto users	Invisible Stellar wallets (Web2 UX)
Tracking payment state	State machine with full audit log
Real-time notifications	SSE event stream

Tip

Without the Orchestrator, building all of this could take 6-12 months. With it, you can integrate in a few days.

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Purpose
Node.js	18+	Runtime environment
npm or pnpm	Latest	Package management
PostgreSQL	14+	Database
Redis	6+	Caching and queues
Git	Latest	Version control

You'll also need:

A Stellar testnet account (for development)
Basic familiarity with REST APIs
A marketplace application to integrate with

Note

For production, you'll need a Stellar mainnet account with USDC trustline and a Trustless Work API key.

Installation

Clone the Repository

git clone https://github.com/OFFER-HUB/offer-hub-monorepo.git

cd offer-hub-monorepo

Install Dependencies

npm install

Set Up the Database

Create a PostgreSQL database:

createdb offerhub_dev

Run migrations:

npm run db:migrate

Start the Development Server

npm run dev

The API will be available at http://localhost:4000.

Tip

Run npm run dev:watch for auto-reload during development.

Configuration

Create a .env file in the project root:

bash

# Database
DATABASE_URL=postgresql://localhost:5432/offerhub_dev

# Redis
REDIS_URL=redis://localhost:6379

# Stellar Network
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

# Trustless Work (Escrow Provider)
TRUSTLESS_WORK_API_URL=https://api.trustlesswork.com
TRUSTLESS_WORK_SECRET=your_secret_here

# API Security
OFFERHUB_MASTER_KEY=your_master_key_here
JWT_SECRET=your_jwt_secret_here

# Payment Provider (crypto or airtm)
PAYMENT_PROVIDER=crypto

Key Configuration Options

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`REDIS_URL`	Yes	Redis connection string
`STELLAR_NETWORK`	Yes	`testnet` or `mainnet`
`TRUSTLESS_WORK_SECRET`	Yes	API key for escrow contracts
`OFFERHUB_MASTER_KEY`	Yes	Master key for creating API keys
`PAYMENT_PROVIDER`	No	`crypto` (default) or `airtm`

Warning

Never commit your .env file to version control. Add it to .gitignore.

See Configuration for the complete list of environment variables.

Your First Escrow

Let's walk through creating your first escrow transaction.

1. Create an API Key

First, generate an API key using your master key:

bash

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

Save the returned key value — it's only shown once.

2. Create Users

Create a buyer and seller:

bash

# Create buyer
curl -X POST http://localhost:4000/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "buyer_123", "email": "buyer@example.com"}'

# Create seller
curl -X POST http://localhost:4000/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "seller_456", "email": "seller@example.com"}'

3. Fund the Buyer's Account

Get the buyer's deposit address:

bash

curl -X GET http://localhost:4000/api/v1/users/buyer_123/wallet/deposit \
  -H "Authorization: Bearer YOUR_API_KEY"

Send testnet USDC to the returned address. The balance will update automatically.

4. Create an Order

bash

curl -X POST http://localhost:4000/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-001" \
  -d '{
    "buyer_id": "buyer_123",
    "seller_id": "seller_456",
    "amount": "100.00",
    "currency": "USD",
    "description": "Website development project"
  }'

5. Fund the Escrow

Reserve the buyer's funds in escrow:

bash

curl -X POST http://localhost:4000/api/v1/orders/ORDER_ID/escrow/fund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: fund-001"

The funds are now locked in a smart contract on Stellar.

6. Release to Seller

When the work is complete, release the funds:

bash

curl -X POST http://localhost:4000/api/v1/orders/ORDER_ID/resolution/release \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: release-001"

The seller's balance is now credited with the payment amount.

Tip

Use the same Idempotency-Key if you need to retry a request. The Orchestrator will return the cached response instead of processing a duplicate.

TypeScript Example

Here's the same flow using the TypeScript SDK:

import { OfferHubClient } from '@offer-hub/sdk';

const client = new OfferHubClient({
  baseUrl: 'http://localhost:4000',
  apiKey: 'YOUR_API_KEY',
});

// Create an order
const order = await client.orders.create({
  buyerId: 'buyer_123',
  sellerId: 'seller_456',
  amount: '100.00',
  currency: 'USD',
  description: 'Website development project',
});

// Fund the escrow
await client.orders.fundEscrow(order.id);

// Release to seller when complete
await client.orders.release(order.id);

Next Steps

Now that you've completed your first escrow, explore these guides:

Orchestrator Guide — Deep dive into the Orchestrator architecture
Escrow Flows — Learn about escrow states and transitions
Orders Guide — Complete order lifecycle documentation
Disputes — Handle disputes and resolutions
API Reference — Full REST API documentation
SDK Quick Start — Use the TypeScript SDK

Note

Need help? Join our Discord community or open an issue on GitHub.

Edit this page on GitHub