Skip to main content

​
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" }'
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"
  }'
ParameterTypeDescription
timeout_hoursfloatHours until auto-action triggers
auto_actionstring"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".

​
Flow Diagram