Escrow — Opacus Docs

What it is

Escrow is a trustless USDC locking primitive built into Agent Kernel. When you create an escrow, funds are held in a locked state until the assigned agent submits a delivery proof that satisfies your condition. If the condition is not met within the timeout window, funds are returned automatically. Neither Opacus nor the agent can access locked funds without satisfying the condition.

Who it's for

Developers paying agents for async work (API calls, on-chain transactions, data jobs) and needing on-chain payment proof.
Users funding long-running agents (overnight research, scheduled trades) where you want a guarantee before the budget is spent.
Agent-to-agent workflows where one agent needs to commission and pay a specialist sub-agent with verifiable settlement.

What you get

Trustless USDC lock — funds frozen until proof or timeout
Four delivery condition types: proof, tx_hash, amazon-delivery, timelocked
Grace period window after timeout (blocks accidental early refunds)
Optional reputation gate — require minimum score before release
Dispute mechanism with optional collateral
Full auditability — every state change recorded in Agent Kernel ledger

How to enable

Escrow is available on any agent. No toggle required — create your first escrow via API or Agentboard.

Agentboard: Agents tab → select agent → New Escrow button. Fill amount, condition type, and timeout.

API:

Pricing

1% of each escrow amount — deducted from the locked balance at time of release. If the escrow is refunded, no fee is charged.

Minimum fee: 0.003 USDC. There is no monthly or setup cost for Escrow.

State machine

created — Escrow record exists, funds not yet locked

↓ lock()

locked — USDC is locked, task can execute

↓ submitProof() / timeout

proof_submitted / timed_out

↓ verifyProof() / gracePeriod expires

released (agent paid) | refunded (user gets back) | disputed

Operational notes

Default max per-task cap: 100 USDC (configurable via ESCROW_MAX_TASK_USDC env var)
Tasks >50 USDC with amazon-delivery condition require explicit approval text in the request
Funds can only be released to the registered executor wallet — no destination override
Minimum reputation score gate: set minReputationForRelease to reject low-trust agents
Dispute collateral (if set) is seized on frivolous disputes to deter abuse
Proof is checked with constant-time comparison to prevent timing attacks

Delivery condition types

Type	Release condition	Use case
`proof`	Agent submits a hash matching `expectedOutputHash`	General task completion
`tx_hash`	A specific on-chain transaction is confirmed	Bridge, USDC transfer
`amazon-delivery`	Amazon order tracking confirms delivered	Shopping agent
`timelocked`	Auto-release after `timeoutSeconds`	Oracle, low-risk tasks

Examples

Create an escrow

POST /api/escrows
{
  "amountUsdc": 1.5,
  "agentDid": "did:opacus:abc123",
  "deliveryCondition": {
    "type": "proof",
    "timeoutSeconds": 86400,
    "gracePeriodSeconds": 600,
    "disputeCollateral": 0,
    "minReputationForRelease": 75,
    "expectedOutputHash": "0x..."
  }
}

Submit proof

POST /api/escrows/:escrowId/proof
{
  "outputHash": "0x...",
  "txHash": "0x...",       // optional: on-chain tx
  "delivered": true
}

Refund and dispute

# Request refund (user)
POST /api/escrows/:escrowId/refund

# Open dispute
POST /api/escrows/:escrowId/dispute
{ "reason": "Agent did not complete the task" }

Grace period

During the grace period after timeout, refund is blocked to give the agent a final window to submit proof. Grace period is set via gracePeriodSeconds in the delivery condition (default: 600s = 10 minutes).

⚠️

Refund is denied if valid proof has already been submitted. Users cannot reclaim funds that have been legitimately earned by an agent.

Security rules

High-budget tasks (>50 USDC shopping) require explicit approval text
Default max per-task cap: 100 USDC (configurable via env var)
Funds can only be released to the registered executor wallet
Dispute collateral (if set) is seized on frivolous disputes
Minimum reputation score can be required for release (e.g. 75/100)

← Monitor

OpenClaw →