API Reference

The OFFER-HUB Orchestrator exposes a RESTful JSON API. All endpoints are prefixed with /api/v1.

Base URL

https://{your-orchestrator-domain}/api/v1

For local development:

http://localhost:4000/api/v1

Authentication

All requests require authentication via a Bearer token (API Key).

Request Header

Authorization: Bearer ohk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Getting an API Key

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:

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

API Key Scopes

Common Headers

Request Headers

Response Headers

Response Format

Success Response

{
  "id": "ord_abc123",
  "status": "ORDER_CREATED",
  "amount": "100.00",
  "currency": "USD",
  "created_at": "2026-01-12T10:00:00.000Z",
  "updated_at": "2026-01-12T10:00:00.000Z"
}

List Response

{
  "data": ["..."],
  "pagination": {
    "has_more": true,
    "next_cursor": "ord_abc123"
  }
}

Error Response

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Available balance is less than requested amount",
    "details": {
      "available": "50.00",
      "requested": "100.00"
    }
  }
}

Error Codes

Per-endpoint reference

The summaries on this page cover the API surface at a glance. The endpoint groups below have dedicated pages with real DTO fields, signer roles, valid state transitions, error codes, and cURL plus TypeScript SDK examples:

Escrows

Escrow contracts hold funds securely between buyers and sellers until project completion. The two creation and funding calls are documented end to end in Escrow Endpoints; the three settlement calls are in Resolution Endpoints.

Initialize an Escrow

POST /api/v1/orders/{id}/escrow

Creates a new escrow contract between buyer and seller. Funds are held until release. See Escrow Endpoints for parameters, contract roles, and the full response schema.

Request Body

{
  "amount": "2500.00",
  "currency": "USD"
}

Response

{
  "data": {
    "escrow_id": "esc_01JKL",
    "order_id": "ord_abc123",
    "buyer_id": "usr_01ABC",
    "seller_id": "usr_02ABC",
    "amount": "2500.00",
    "currency": "USD",
    "status": "PENDING",
    "created_at": "2026-02-01T14:00:00.000Z"
  }
}

Fund Escrow

POST /api/v1/orders/{id}/escrow/fund

Funds an existing escrow contract. See Escrow Endpoints for the reserved-balance debit, contract-type selection, and error codes.

Release Escrow

POST /api/v1/orders/{id}/resolution/release

Releases held funds from an escrow to the seller upon project completion. See Resolution Endpoints for the three on-chain steps and their signer roles.

Response

{
  "data": {
    "escrow_id": "esc_01JKL",
    "status": "RELEASED",
    "released_amount": "2500.00",
    "released_at": "2026-02-10T16:00:00.000Z"
  }
}

Refund Escrow

POST /api/v1/orders/{id}/resolution/refund

Refunds escrowed funds back to the buyer. See Resolution Endpoints for the two-step dispute-then-resolve flow.

Open Dispute

POST /api/v1/orders/{id}/resolution/dispute

Opens a dispute on an escrow for resolution. See Resolution Endpoints for the OpenDisputeDto fields and how a dispute is later resolved.

Transactions

Retrieve user transaction and balance history.

Get User Balance

GET /api/v1/users/{id}/balance

Returns the user's current balance across all currencies.

Response

{
  "data": {
    "user_id": "usr_abc123",
    "balances": [
      { "currency": "USD", "available": "1250.00", "held": "200.00" },
      { "currency": "XLM", "available": "5000.00", "held": "0.00" }
    ]
  }
}

Get Deposit Address

GET /api/v1/users/{id}/wallet/deposit

Returns a deposit address for the user to fund their account.

Real-Time Events

Subscribers consume real-time domain events over the SSE event stream at GET /api/v1/events. Separately, the Orchestrator receives inbound webhooks from external providers (Airtm, Trustless Work) to process payment and escrow lifecycle events — see the Inbound Webhooks reference for signature verification and deduplication behavior.

Assets

Create Withdrawal

POST /api/v1/withdrawals

Initiate a withdrawal from user balance.

Request Body

{
  "user_id": "usr_abc123",
  "amount": "100.00",
  "currency": "USD",
  "destination": {
    "type": "stellar",
    "address": "GBCG42WTVWPO4Q6N..."
  }
}

Get Withdrawal

GET /api/v1/withdrawals/{id}

Returns withdrawal status and details.

Pagination

List endpoints support cursor-based pagination:

Request

GET /orders?limit=20&cursor=ord_xyz789

Response

{
  "data": ["..."],
  "pagination": {
    "has_more": true,
    "next_cursor": "ord_abc123"
  }
}

Filters

List endpoints accept query parameter filters:

GET /orders?status=IN_PROGRESS&buyer_id=usr_abc&created_after=2026-01-01

Idempotency

Idempotency-Key is optional and is processed on POST, PUT, and PATCH requests. When supplied, it must be a UUID v4 and is scoped to the API key and request body. The guard and response lifecycle are implemented in the orchestrator IdempotencyGuard and IdempotencyInterceptor.

Use a real UUID v4 for every request key:

POST /orders
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{ "order_data": "..." }

Behavior

1. Invalid key: Returns 400 VALIDATION_ERROR; the key must be a UUID v4.
2. First request: Processed normally and stored for replay.
3. Repeated request with the same key and body: Returns the original response and sets Idempotency-Replay: true.
4. Different body with the same key: Returns 409 IDEMPOTENCY_KEY_REUSED.
5. Original request still processing: Returns 409 IDEMPOTENCY_KEY_IN_PROGRESS.

Example for a reused key:

{
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "message": "This idempotency key was used with a different request body"
  }
}

Example while the original request is still running:

{
  "error": {
    "code": "IDEMPOTENCY_KEY_IN_PROGRESS",
    "message": "A request with this key is still being processed"
  }
}

Keys are retained for 24 hours. Reuse after that period is treated as a new request.

Rate Limiting

The API applies one global limit of 100 requests per 60-second window. The counter is keyed by API key when authenticated, or by client IP when no API key is available. There are no additional per-endpoint limits documented here. The headers and error payload are implemented in the orchestrator RateLimitGuard.

Every response includes:

Response When Exceeded

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "details": {
      "limit": 100,
      "windowSeconds": 60,
      "retryAfter": 60
    }
  }
}

Available Endpoints

Every entry below was verified against the real controllers in apps/api/src/modules. All paths are relative to the /api/v1 prefix.

Auth

Config

Health

Users

Balance

All balance endpoints are scoped to a user: /users/{userId}/balance.

Wallet

Wallet endpoints are scoped to a user: /users/{userId}/wallet.

Top-ups

Orders

Escrow

Resolution

Disputes

Withdrawals

Events

Webhooks (inbound)

Audit Logs

Versioning

The API uses path versioning:

/api/v1/orders
/api/v2/orders  (future)

• v1 is the current stable version
• Deprecated versions will have 6 months notice

Next Steps

• Events (SSE) - Real-time event stream and event catalog
• Inbound Webhooks - AirTM and Trustless Work receivers
• Quick Start - Your first API call
• SDK Guide - Use the TypeScript SDK