Escrow Flows

Complete guide to all escrow lifecycle flows — creation, funding, release, dispute, and refund.

This guide walks through every escrow flow in OFFER-HUB: from creating and funding a contract to releasing, disputing, and refunding. Each flow includes step-by-step diagrams and code examples.

Note

OFFER-HUB uses Trustless Work smart contracts on Stellar for non-custodial escrow. All flows ultimately resolve on-chain.

State Machines

Escrow and order lifecycles are governed by two canonical state machines (matching docs/architecture/state-machines.md in the orchestrator repository exactly). The Order state machine tracks the order lifecycle, while the internal Escrow state machine tracks the smart contract itself. The flows below map onto these two machines.

Mermaid

Rendering diagram…

Mermaid

Rendering diagram…

Creating an Escrow

An escrow contract is created after an order is placed and the buyer's funds are reserved off-chain.

Steps

Create the order — Buyer's balance is reserved (ORDER_CREATED → FUNDS_RESERVED)
Call the escrow creation endpoint — Deploys a Trustless Work contract on Stellar (ESCROW_CREATING)
Wait for confirmation — Contract becomes CREATED; the order advances to ESCROW_FUNDING

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json"

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "ESCROW_CREATING",
    "escrow": {
      "contractId": "CDLZFC3SYJYD...",
      "status": "creating"
    }
  }
}

TypeScript SDK

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

const sdk = new OfferHubSDK({
  apiUrl: 'http://localhost:4000',
  apiKey: 'ohk_live_your_api_key',
});

// Create escrow contract
await sdk.orders.createEscrow('ord_xyz789');

// Wait until the contract is deployed (order advances to ESCROW_FUNDING)
await sdk.orders.waitForStatus('ord_xyz789', 'ESCROW_FUNDING');

Tip

Contract deployment is asynchronous. Use waitForStatus or subscribe to the order.escrow_creating event rather than polling manually.

Funding the Escrow

Once the contract is deployed, the buyer's reserved USDC is transferred on-chain into the smart contract.

Steps

Call the fund endpoint — Triggers an on-chain USDC transfer
Platform signs — The buyer's encrypted key authorizes the transaction
Stellar confirms — Transaction lands on-chain (5–10 seconds)
Status updates — Order advances to IN_PROGRESS

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow/fund \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"

TypeScript SDK

await sdk.orders.fundEscrow('ord_xyz789');

await sdk.orders.waitForStatus('ord_xyz789', 'IN_PROGRESS');

Warning

Always include an Idempotency-Key when funding. If the request times out, retrying with the same key is safe and prevents double-funding.

Balance changes during funding

Stage	Available	Reserved	On-Chain (Wallet)	In Contract
After reserve	50.00	50.00	100.00	0.00
After funding	50.00	0.00	50.00	50.00

Release Conditions

Funds can be released in two ways depending on how the order is configured.

Time-Based Release

The buyer approves release after a deadline or after delivery confirmation within a time window.

Mermaid

Rendering diagram…

Seller marks work as complete
Buyer has a review window (e.g., 72 hours)
If the buyer approves — or the window expires without a dispute — release is triggered

Milestone-Based Release

For larger projects, create one order with multiple milestones. The milestones are tracked within the same order and share its escrow. Complete each milestone as work is delivered, then use the order resolution flow to release, refund, or dispute the order.

Mermaid

Rendering diagram…

Tip

Milestones do not have separate order lifecycles or escrow contracts. Use GET /orders/{id}/milestones to list them and POST /orders/{id}/milestones/{ref}/complete to mark one complete within the parent order.

Releasing Funds

When the buyer approves the delivered work, funds are released to the seller in three on-chain transactions.

Steps

Step	Contract call	Signer	Role in contract
1	`changeMilestoneStatus`	Seller	`serviceProvider`
2	`approveMilestone`	Buyer	`approver`
3	`releaseFunds`	Buyer	`releaseSigner`

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/release \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002" \
  -d '{"requestedBy": "usr_buyer123"}'

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "CLOSED",
    "resolution": {
      "type": "released",
      "amount": "50.00",
      "recipient": "usr_seller456",
      "completedAt": "2026-03-01T14:00:00.000Z"
    }
  }
}

TypeScript SDK

await sdk.orders.release('ord_xyz789', 'Buyer approved release');

Note

After release, the seller's internal balance is credited. They can withdraw to their external wallet at any time via the Withdrawals flow.

Raising a Dispute

If the buyer believes the work was not delivered as agreed, they can open a dispute while the order is IN_PROGRESS.

Steps

