Build Your First Marketplace

# 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
REDIS_URL=redis://localhost:6379

# Payment mode — crypto uses Stellar USDC directly
PAYMENT_PROVIDER=crypto

# Generate with: openssl rand -hex 32
WALLET_ENCRYPTION_KEY=your-32-byte-hex-key

# Choose any secret for local dev
OFFERHUB_MASTER_KEY=dev-master-key-change-in-production

# Get from trustlesswork.com (testnet key)
TRUSTLESS_API_KEY=your_trustless_testnet_key
TRUSTLESS_API_URL=https://dev.api.trustlesswork.com

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

{
  "status": "healthy",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

curl -X POST http://localhost:4000/api/v1/auth/api-keys \
  -H "Authorization: Bearer dev-master-key-change-in-production" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-marketplace", "scopes": ["read", "write"]}'

OFFERHUB_API_URL=http://localhost:4000
OFFERHUB_API_KEY=ohk_live_your_api_key_here

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

export const sdk = new OfferHubSDK({
  apiUrl: process.env.OFFERHUB_API_URL!,
  apiKey: process.env.OFFERHUB_API_KEY!,
});

import 'dotenv/config';
import { sdk } from './sdk.js';

async function signup() {
  // Register the buyer
  const buyer = await sdk.users.create({
    externalUserId: 'marketplace-user-buyer-001',
    email: 'alice@example.com',
    type: 'BUYER',
  });
  console.log('Buyer created:', buyer.id);

  // Register the seller
  const seller = await sdk.users.create({
    externalUserId: 'marketplace-user-seller-001',
    email: 'bob@example.com',
    type: 'SELLER',
  });
  console.log('Seller created:', seller.id);

  // Check initial balances
  const buyerBalance = await sdk.balance.get(buyer.id);
  console.log('Buyer balance:', buyerBalance);
  // → { available: "0.00", reserved: "0.00", currency: "USD" }

  // Get buyer's deposit address
  const depositInfo = await sdk.wallet.getDepositAddress(buyer.id);
  console.log('Buyer deposit address:', depositInfo.address);

  return { buyer, seller };
}

signup().catch(console.error);

import 'dotenv/config';
import { sdk } from './sdk.js';

async function showDepositAddress(userId: string) {
  const info = await sdk.wallet.getDepositAddress(userId);

  console.log('─────────────────────────────────────────');
  console.log('Send USDC to fund this account:');
  console.log('  Network :', info.network);    // testnet
  console.log('  Asset   :', info.asset.code); // USDC
  console.log('  Address :', info.address);    // G...
  console.log('─────────────────────────────────────────');
  console.log('Use Stellar Friendbot to get test USDC:');
  console.log(`  https://friendbot.stellar.org?addr=${info.address}`);

  return info;
}

// Replace with your actual buyer ID from Part 3
showDepositAddress('usr_buyer123').catch(console.error);

const balance = await sdk.balance.get('usr_buyer123');
console.log('Available:', balance.available); // e.g., "100.00"
console.log('Reserved:', balance.reserved);   // "0.00"

import 'dotenv/config';
import { sdk } from './sdk.js';

// Your marketplace owns the listing data
const listing = {
  id: 'listing-001',
  title: 'Logo Design — Startup Package',
  description: 'Professional logo design with 3 concepts, 2 revision rounds',
  price: '75.00',
  currency: 'USD',
  sellerId: 'usr_seller456', // from Part 3
};

async function checkout(buyerId: string) {
  // Step 1: Check buyer has enough funds
  const balance = await sdk.balance.get(buyerId);
  if (parseFloat(balance.available) < parseFloat(listing.price)) {
    throw new Error(
      `Insufficient balance: have ${balance.available}, need ${listing.price}`
    );
  }

  // Step 2: Create the order
  const order = await sdk.orders.create({
    buyerId,
    sellerId: listing.sellerId,
    amount: listing.price,
    currency: listing.currency,
    title: listing.title,
    description: listing.description,
  });
  console.log('Order created:', order.id, '| Status:', order.status);
  // → ORDER_CREATED

  // Step 3: Reserve the buyer's funds
  await sdk.orders.reserve(order.id);
  console.log('Funds reserved for order:', order.id);

  // Verify the balance change
  const updatedBalance = await sdk.balance.get(buyerId);
  console.log('Available after reserve:', updatedBalance.available);
  // decreased by listing.price
  console.log('Reserved after reserve:', updatedBalance.reserved);
  // increased by listing.price

  return order;
}

// Replace with your actual buyer ID from Part 3
checkout('usr_buyer123').catch(console.error);

import 'dotenv/config';
import { sdk } from './sdk.js';

async function fundEscrow(orderId: string) {
  // Step 1: Deploy the Soroban smart contract
  await sdk.orders.createEscrow(orderId);
  console.log('Deploying escrow contract for order:', orderId);

  // Step 2: Wait for contract deployment (async on-chain)
  await sdk.orders.waitForStatus(orderId, 'ESCROW_CREATED');
  console.log('Contract deployed. Status: ESCROW_CREATED');

  // Step 3: Transfer USDC from buyer's wallet into the contract
  await sdk.orders.fundEscrow(orderId);
  console.log('Funding escrow...');

  // Step 4: Wait for on-chain confirmation (3–10 seconds on testnet)
  await sdk.orders.waitForStatus(orderId, 'IN_PROGRESS');
  console.log('Escrow funded! Order is now IN_PROGRESS');
  console.log('Funds are non-custodially held in the Soroban contract.');
}

// Replace with your actual order ID from Part 5
fundEscrow('ord_xyz789').catch(console.error);

import 'dotenv/config';
import { sdk } from './sdk.js';

async function releaseToSeller(orderId: string, buyerId: string, sellerId: string) {
  // Buyer approves the completed work
  await sdk.orders.release(orderId, "Buyer approved the order");
  console.log('Release initiated...');

  // Wait for settlement
  await sdk.orders.waitForStatus(orderId, 'CLOSED');
  console.log('Order CLOSED. Funds released to seller.');

  // Seller can now see their updated balance
  const sellerBalance = await sdk.balance.get(sellerId);
  console.log('Seller available balance:', sellerBalance.available);
  // Increased by the order amount

  // Seller can withdraw to any Stellar address
  const withdrawal = await sdk.withdrawals.create({
    userId: sellerId,
    amount: '75.00',
    destinationAddress: 'GXXXXXXXX...', // seller's external wallet
  });
  console.log('Withdrawal requested:', withdrawal.id);
}

// Replace with your actual IDs from previous steps
releaseToSeller('ord_xyz789', 'usr_buyer123', 'usr_seller456').catch(console.error);

import 'dotenv/config';
import { sdk } from './sdk.js';

async function handleDispute(
  orderId: string,
  buyerId: string,
  orderAmount: string
) {
  // Step 1: Buyer opens a dispute (must be IN_PROGRESS)
  await sdk.disputes.open(orderId, {
    reason: 'Delivered work does not match agreed specifications',
    evidence: [],
  });
  console.log('Dispute opened. Funds frozen in contract.');

  // Step 2: Platform fetches the dispute record
  const disputes = await sdk.disputes.list({ orderId });
  const dispute = disputes[0];
  console.log('Dispute ID:', dispute.id);

  // Step 3: Platform reviews evidence and resolves
  // Option A: Refund the buyer
  await sdk.disputes.resolve(dispute.id, {
  decision: 'FULL_REFUND',
  releaseAmount: '0.00',
  refundAmount: orderAmount,
  note: 'Verified: deliverables did not meet specification',
  });

  // Option B (alternative): Release to seller
  // await sdk.disputes.resolve(dispute.id, {
  //   decision: 'FULL_RELEASE',
  //   releaseAmount: orderAmount,
  //   refundAmount: '0.00',
  //   note: 'Verified: work was delivered as agreed',
  // });

  await sdk.orders.waitForStatus(orderId, 'REFUNDED');
  console.log('Order REFUNDED. Buyer balance credited.');

  const buyerBalance = await sdk.balance.get(buyerId);
  console.log('Buyer available balance (after refund):', buyerBalance.available);
}

// Replace with your actual IDs
handleDispute('ord_xyz789', 'usr_buyer123', '75.00').catch(console.error);

import 'dotenv/config';

// OFFER-HUB emits Server-Sent Events at GET /api/v1/events
// Standard EventSource works in Node 18+ and all modern browsers.
const EVENTS_URL = `${process.env.OFFERHUB_API_URL}/api/v1/events`;
const API_KEY = process.env.OFFERHUB_API_KEY!;

// Node.js EventSource (install eventsource package if needed)
// In a browser you'd use new EventSource(url) directly.
const { EventSource } = await import('eventsource');

const es = new EventSource(EVENTS_URL, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

es.onopen = () => {
  console.log('Connected to OFFER-HUB event stream');
};

es.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.eventType) {
    case 'balance.credited':
      console.log(`💰 Balance credited: +${data.payload.amount} USDC for user ${data.payload.userId}`);
      break;
    case 'order.escrow_funded':
      console.log(`🔒 Escrow funded: order ${data.payload.orderId} is now IN_PROGRESS`);
      break;
    case 'order.released':
      console.log(`✅ Funds released: order ${data.payload.orderId} CLOSED`);
      break;
    case 'order.disputed':
      console.log(`⚠️ Dispute opened: order ${data.payload.orderId}`);
      break;
    case 'order.refunded':
      console.log(`↩️ Refund processed: order ${data.payload.orderId}`);
      break;
    default:
      console.log(`Event: ${data.eventType}`, data.payload);
  }
};

