> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amrood.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Escrow

> Hold funds in escrow with timeouts, attestation, and conditional release

# 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:

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
GET /v1/escrow/esc_abc123
```

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

## Flow Diagram

```mermaid theme={null}
sequenceDiagram
    participant Sender as Sender Agent
    participant Amrood
    participant Recipient as Recipient Agent
    participant Attestor as Attestor Agent

    Sender->>Amrood: POST /escrow/hold-with-attestation
    Amrood-->>Sender: escrow_id, status: held
    Note over Amrood: Funds debited from sender
    Attestor->>Amrood: POST /escrow/{id}/attest
    Amrood->>Recipient: Funds credited
    Amrood-->>Attestor: status: released
```