# EscrowPulse Agent Integration Guide

Agent-native USDC escrow on Solana. Deposit funds into a vault, do the job, release on proof.

## Overview

EscrowPulse is an HTTP escrow service built for autonomous agents. It uses the x402 payment protocol — agents pay per API call in USDC (Solana or Base), no signup, no API key required.

**Core flow:**
1. Principal agent creates an escrow vault (POST /v1/escrow)
2. Principal sends USDC to the vault address (on-chain)
3. Worker agent does the job
4. Worker submits proof (POST /v1/escrow/{id}/release)
5. EscrowPulse verifies proof, transfers USDC to worker

## Authentication

### x402 (agents — no signup required)

All write operations require an x402 USDC micropayment. Use any x402-compatible client:

```javascript
import { fetch402 } from "x402-fetch";

// Create an escrow
const response = await fetch402("https://escrowpulse.waltsoft.net/v1/escrow", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    amount_usd: 100,
    worker_address: "BnHLApK6...",
    condition: "task_complete",
    expires_hours: 48,
  }),
});
```

x402 payment networks: `solana` (USDC-SPL), `base` (USDC-ERC20).

### API key (humans — Stripe subscription)

Subscribe at [escrowpulse.waltsoft.net/#pricing](https://escrowpulse.waltsoft.net/#pricing). Pass your key as:

```
Authorization: Bearer esc_live_<your_key>
```

No x402 required with a valid API key.

## Endpoints

| Method | Path                          | x402 price | Description             |
|--------|-------------------------------|-----------|-------------------------|
| POST   | `/v1/escrow`                  | $0.02     | Create escrow vault     |
| GET    | `/v1/escrow/{id}`             | $0.005    | Check vault status      |
| POST   | `/v1/escrow/{id}/release`     | $0.02     | Submit proof → release  |
| POST   | `/v1/escrow/{id}/dispute`     | $0.02     | Flag a dispute          |
| GET    | `/v1/escrow/{id}/history`     | $0.005    | Get event log           |
| GET    | `/health`                     | free      | Liveness check          |
| GET    | `/.well-known/x402`           | free      | x402 protocol manifest  |
| GET    | `/.well-known/agent.json`     | free      | Agent capability descriptor |

## Example flows

### Create escrow → monitor → release

```bash
# Step 1: Create escrow (x402 payment required)
curl -H "X-PAYMENT: <x402_payment>" \
     -H "Content-Type: application/json" \
     https://escrowpulse.waltsoft.net/v1/escrow \
     -d '{
       "amount_usd": 500,
       "worker_address": "BnHLApK6...",
       "condition": "procurement_report_delivered",
       "description": "Vendor analysis — 10 suppliers",
       "expires_hours": 72,
       "principal_address": "GsKr5q9T..."
     }'
# Response: { "escrow_id": "esc_abc123", "status": "awaiting_deposit",
#             "deposit_address": "EscrowVault7x...", "total_to_deposit_usd": 502.50 }

# Step 2: Principal sends USDC to deposit_address (on Solana mainnet)
# Amount: total_to_deposit_usd in USDC atomic units (6 decimals)
# Use any Solana wallet or the Solana Web3.js / CDP SDK

# Step 3: Poll status (lightweight read)
curl -H "X-PAYMENT: <x402_payment>" \
     https://escrowpulse.waltsoft.net/v1/escrow/esc_abc123
# Wait for { "status": "funded" }

# Step 4: Worker submits proof (x402 payment required)
curl -H "X-PAYMENT: <x402_payment>" \
     -H "Content-Type: application/json" \
     https://escrowpulse.waltsoft.net/v1/escrow/esc_abc123/release \
     -d '{
       "proof_type": "signed_hash",
       "proof_data": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f..."
     }'
# Response: { "status": "released", "tx_release": "5Kz7...", "amount_usd": 500.00 }
```

### Dispute flow

```bash
# Either party can dispute within the expiry window
curl -H "X-PAYMENT: <x402_payment>" \
     -H "Content-Type: application/json" \
     https://escrowpulse.waltsoft.net/v1/escrow/esc_abc123/dispute \
     -d '{ "reason": "Deliverable does not match condition" }'
# Funds locked for 72h. After 72h with no resolution, returns to principal.
```

## Escrow state machine

```
awaiting_deposit → funded → released
                          → disputed
                          → expired
                          → expired_refunded
```

- `awaiting_deposit`: vault created, waiting for USDC deposit
- `funded`: USDC received, ready for work
- `released`: proof accepted, funds sent to worker
- `disputed`: in dispute window (72h lock)
- `expired`: deposit never arrived, vault expired
- `expired_refunded`: funded but expired; USDC returned to principal

## Pricing

| Operation | x402 cost | Notes |
|-----------|-----------|-------|
| Create escrow | $0.02 | Write operation |
| Check status | $0.005 | Read operation |
| Release funds | $0.02 | Write operation |
| Flag dispute | $0.02 | Write operation |
| Platform fee | 0.5% | Deducted from escrowed amount on release |

**Subscription tiers** (lower platform fee):
- Starter: $29/mo, 50 escrows, 0.5% fee
- Pro: $99/mo, 250 escrows, 0.35% fee
- Enterprise: $299/mo, 1000 escrows, 0.25% fee

## Error codes

| HTTP | Code | Meaning |
|------|------|---------|
| 402 | `payment_required` | x402 payment missing or insufficient |
| 400 | `invalid_input` | Malformed request body |
| 404 | `not_found` | Escrow ID does not exist |
| 409 | `conflict` | State transition not allowed (e.g., release on unfunded escrow) |
| 410 | `expired` | Escrow has passed its expiry time |
| 429 | `rate_limited` | 10 req/min per IP exceeded |
| 500 | `internal_error` | Lambda error; x402 fee refunded to balance |

## x402 protocol notes

- x402 version: 2
- Accepted networks: `solana`, `base`
- Asset: USDC (6 decimals)
- Fee payer: read live from `$.well-known/x402` — rotates every ~30s, never hardcode
- Bazaar: `extensions.bazaar.routeTemplate` is injected server-side for CDP discovery

## Links

- Landing: [https://escrowpulse.waltsoft.net](https://escrowpulse.waltsoft.net)
- x402 protocol: [https://x402.org](https://x402.org)
- waltsoft agent fleet: [https://agents.waltsoft.net/products/escrowpulse](https://agents.waltsoft.net/products/escrowpulse)
- LLM discovery: [https://escrowpulse.waltsoft.net/llms.txt](https://escrowpulse.waltsoft.net/llms.txt)
- OpenAPI spec: [https://escrowpulse.waltsoft.net/openapi.json](https://escrowpulse.waltsoft.net/openapi.json)
- Agent descriptor: [https://escrowpulse.waltsoft.net/.well-known/agent.json](https://escrowpulse.waltsoft.net/.well-known/agent.json)