es.onerror = (err) => {
  console.error('Event stream error:', err);
};

// Keep alive — press Ctrl+C to stop
console.log('Listening for events. Press Ctrl+C to stop.');

import 'dotenv/config';
import { sdk } from './sdk.js';

async function fullDemoFlow() {
  console.log('\n=== OFFER-HUB Marketplace Demo ===\n');

  // 1. Register participants
  const buyer = await sdk.users.create({
    externalUserId: `demo-buyer-${Date.now()}`,
    email: 'alice@demo.com',
    type: 'BUYER',
  });
  const seller = await sdk.users.create({
    externalUserId: `demo-seller-${Date.now()}`,
    email: 'bob@demo.com',
    type: 'SELLER',
  });
  console.log('✓ Buyer:', buyer.id);
  console.log('✓ Seller:', seller.id);

  // 2. Get buyer deposit address (fund manually via Friendbot on testnet)
  const deposit = await sdk.wallet.getDepositAddress(buyer.id);
  console.log('\nFund the buyer via Friendbot:');
  console.log(`  https://friendbot.stellar.org?addr=${deposit.address}`);
  console.log('\nPress Ctrl+C and re-run after funding, or use a pre-funded testnet account.\n');

  // ⚠️ In a real hackathon demo, fund the buyer first, then continue.
  // For a fully automated demo, inject a pre-funded externalUserId here.

  // 3. Place an order
  const order = await sdk.orders.create({
    buyerId: buyer.id,
    sellerId: seller.id,
    amount: '50.00',
    currency: 'USD',
    title: 'Demo Service',
    description: 'End-to-end demo for hackathon',
  });
  console.log('✓ Order created:', order.id);

  // 4. Reserve funds
  await sdk.orders.reserve(order.id);
  console.log('✓ Funds reserved');

  // 5. Create + fund escrow
  await sdk.orders.createEscrow(order.id);
  await sdk.orders.waitForStatus(order.id, 'ESCROW_CREATED');
  console.log('✓ Escrow contract deployed');

  await sdk.orders.fundEscrow(order.id);
  await sdk.orders.waitForStatus(order.id, 'IN_PROGRESS');
  console.log('✓ Escrow funded (USDC on-chain)');

  // 6. Simulate work delivery + buyer approval
  await sdk.orders.release(order.id, "Buyer approved the order");
  await sdk.orders.waitForStatus(order.id, 'CLOSED');
  console.log('✓ Funds released to seller');

  // 7. Check seller balance
  const sellerBalance = await sdk.balance.get(seller.id);
  console.log('\nSeller balance:', sellerBalance.available, sellerBalance.currency);

  console.log('\n=== Demo complete! ===');
}