Buyer opens dispute — Provides a reason
Status changes — Order moves to DISPUTED (funds stay locked in the contract)
Funds remain locked — Neither party can access the escrow
Platform reviews — Manual or automated resolution begins

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/dispute \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "openedBy": "BUYER",
    "reason": "QUALITY_ISSUE"
  }'

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "DISPUTED",
    "dispute": {
      "id": "dsp_abc123",
      "reason": "QUALITY_ISSUE",
      "openedAt": "2026-03-01T10:00:00.000Z",
      "openedBy": "BUYER"
    }
  }
}

TypeScript SDK

await sdk.disputes.open('ord_xyz789', {
  reason: 'Work delivered does not match agreed specifications',
});

Warning

Disputes can only be opened while the order is IN_PROGRESS. Once released or refunded, the order is final.

Dispute Resolution

After a dispute is opened, the platform reviews evidence and resolves with a release (seller wins) or refund (buyer wins).

Resolution Options

Decision	Outcome	On-Chain Transaction
`FULL_RELEASE`	Funds go to seller	`resolve_dispute` → release
`FULL_REFUND`	Funds return to buyer	`resolve_dispute` → refund
`SPLIT`	Custom split between parties	`resolve_dispute` → split

REST — Resolve with Refund

bash

curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "FULL_REFUND",
    "note": "Seller did not deliver agreed deliverables"
  }'

REST — Resolve with Release

bash

curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "FULL_RELEASE",
    "note": "Evidence confirms work was delivered as agreed"
  }'

TypeScript SDK

// Resolve in favor of buyer (refund)
await sdk.disputes.resolve('dsp_abc123', {
  decision: 'FULL_REFUND',
  note: 'Seller did not deliver agreed deliverables',
});

// Resolve in favor of seller (release)
await sdk.disputes.resolve('dsp_abc123', {
  decision: 'FULL_RELEASE',
  note: 'Evidence confirms work was delivered as agreed',
});

Note

Only the platform (using the master API key) can resolve disputes. This requires a co-signature from the Trustless Work smart contract arbiter.

Refund Flow

A refund can result from dispute resolution or, in some configurations, from a direct cancellation before work begins.

Refund via Dispute

Mermaid

Rendering diagram…

Two on-chain transactions are required:

Step	Contract call	Signer	Role in contract
1	`disputeEscrow`	Buyer	`approver` (disputer)
2	`resolveDispute` (100% to buyer)	Platform	`disputeResolver`

Danger

Role separation is enforced by the smart contract. The disputeResolver must be a different party from the disputer. Because the buyer signs step 1, the platform wallet is the only valid signer for step 2. Neither the buyer nor the seller can unilaterally resolve a dispute to reclaim funds.

Refund via Cancellation

If the order is cancelled before funding (e.g., the seller cannot fulfill), the off-chain reservation is released with no blockchain transaction:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/cancel \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestedBy": "usr_seller456", "reason": "Unable to fulfill order"}'

Note

Cancellations before escrow funding are instant — no Stellar transaction required. The buyer's reserved balance is immediately returned to available.

TypeScript SDK — Full Dispute-to-Refund Flow

// Step 1: Buyer raises dispute
await sdk.disputes.open('ord_xyz789', {
  reason: 'Work not delivered',
});

// Step 2: Platform fetches the dispute
const disputes = await sdk.disputes.list({ orderId: 'ord_xyz789' });
const dispute = disputes[0];

// Step 3: Platform resolves with refund
await sdk.disputes.resolve(dispute.id, {
  decision: 'FULL_REFUND',
  note: 'Verified: seller did not deliver',
});

// Buyer's balance is now credited
const buyer = await sdk.users.get('usr_buyer123');
console.log('Buyer available balance:', buyer.balance.available);

Listening to Escrow Events

Lifecycle events are delivered over the SSE event stream at GET /api/v1/events — there is no outbound webhook API. Subscribe to keep your application in sync:

const events = sdk.events.subscribe();

events.on('order.escrow_creating', (data) => {
  console.log('Contract deploying:', data.contractId);
});

events.on('order.escrow_funded', (data) => {
  console.log('Funds locked:', data.amount, 'USDC');
});

events.on('order.released', (data) => {
  console.log('Released to seller:', data.recipient);
});

events.on('order.disputed', (data) => {
  console.log('Dispute opened:', data.dispute.id);
});

events.on('order.refunded', (data) => {
  console.log('Refunded to buyer:', data.amount, 'USDC');
});

Error Reference

Error	Cause	Fix
`ESCROW_ALREADY_EXISTS`	Contract already created for this order	Check status before calling create
`ESCROW_NOT_FUNDED`	Release attempted before funding	Fund the escrow first
`INVALID_STATE_TRANSITION`	Action not valid in current status	Follow the state machine
`INSUFFICIENT_FUNDS`	Buyer wallet has insufficient USDC	Check balance before funding
`DISPUTE_ALREADY_OPEN`	Duplicate dispute on same order	Resolve existing dispute first
`FUNDING_TIMEOUT`	Stellar transaction not confirmed	Check order status — do not retry blindly

