Create On-Chain USDC Escrow — POST /api/escrow/create

When you create an escrow, FlareHQ locks the specified USDC amount into a smart contract on Arc Testnet (chain ID 5042002) on your behalf and waits for on-chain confirmation before returning. The response includes the reference ID you will use for every subsequent release, dispute, or status query.

The depositorWalletId is the wallet UUID associated with the depositor’s SCA — not the SCA address itself. Retrieve it from GET /api/agent/status before calling this endpoint.

Endpoint

POST https://flarehq.xyz/api/escrow/create

Authentication

Pass your merchant bearer token in the Authorization header.

Authorization: Bearer fhq_sec_...

Request Body

string

required

The Circle Smart Contract Account (SCA) wallet address that will fund the escrow. This wallet must hold enough USDC to cover amount. Fund testnet wallets at Circle Faucet — select ARC-TESTNET.

string

required

The Circle wallet UUID of the depositor. Used internally to sign the approval and escrow transactions. Retrieve this from GET /api/agent/status.

string

required

The SCA wallet address of the recipient. Funds are released to this address when both parties confirm delivery.

string

required

USDC amount to lock, as a decimal string — e.g. "200.00". USDC uses 6 decimal places internally; the API handles the conversion for you.

number

default:24

Hours from now until the escrow auto-release deadline. Defaults to 24. After the deadline passes, the contract allows the depositor to reclaim funds.

string

A human-readable description of the release condition — e.g. "Delivery of 500 API credits confirmed". Stored on-chain alongside the escrow. Defaults to "No condition set" if omitted.

string

A publicly reachable HTTPS URL. FlareHQ will POST escrow.created and escrow.released events to this URL as JSON. Delivery is best-effort and non-blocking.

Response

boolean

true when the escrow was created and confirmed on-chain.

object

The persisted escrow record.

Show escrow fields

string

Unique escrow identifier in the format escrow_<base36timestamp>_<random>. Use this in all subsequent calls.

number

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

string

Initial status. Always "ACTIVE" on a successful create.

string

The escrow contract address that holds the locked funds on Arc testnet.

string

ISO 8601 timestamp when the escrow expires — e.g. "2025-07-15T12:00:00.000Z".

string

The depositor’s SCA address, echoed back from the request.

string

The beneficiary’s SCA address, echoed back from the request.

string

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

string

Always "USDC".

string

The on-chain transaction hash for the escrow creation — e.g. "0xabc123...".

string

A direct link to the transaction on ArcScan — https://testnet.arcscan.app/tx/{txHash}.

string

A human-readable summary of the operation.

object

Convenience strings showing the exact API calls to release, dispute, or query this escrow.

Show nextSteps fields

string

Template for POST /api/escrow/release with the reference pre-filled.

string

Template for POST /api/escrow/dispute with the reference pre-filled.

string

Template for GET /api/escrow/status with the reference pre-filled.

Examples

curl -X POST https://flarehq.xyz/api/escrow/create \
  -H "Authorization: Bearer fhq_sec_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "depositorSCA":    "0xDepositorSCAWalletAddress",
    "depositorWalletId": "wallet_uuid_from_agent_status",
    "beneficiarySCA":  "0xBeneficiarySCAWalletAddress",
    "amount":          "200.00",
    "deadlineHours":   48,
    "condition":       "Delivery of 500 API credits confirmed",
    "webhookUrl":      "https://yourapp.com/webhooks/flare"
  }'

const response = await fetch("https://flarehq.xyz/api/escrow/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fhq_sec_YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    depositorSCA:     "0xDepositorSCAWalletAddress",
    depositorWalletId: "wallet_uuid_from_agent_status",
    beneficiarySCA:   "0xBeneficiarySCAWalletAddress",
    amount:           "200.00",
    deadlineHours:    48,
    condition:        "Delivery of 500 API credits confirmed",
    webhookUrl:       "https://yourapp.com/webhooks/flare",
  }),
});

const data = await response.json();
console.log(data.escrow.reference); // escrow_abc123_xyz789

Success Response

{
  "success": true,
  "escrow": {
    "reference":       "escrow_m5k2r1_a4b8c2",
    "amount":          200,
    "currency":        "USDC",
    "status":          "ACTIVE",
    "contractAddress": "0xEscrowContractAddress",
    "depositorSCA":    "0xDepositorSCAWalletAddress",
    "beneficiarySCA":  "0xBeneficiarySCAWalletAddress",
    "condition":       "Delivery of 500 API credits confirmed",
    "deadline":        "2025-07-16T14:00:00.000Z"
  },
  "txHash":      "0xabc123def456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
  "explorerUrl": "https://testnet.arcscan.app/tx/0xabc123def456789abcdef...",
  "message":     "200 USDC locked in escrow contract on Arc Testnet. Both parties must confirm to release.",
  "nextSteps": {
    "release": "POST /api/escrow/release { reference: \"escrow_m5k2r1_a4b8c2\", callerSCA: \"depositorOrBeneficiarySCA\" }",
    "dispute": "POST /api/escrow/dispute { reference: \"escrow_m5k2r1_a4b8c2\", callerSCA: \"...\", reason: \"...\" }",
    "status":  "GET /api/escrow/status?reference=escrow_m5k2r1_a4b8c2"
  }
}

Error Response — Insufficient Balance

{
  "success": false,
  "error": "Depositor wallet has insufficient USDC balance.",
  "hint": "Fund the depositor SCA wallet at https://faucet.circle.com — select ARC-TESTNET."
}

Escrow creation involves on-chain transactions that can take up to 75 seconds to confirm. Do not retry the request during this window — doing so may result in duplicate escrows and double-spending from the depositor’s wallet.

Overview

Payments

Escrow

Streaming

x402

Agents

Create On-Chain USDC Escrow — POST /api/escrow/create

Endpoint

Authentication

Request Body

Response

Examples

Success Response

Error Response — Insufficient Balance

​Endpoint

​Authentication

​Request Body

​Response

​Examples

​Success Response

​Error Response — Insufficient Balance

Endpoint

Authentication

Request Body

Response

Examples

Success Response

Error Response — Insufficient Balance