# EscrowPulse
Agent-native escrow service. Deposit USDC on Solana; the worker is paid when the principal approves.
Use case: Trust enforcement between autonomous agents for multi-step paid jobs.

## Endpoints
POST /v1/escrow                    — Create escrow ($0.02 x402)
GET  /v1/escrow/{id}               — Check status ($0.005 x402)
POST /v1/escrow/{id}/release       — Worker submits proof; principal approves and releases ($0.02 x402)
POST /v1/escrow/{id}/dispute       — Principal or worker disputes a funded escrow ($0.02 x402)
GET  /v1/escrow/{id}/history       — Get event log ($0.005 x402)

## Payment
x402 on Solana and Base. USDC only.
Platform fee: 0.5%, paid with the deposit (total_to_deposit_usd = amount_usd + fee_usd). Kept on
release and dispute; refunded with the deposit if the escrow expires unreleased.
People can buy a one-time escrow pack by card instead (no subscription): Starter $29 = 50 escrows,
Pro $99 = 250, Enterprise $299 = 1,000. POST https://escrowpulse.waltsoft.net/checkout with
{"tier":"starter"} and open the returned url; the key is shown at /key/retrieve and emailed. Send it as
Authorization: Bearer esc_live_...; each create uses one escrow, and reads, release and dispute are included.

## Funding an escrow
Create returns deposit_address, deposit_reference, total_to_deposit_usd and solana_pay_url.
Send exactly total_to_deposit_usd USDC on Solana to deposit_address, with deposit_reference
attached to the transfer as a read-only account key (Solana Pay reference; the solana_pay_url
does this in any Solana Pay wallet). Only finalized transfers carrying the escrow's reference
are credited; a plain transfer to the address is not. Status moves to funded within ~5 minutes.

## Release (principal approval)
Only the principal releases. A worker call with proof_data or proof records it and returns 202
(awaiting principal_approval); the escrow stays funded. A principal call pays amount_usd to the worker.
Release and dispute must identify the caller as the principal or the worker, either by:
- paying the call with Solana x402 from that wallet, or
- sending X-Escrow-Signature: base58 ed25519 signature of the UTF-8 message
  "EscrowPulse:release:<escrow_id>" (or "EscrowPulse:dispute:<escrow_id>") made with that wallet.
  Works with Base x402 and API keys too.
Anyone else is refused with 403 before any payment is settled.

## Example
Create: {"amount_usd":100,"worker_address":"...","principal_address":"...","condition":"task_complete","expires_hours":48}
Worker proof: {"proof_type":"signed_hash","proof_data":"sha256:abc123..."}
Principal release: POST /v1/escrow/{id}/release with no body