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:

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

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

Escrows

Escrow contracts hold funds securely between buyers and sellers until project completion.

Initialize an Escrow

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

Creates a new escrow contract between buyer and seller. Funds are held until release.

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.

Release Escrow

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

Releases held funds from an escrow to the seller upon project completion.

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.

Open Dispute

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

Opens a dispute on an escrow for resolution.

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.

Webhooks

Receive real-time event notifications from OFFER-HUB via HTTP webhooks.

See the Webhooks documentation for complete details on:

• Payload structures
• Signature verification
• Retry logic

Available Events

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

All state-changing POSTs accept Idempotency-Key to prevent duplicate operations:

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

{ "order_data": "..." }

Behavior

1. First request: Processed normally
2. Repeated request (same key): Returns original response
3. Different body + same key: Returns 409 IDEMPOTENCY_KEY_REUSED

Idempotency Windows

Rate Limiting

Response When Exceeded

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "details": {
      "retry_after": 60
    }
  }
}

Available Endpoints

Auth & Config

Users

Orders

Escrow

Resolution

Withdrawals

Events

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

• Webhooks - Receive event notifications
• Quick Start - Your first API call
• SDK Guide - Use the TypeScript SDK