Escrows API

Escrows hold funds in a secure on-chain account until predefined conditions are met. They provide a trust layer between agents and merchants for high-value or conditional transactions. Escrows can be released (funds go to merchant), refunded (funds return to vault), or disputed.

Create Escrow#

Request Body#

| Field | Type | Required | Description | |---|---|---|---| | vault_id | string | Yes | The vault funding the escrow | | agent_id | string | No | The agent that initiated the escrow | | merchant_id | string | No | The merchant that will receive funds upon release | | amount | string | Yes | Amount in decimal USDC (e.g., "500.00") | | currency | string | No | Currency code (default: "USDC") | | condition_type | string | Yes | Type of release condition (see below) | | condition_data | object | No | Additional data for the condition | | expires_in_hours | number | No | Hours until the escrow expires (default: 24) |

Condition Types#

| Type | Description | |---|---| | time_release | Automatically releases after a specified time | | oracle_confirmation | Releases when an oracle confirms an external event | | multi_sig_approval | Requires multiple signature approvals to release | | delivery_confirmation | Releases when delivery is confirmed by the buyer |

Example Request#

{
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "agt_550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "mrc_660e8400-e29b-41d4-a716-446655440000",
  "amount": "500.00",
  "currency": "USDC",
  "condition_type": "delivery_confirmation",
  "condition_data": {
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups"
  },
  "expires_in_hours": 72
}

Response#

{
  "escrow_id": "esc_990e8400-e29b-41d4-a716-446655440000",
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "agt_550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "mrc_660e8400-e29b-41d4-a716-446655440000",
  "amount": "500.00",
  "currency": "USDC",
  "condition_type": "delivery_confirmation",
  "condition_data": {
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups"
  },
  "status": "funded",
  "expires_at": "2025-01-18T10:30:00.000Z",
  "created_at": "2025-01-15T10:30:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | vault_not_found | The specified vault does not exist | | vault_frozen | The vault is currently frozen | | policy_violation | Amount must be greater than 0 | | insufficient_balance | The vault does not have enough funds |

Get Escrow#

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The escrow ID |

Response#

{
  "escrow_id": "esc_990e8400-e29b-41d4-a716-446655440000",
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "agt_550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "mrc_660e8400-e29b-41d4-a716-446655440000",
  "amount": "500.00",
  "currency": "USDC",
  "condition_type": "delivery_confirmation",
  "condition_data": {
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups"
  },
  "status": "funded",
  "escrow_address": "esc_onchain_addr_abc123...",
  "tx_hash_fund": "5UfDuX...",
  "tx_hash_release": null,
  "expires_at": "2025-01-18T10:30:00.000Z",
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | escrow_not_found | No escrow exists with the given ID |

List Escrows#

Query Parameters#

| Parameter | Type | Required | Description | |---|---|---|---| | vault_id | string | Yes | The vault ID to list escrows for | | status | string | No | Filter by status: funded, released, refunded, disputed | | limit | integer | No | Number of results (default 50, max 200) | | cursor | string | No | Pagination cursor |

Response#

{
  "escrows": [
    {
      "escrow_id": "esc_990e8400...",
      "vault_id": "550e8400...",
      "agent_id": "agt_550e8400...",
      "merchant_id": "mrc_660e8400...",
      "amount": "500.00",
      "currency": "USDC",
      "condition_type": "delivery_confirmation",
      "status": "funded",
      "expires_at": "2025-01-18T10:30:00.000Z",
      "created_at": "2025-01-15T10:30:00.000Z"
    }
  ],
  "has_more": false
}

Release Escrow#

Releases the held funds to the merchant's wallet. The escrow must be in funded status and must not have expired.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The escrow ID |

Response#

{
  "escrow_id": "esc_990e8400-e29b-41d4-a716-446655440000",
  "status": "released",
  "tx_hash_release": "sim_rel_abc123...",
  "released_at": "2025-01-16T14:00:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | escrow_not_found | No escrow exists with the given ID | | escrow_already_released | The escrow funds have already been released | | escrow_expired | The escrow has passed its expiration time | | policy_violation | Cannot release escrow in its current status |

Refund Escrow#

Returns the held funds to the originating vault. The escrow must be in funded or disputed status.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The escrow ID |

Response#

{
  "escrow_id": "esc_990e8400-e29b-41d4-a716-446655440000",
  "status": "refunded",
  "refunded_at": "2025-01-16T14:00:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | escrow_not_found | No escrow exists with the given ID | | escrow_already_released | The escrow funds have already been released | | policy_violation | Cannot refund escrow in its current status |

Dispute Escrow#

Marks an escrow as disputed. A disputed escrow can be refunded but cannot be released until the dispute is resolved. The escrow must be in funded status.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The escrow ID |

Request Body (Optional)#

| Field | Type | Required | Description | |---|---|---|---| | reason | string | No | Reason for the dispute (defaults to "Dispute raised") |

Example Request#

{
  "reason": "Product was not as described"
}

Response#

{
  "escrow_id": "esc_990e8400-e29b-41d4-a716-446655440000",
  "status": "disputed",
  "reason": "Product was not as described",
  "disputed_at": "2025-01-16T14:00:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | escrow_not_found | No escrow exists with the given ID | | policy_violation | Cannot dispute escrow in its current status |

Escrow Statuses#

| Status | Description | |---|---| | funded | Escrow is active with funds locked | | released | Funds have been sent to the merchant | | refunded | Funds have been returned to the vault | | disputed | A dispute has been raised; can be refunded but not released |