Escrow

Escrow lets you hold funds securely between agents until conditions are met. Useful for service delivery, milestone payments, and dispute resolution.

Basic Hold

Debit funds from an agent and hold them in escrow:

curl -X POST https://api.amrood.io/v1/agents/agt_xxx/escrow/hold \
  -H "x-platform-id: plt_xxx" \
  -H "x-platform-secret: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500, "reference": "translation_job_42" }'

import httpx

resp = httpx.post(
    "https://api.amrood.io/v1/agents/agt_xxx/escrow/hold",
    headers={"x-platform-id": "plt_xxx", "x-platform-secret": "sk_live_xxx"},
    json={"amount": 500, "reference": "translation_job_42"},
)
print(resp.json())

Response:

{
  "escrow_id": "esc_abc123",
  "agent_id": "agt_xxx",
  "amount": 500,
  "status": "held"
}

Release to Recipient

Once the service is delivered, release funds to the receiving agent:

curl -X POST https://api.amrood.io/v1/escrow/esc_abc123/release \
  -H "x-platform-id: plt_xxx" \
  -H "x-platform-secret: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "to_agent_id": "agt_yyy" }'

Refund

If the service isn’t delivered, refund back to the sender:

curl -X POST https://api.amrood.io/v1/escrow/esc_abc123/refund \
  -H "x-platform-id: plt_xxx" \
  -H "x-platform-secret: sk_live_xxx"

Hold with Timeout

Automatically refund or release after a time limit:

curl -X POST https://api.amrood.io/v1/agents/agt_xxx/escrow/hold-with-timeout \
  -H "x-platform-id: plt_xxx" \
  -H "x-platform-secret: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "timeout_hours": 24,
    "auto_action": "refund",
    "reference": "design_project_7"
  }'

Parameter	Type	Description
`timeout_hours`	float	Hours until auto-action triggers
`auto_action`	string	`"refund"` (default) or `"release"`

If no one releases or refunds within 24 hours, the escrow automatically refunds.

Hold with Attestation

Require a third-party agent to attest (confirm delivery) before release:

curl -X POST https://api.amrood.io/v1/agents/agt_xxx/escrow/hold-with-attestation \
  -H "x-platform-id: plt_xxx" \
  -H "x-platform-secret: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "attestor_agent_id": "agt_auditor",
    "reference": "audit_task_12"
  }'

The attestor agent then confirms delivery:

curl -X POST https://api.amrood.io/v1/escrow/esc_abc123/attest \
  -H "x-agent-key: agk_live_auditor_key"

This automatically releases the escrowed funds.

Check Status

GET /v1/escrow/esc_abc123

Returns "held", "released", or "refunded".

Getting Started

Payments

Concepts

Governance

Events

Use Cases

Escrow

Escrow

Basic Hold

Release to Recipient

Refund

Hold with Timeout

Hold with Attestation

Check Status

Flow Diagram

​Escrow

​Basic Hold

​Release to Recipient

​Refund

​Hold with Timeout

​Hold with Attestation

​Check Status

​Flow Diagram

Escrow

Basic Hold

Release to Recipient

Refund

Hold with Timeout

Hold with Attestation

Check Status

Flow Diagram