Tip

Use idempotency keys on all mutating requests (fund, release, dispute). This allows safe retries without risk of duplicate transactions.

Next Steps

Escrow Guide — State machine reference and balance mechanics
Disputes Guide — Full dispute management documentation
Withdrawals Guide — Move funds off-platform after release
SDK Quick Start — TypeScript SDK setup and usage
API Reference — Full REST API documentation

Edit this page on GitHub

Escrow Flows

Complete guide to all escrow lifecycle flows — creation, funding, release, dispute, and refund.

This guide walks through every escrow flow in OFFER-HUB: from creating and funding a contract to releasing, disputing, and refunding. Each flow includes step-by-step diagrams and code examples.

Note

OFFER-HUB uses Trustless Work smart contracts on Stellar for non-custodial escrow. All flows ultimately resolve on-chain.

State Machines

Mermaid

Rendering diagram…

Mermaid

Rendering diagram…

Creating an Escrow

An escrow contract is created after an order is placed and the buyer's funds are reserved off-chain.

Steps

Create the order — Buyer's balance is reserved (ORDER_CREATED → FUNDS_RESERVED)
Call the escrow creation endpoint — Deploys a Trustless Work contract on Stellar (ESCROW_CREATING)
Wait for confirmation — Contract becomes CREATED; the order advances to ESCROW_FUNDING

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json"

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "ESCROW_CREATING",
    "escrow": {
      "contractId": "CDLZFC3SYJYD...",
      "status": "creating"
    }
  }
}

TypeScript SDK

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

const sdk = new OfferHubSDK({
  apiUrl: 'http://localhost:4000',
  apiKey: 'ohk_live_your_api_key',
});

// Create escrow contract
await sdk.orders.createEscrow('ord_xyz789');

// Wait until the contract is deployed (order advances to ESCROW_FUNDING)
await sdk.orders.waitForStatus('ord_xyz789', 'ESCROW_FUNDING');

Tip

Contract deployment is asynchronous. Use waitForStatus or subscribe to the order.escrow_creating event rather than polling manually.

Funding the Escrow

Once the contract is deployed, the buyer's reserved USDC is transferred on-chain into the smart contract.

Steps

Call the fund endpoint — Triggers an on-chain USDC transfer
Platform signs — The buyer's encrypted key authorizes the transaction
Stellar confirms — Transaction lands on-chain (5–10 seconds)
Status updates — Order advances to IN_PROGRESS

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow/fund \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001"

TypeScript SDK

await sdk.orders.fundEscrow('ord_xyz789');

await sdk.orders.waitForStatus('ord_xyz789', 'IN_PROGRESS');

Warning

Always include an Idempotency-Key when funding. If the request times out, retrying with the same key is safe and prevents double-funding.

Balance changes during funding

Stage	Available	Reserved	On-Chain (Wallet)	In Contract
After reserve	50.00	50.00	100.00	0.00
After funding	50.00	0.00	50.00	50.00

Release Conditions

Funds can be released in two ways depending on how the order is configured.

Time-Based Release

The buyer approves release after a deadline or after delivery confirmation within a time window.

Mermaid

Rendering diagram…

Seller marks work as complete
Buyer has a review window (e.g., 72 hours)
If the buyer approves — or the window expires without a dispute — release is triggered

Milestone-Based Release

Mermaid

Rendering diagram…

Tip

Releasing Funds

When the buyer approves the delivered work, funds are released to the seller in three on-chain transactions.

Steps

Step	Contract call	Signer	Role in contract
1	`changeMilestoneStatus`	Seller	`serviceProvider`
2	`approveMilestone`	Buyer	`approver`
3	`releaseFunds`	Buyer	`releaseSigner`

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/release \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002" \
  -d '{"requestedBy": "usr_buyer123"}'

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "CLOSED",
    "resolution": {
      "type": "released",
      "amount": "50.00",
      "recipient": "usr_seller456",
      "completedAt": "2026-03-01T14:00:00.000Z"
    }
  }
}

TypeScript SDK

await sdk.orders.release('ord_xyz789', 'Buyer approved release');

Note

After release, the seller's internal balance is credited. They can withdraw to their external wallet at any time via the Withdrawals flow.

Raising a Dispute

If the buyer believes the work was not delivered as agreed, they can open a dispute while the order is IN_PROGRESS.

Steps

Buyer opens dispute — Provides a reason
Status changes — Order moves to DISPUTED (funds stay locked in the contract)
Funds remain locked — Neither party can access the escrow
Platform reviews — Manual or automated resolution begins

Mermaid

Rendering diagram…

REST

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/dispute \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "openedBy": "BUYER",
    "reason": "QUALITY_ISSUE"
  }'

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "DISPUTED",
    "dispute": {
      "id": "dsp_abc123",
      "reason": "QUALITY_ISSUE",
      "openedAt": "2026-03-01T10:00:00.000Z",
      "openedBy": "BUYER"
    }
  }
}

