Core Concepts

These are the primitives of the Clearhold engine. Understanding these is essential for correct integration.

Escrow

An escrow is the top-level container for a transactional agreement between two parties.

Definition A state machine tracking funds and deliverables between client and contractor
Lifecycle CREATED → FUNDED → IN_PROGRESS → DELIVERED → COMPLETED
Boundary We track state. You hold funds. We never touch money.

Key Properties

  • external_id — Your reference (order ID, project ID, etc.)
  • total_amount — Total value in minor units (cents)
  • currency — ISO 4217 code (USD, EUR, etc.)
  • state — Current lifecycle position

Milestone

A milestone represents a phase of work with an associated amount and deadline.

Definition A sub-unit of an escrow with its own deadline and payout amount
Lifecycle Created with escrow → Deliverable submitted → Approved or Disputed
Boundary We track deadlines and completion. You define what "done" means.

Milestone Sum Rule

Milestone amounts must equal escrow total. API rejects mismatched sums.

typescript 
// Valid
total_amount: 50000
milestones: [
  { amount: 20000 },
  { amount: 30000 }
]  // Sum = 50000 ✓

// Invalid → 409 Conflict
total_amount: 50000
milestones: [
  { amount: 20000 },
  { amount: 25000 }
]  // Sum = 45000 ✗

Dispute

A dispute is opened when a party contests the escrow outcome.

Definition A formal claim that triggers the evidence and decision flow
Lifecycle OPEN → EVIDENCE_LOCKED → RESOLVED
Boundary One active dispute per escrow. Closed disputes cannot be reopened.

Reason Codes

  • DELIVERABLE_INCOMPLETE — Work not finished
  • DELIVERABLE_NOT_AS_DESCRIBED — Work doesn't match spec
  • DELIVERABLE_LATE — Deadline missed
  • PAYMENT_ISSUE — Funds-related dispute
  • COMMUNICATION_BREAKDOWN — Process failure
  • OTHER — Catch-all

Evidence

Evidence is submitted during a dispute's open phase.

Definition A reference to external proof supporting a party's claim
Storage We store URI + content hash. We never download or host files.
Boundary You host files. We verify hashes. We reference, not store.

Evidence Window

  • Default window: 72 hours from dispute open
  • Can be locked manually via POST /disputes/:id/lock
  • After lock: no new evidence accepted

Decision

A decision resolves a dispute and determines fund allocation.

Definition The final resolution of a dispute, specifying payout ratios
Types FULL_RELEASE (100% contractor), FULL_REFUND (100% client), SPLIT
Boundary We calculate. You execute. We never move money.

Decision Flow

  1. Engine recommendation — Deterministic calculation based on signals
  2. Operator review — Human can adjust within ±30%
  3. Final decision — Immutable, audit-logged
  4. Webhook dispatch — You receive the payout breakdown

Lifecycle Diagram

ESCROW_CREATED
Payment Declared
FUNDED
Work Begins
IN_PROGRESS
Work In Progress
Deliverable Submitted
DELIVERED
No Dispute
COMPLETED
Dispute Opened
DISPUTE_OPENED
Evidence Locked
EVIDENCE_LOCKED
Decision Applied
RESOLVED
Next: API Reference →