Query On-Chain Escrow Status — GET /api/escrow/status

Use this endpoint to poll the current state of any escrow your merchant account created. The response includes the live status (ACTIVE, RELEASED, or DISPUTED), both party addresses, the release condition, deadline, and a real-time timeRemaining value in seconds. If the deadline has passed without both parties confirming, isExpired is true and timeRemaining is 0 — at that point the depositor may reclaim funds directly on-chain.

Endpoint

GET https://flarehq.xyz/api/escrow/status?reference={reference}

Authentication

Pass your merchant bearer token in the Authorization header.

Authorization: Bearer fhq_sec_...

Query Parameters

string

required

The escrow reference ID returned by POST /api/escrow/create — e.g. "escrow_m5k2r1_a4b8c2".

Response

boolean

true when the escrow was found and the response is populated.

object

The full escrow record with computed live fields.

Show escrow fields

string

The escrow reference ID.

number

The locked USDC amount as a float — e.g. 200.

string

Always "USDC".

string

Current state: "ACTIVE", "RELEASED", or "DISPUTED".

string

SCA wallet address of the party who funded the escrow.

string

SCA wallet address of the intended recipient.

string | null

The release condition string stored on-chain, or null if none was provided.

string

ISO 8601 timestamp of the auto-release deadline — e.g. "2025-07-16T14:00:00.000Z".

boolean

true if the current time is past the deadline.

number

Seconds remaining until the deadline. 0 if already expired.

string

On-chain transaction hash for the original escrow creation transaction.

string

ArcScan link — https://testnet.arcscan.app/tx/{txHash}. null if txHash is not yet available.

string

The escrow contract address holding the locked funds on Arc testnet.

boolean

Whether the depositor has submitted a release confirmation.

boolean

Whether the beneficiary has submitted a release confirmation.

Examples

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

const ref = "escrow_m5k2r1_a4b8c2";
const response = await fetch(
  `https://flarehq.xyz/api/escrow/status?reference=${ref}`,
  {
    headers: { "Authorization": "Bearer fhq_sec_YOUR_TOKEN" },
  }
);

const { escrow } = await response.json();
console.log(escrow.status);        // "ACTIVE"
console.log(escrow.timeRemaining); // 82340 (seconds)

Active Escrow Response

{
  "success": true,
  "escrow": {
    "reference":            "escrow_m5k2r1_a4b8c2",
    "amount":               200,
    "currency":             "USDC",
    "status":               "ACTIVE",
    "depositorSCA":         "0xDepositorSCAWalletAddress",
    "beneficiarySCA":       "0xBeneficiarySCAWalletAddress",
    "condition":            "Delivery of 500 API credits confirmed",
    "deadline":             "2025-07-16T14:00:00.000Z",
    "isExpired":            false,
    "timeRemaining":        82340,
    "depositorConfirmed":   false,
    "beneficiaryConfirmed": false,
    "contractAddress":      "0xEscrowContractAddress",
    "txHash":               "0xabc123def456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
    "explorerUrl":          "https://testnet.arcscan.app/tx/0xabc123def456789..."
  }
}

Released Escrow Response

{
  "success": true,
  "escrow": {
    "reference":            "escrow_m5k2r1_a4b8c2",
    "amount":               200,
    "currency":             "USDC",
    "status":               "RELEASED",
    "depositorSCA":         "0xDepositorSCAWalletAddress",
    "beneficiarySCA":       "0xBeneficiarySCAWalletAddress",
    "condition":            "Delivery of 500 API credits confirmed",
    "deadline":             "2025-07-16T14:00:00.000Z",
    "isExpired":            false,
    "timeRemaining":        81020,
    "depositorConfirmed":   true,
    "beneficiaryConfirmed": true,
    "contractAddress":      "0xEscrowContractAddress",
    "txHash":               "0xabc123def456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
    "explorerUrl":          "https://testnet.arcscan.app/tx/0xabc123def456789..."
  }
}

Error — Not Found

{
  "success": false,
  "error": "Escrow not found."
}

Poll this endpoint after calling /api/escrow/release to confirm both parties have confirmed. depositorConfirmed and beneficiaryConfirmed update independently — you can surface partial confirmation state to your users in real time.

Overview

Payments

Escrow

Streaming

x402

Agents

Query On-Chain Escrow Status — GET /api/escrow/status

Endpoint

Authentication

Query Parameters

Response

Examples

Active Escrow Response

Released Escrow Response

Error — Not Found

​Endpoint

​Authentication

​Query Parameters

​Response

​Examples

​Active Escrow Response

​Released Escrow Response

​Error — Not Found

Endpoint

Authentication

Query Parameters

Response

Examples

Active Escrow Response

Released Escrow Response

Error — Not Found