fullDemoFlow().catch(console.error);

import {
  InsufficientFundsError,
  NotFoundError,
  ValidationError,
  InvalidTransitionError,
  OfferHubError,
} from '@offerhub/sdk';

async function safeCreateOrder(buyerId: string, sellerId: string, amount: string) {
  try {
    const order = await sdk.orders.create({
      buyerId,
      sellerId,
      amount,
      currency: 'USD',
      title: 'Service',
    });
    await sdk.orders.reserve(order.id);
    return order;

  } catch (error) {
    if (error instanceof InsufficientFundsError) {
      // Show "Please add funds" UI to the buyer
      console.error(`Need ${error.required} USDC, balance is ${error.available}`);
    } else if (error instanceof NotFoundError) {
      // User ID does not exist — re-register flow
      console.error(`${error.resourceType} not found`);
    } else if (error instanceof ValidationError) {
      // Bad request body — log and fix
      console.error('Validation failed:', error.errors);
    } else if (error instanceof InvalidTransitionError) {
      // State machine violation — check current order status
      console.error(`Cannot transition from state: ${error.currentState}`);
    } else if (error instanceof OfferHubError) {
      // Generic orchestrator error
      console.error('Orchestrator error:', error.message);
    } else {
      throw error; // Re-throw unexpected errors
    }
  }
}

// Attach a stable, deterministic key to each state-changing operation
const idempotentSdk = sdk.withIdempotencyKey(
  '550e8400-e29b-41d4-a716-446655440005'
);

// Safe to retry — same key returns the cached result
 await idempotentSdk.orders.fundEscrow(orderId);

my-marketplace/
├── .env                     # OFFERHUB_API_URL, OFFERHUB_API_KEY
├── package.json
├── tsconfig.json
└── src/
    ├── sdk.ts               # SDK singleton
    ├── 01-signup.ts         # Create buyer + seller users
    ├── 02-deposit.ts        # Show deposit address
    ├── 03-listing-and-order.ts  # Create order + reserve funds
    ├── 04-escrow.ts         # Deploy contract + fund on-chain
    ├── 05-release.ts        # Approve + release to seller
    ├── 06-dispute.ts        # Dispute + platform resolution
    ├── 07-events.ts         # SSE real-time event subscription
    └── full-demo.ts         # Complete happy-path demo