TypeScript SDK

await sdk.disputes.open('ord_xyz789', {
  reason: 'Work delivered does not match agreed specifications',
});

Warning

Disputes can only be opened while the order is IN_PROGRESS. Once released or refunded, the order is final.

Dispute Resolution

After a dispute is opened, the platform reviews evidence and resolves with a release (seller wins) or refund (buyer wins).

Resolution Options

Decision	Outcome	On-Chain Transaction
`FULL_RELEASE`	Funds go to seller	`resolve_dispute` → release
`FULL_REFUND`	Funds return to buyer	`resolve_dispute` → refund
`SPLIT`	Custom split between parties	`resolve_dispute` → split

REST — Resolve with Refund

bash

curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "FULL_REFUND",
    "note": "Seller did not deliver agreed deliverables"
  }'

REST — Resolve with Release

bash

curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "FULL_RELEASE",
    "note": "Evidence confirms work was delivered as agreed"
  }'

TypeScript SDK

// Resolve in favor of buyer (refund)
await sdk.disputes.resolve('dsp_abc123', {
  decision: 'FULL_REFUND',
  note: 'Seller did not deliver agreed deliverables',
});

// Resolve in favor of seller (release)
await sdk.disputes.resolve('dsp_abc123', {
  decision: 'FULL_RELEASE',
  note: 'Evidence confirms work was delivered as agreed',
});

Note

Only the platform (using the master API key) can resolve disputes. This requires a co-signature from the Trustless Work smart contract arbiter.

Refund Flow

A refund can result from dispute resolution or, in some configurations, from a direct cancellation before work begins.

Refund via Dispute

Mermaid

Rendering diagram…

Two on-chain transactions are required:

Step	Contract call	Signer	Role in contract
1	`disputeEscrow`	Buyer	`approver` (disputer)
2	`resolveDispute` (100% to buyer)	Platform	`disputeResolver`

Danger

Refund via Cancellation

If the order is cancelled before funding (e.g., the seller cannot fulfill), the off-chain reservation is released with no blockchain transaction:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/cancel \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestedBy": "usr_seller456", "reason": "Unable to fulfill order"}'

Note

Cancellations before escrow funding are instant — no Stellar transaction required. The buyer's reserved balance is immediately returned to available.

TypeScript SDK — Full Dispute-to-Refund Flow

// Step 1: Buyer raises dispute
await sdk.disputes.open('ord_xyz789', {
  reason: 'Work not delivered',
});

// Step 2: Platform fetches the dispute
const disputes = await sdk.disputes.list({ orderId: 'ord_xyz789' });
const dispute = disputes[0];

// Step 3: Platform resolves with refund
await sdk.disputes.resolve(dispute.id, {
  decision: 'FULL_REFUND',
  note: 'Verified: seller did not deliver',
});

// Buyer's balance is now credited
const buyer = await sdk.users.get('usr_buyer123');
console.log('Buyer available balance:', buyer.balance.available);

Listening to Escrow Events

Lifecycle events are delivered over the SSE event stream at GET /api/v1/events — there is no outbound webhook API. Subscribe to keep your application in sync:

const events = sdk.events.subscribe();

events.on('order.escrow_creating', (data) => {
  console.log('Contract deploying:', data.contractId);
});

events.on('order.escrow_funded', (data) => {
  console.log('Funds locked:', data.amount, 'USDC');
});

events.on('order.released', (data) => {
  console.log('Released to seller:', data.recipient);
});

events.on('order.disputed', (data) => {
  console.log('Dispute opened:', data.dispute.id);
});

events.on('order.refunded', (data) => {
  console.log('Refunded to buyer:', data.amount, 'USDC');
});

Error Reference

Error	Cause	Fix
`ESCROW_ALREADY_EXISTS`	Contract already created for this order	Check status before calling create
`ESCROW_NOT_FUNDED`	Release attempted before funding	Fund the escrow first
`INVALID_STATE_TRANSITION`	Action not valid in current status	Follow the state machine
`INSUFFICIENT_FUNDS`	Buyer wallet has insufficient USDC	Check balance before funding
`DISPUTE_ALREADY_OPEN`	Duplicate dispute on same order	Resolve existing dispute first
`FUNDING_TIMEOUT`	Stellar transaction not confirmed	Check order status — do not retry blindly

Tip

Use idempotency keys on all mutating requests (fund, release, dispute). This allows safe retries without risk of duplicate transactions.

Next Steps

Escrow Guide — State machine reference and balance mechanics
Disputes Guide — Full dispute management documentation
Withdrawals Guide — Move funds off-platform after release
SDK Quick Start — TypeScript SDK setup and usage
API Reference — Full REST API documentation

Edit this page on GitHub