Programmable Escrow and On-Chain Dispute Resolution

FlareHQ’s escrow service lets you lock USDC in a smart contract on Arc testnet until both parties confirm that conditions are met. If either side disagrees, either party can raise a dispute — at which point the designated arbiter reviews the evidence and resolves the outcome on-chain. No funds move unless the contract says so.

Use Cases

Freelance Milestone Payments

Lock the project fee in escrow before work begins. The client releases funds when they accept the deliverable.

Marketplace Transactions

Hold buyer funds until the seller ships and the buyer confirms receipt, eliminating chargeback risk.

AI Agent Job Completion

Pay autonomous agents only when their on-chain wallet reports a task as complete, verified by an arbiter contract.

Grant Milestones

Release tranche payments only when milestone conditions written into the condition field are satisfied.

How Escrow Works

Create — The depositor locks USDC in the escrow contract, naming a beneficiary and an arbiter.
Both confirm — When both depositor and beneficiary call confirmDelivery, the contract releases funds to the beneficiary automatically.
Dispute — If either party raises a dispute, funds are frozen and the arbiter reviews the case.
Resolve — The arbiter resolves the dispute on-chain to send funds to either party.

Creating an Escrow

REST API Parameters

string

required

The wallet address of the party locking the funds. This wallet must hold sufficient USDC.

string

required

The wallet ID used to authorise the on-chain transactions. Retrieve this from GET /api/agent/status.

string

required

The wallet address of the party that receives funds on release.

string

required

USDC amount to lock, as a decimal string, e.g. "200.00".

number

Hours from now until the auto-release deadline. Defaults to 24. See the warning below.

string

Human-readable release condition stored on-chain and shown to both parties, e.g. "Deliver completed API integration".

string

URL to receive escrow lifecycle events. See Webhook Events below.

Releasing Funds

Either the depositor or the beneficiary calls the release endpoint to confirm delivery. The contract tracks confirmations — funds are released to the beneficiary only when both parties have confirmed.

curl -X POST https://flarehq.xyz/api/escrow/release \
  -H "Authorization: Bearer fhq_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "escrow_m8k2p1_ab12cd",
    "callerSCA": "0xYourWalletAddress"
  }'

boolean

true when both parties have confirmed and funds have transferred to the beneficiary.

string

Human-readable status. If only one party has confirmed, the message says so and instructs you to wait for the other party.

Raising a Dispute

Either party can raise a dispute at any time while the escrow is ACTIVE. This freezes the funds and notifies the arbiter.

curl -X POST https://flarehq.xyz/api/escrow/dispute \
  -H "Authorization: Bearer fhq_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "escrow_m8k2p1_ab12cd",
    "callerSCA": "0xWorkerAddress",
    "reason": "Client is unresponsive and has not reviewed the delivered work within the agreed 48-hour window."
  }'

Once a dispute is raised, the escrow status changes to DISPUTED and neither party can release funds unilaterally. The arbiter reviews the case and resolves the outcome on-chain.

Checking Escrow Status

curl "https://flarehq.xyz/api/escrow/status?reference=escrow_m8k2p1_ab12cd" \
  -H "Authorization: Bearer fhq_sec_..."

Escrow Lifecycle

ACTIVE ──── both parties confirm ──→ RELEASED
  │
  ├──── either party disputes ────→ DISPUTED ──── arbiter resolves ──→ RELEASED / REFUNDED
  │
  └──── deadline passes (no dispute raised) ─────────────────────────→ RELEASED (auto)

Status	Description
`ACTIVE`	Funds are locked; awaiting confirmations
`RELEASED`	Funds transferred to beneficiary
`DISPUTED`	A dispute is open; arbiter is reviewing
`REFUNDED`	Arbiter ruled in the depositor’s favour; funds returned

The Arbiter

The default arbiter address is 0x3500000000000000000000000000000000008004, the agent registry contract on Arc testnet. You can substitute any address — a multisig, a DAO, or a trusted third-party contract — by passing a different arbiter value when creating the escrow via the SDK.

Webhook Events

Event	Fired when
`escrow.created`	Escrow is confirmed on-chain and is `ACTIVE`
`escrow.released`	Both parties confirmed and USDC transferred to beneficiary
`dispute.created`	A dispute is raised; escrow moves to `DISPUTED`
`dispute.resolved`	Arbiter resolves the dispute on-chain

Example Payload — `escrow.created`

{
  "event": "escrow.created",
  "reference": "escrow_m8k2p1_ab12cd",
  "depositorSCA": "0xYourWalletAddress",
  "beneficiarySCA": "0xWorkerAddress",
  "amount": 200.0,
  "currency": "USDC",
  "condition": "Deliver completed API integration with passing test suite",
  "deadline": "2025-01-18T10:00:00.000Z",
  "txHash": "0xabc123...",
  "explorerUrl": "https://testnet.arcscan.app/tx/0xabc123...",
  "createdAt": "2025-01-15T10:00:00.000Z"
}

You can verify any escrow transaction on the Arc block explorer:

https://testnet.arcscan.app/tx/{txHash}

Automatic release at deadline. If deadlineHours passes and no dispute has been raised, the escrow contract releases funds automatically to the beneficiary. Raise a dispute before the deadline if you believe conditions have not been met — you cannot dispute an escrow once it has auto-released.

Get Started

Payments

x402 Protocol

Agentic Finance

Developer Guide

Programmable Escrow and On-Chain Dispute Resolution

Use Cases

Freelance Milestone Payments

Marketplace Transactions

AI Agent Job Completion

Grant Milestones

How Escrow Works

Creating an Escrow

REST API Parameters

Releasing Funds

Raising a Dispute

Checking Escrow Status

Escrow Lifecycle

The Arbiter

Webhook Events

Example Payload — `escrow.created`

​Use Cases

Freelance Milestone Payments

Marketplace Transactions

AI Agent Job Completion

Grant Milestones

​How Escrow Works

​Creating an Escrow

​REST API Parameters

​Releasing Funds

​Raising a Dispute

​Checking Escrow Status

​Escrow Lifecycle

​The Arbiter

​Webhook Events

​Example Payload — escrow.created

Use Cases

How Escrow Works

Creating an Escrow

REST API Parameters

Releasing Funds

Raising a Dispute

Checking Escrow Status

Escrow Lifecycle

The Arbiter

Webhook Events

Example Payload — `escrow.created`