POST /api/v1/escrows endpoint doesn't exist - documented purchase method broken

[crtahlin]

Problem

The skill detail page UI instructs buyers to purchase via:

API: POST /api/v1/escrows

However, this endpoint does not accept POST requests:

curl -X POST "https://agents.datafund.io/api/v1/escrows" \
  -H "Content-Type: application/json" \
  --data '{"skill_id":"...","buyer":"0x..."}'

Response:

<pre>Cannot POST /api/v1/escrows</pre>

Verification via OPTIONS:

access-control-allow-methods: GET, OPTIONS

The endpoint is read-only. POST is not implemented.

Also Tested

• POST /api/v1/skills/:id/buy → 404
• POST /api/v1/escrows/fund → 404

No API endpoint exists to create or fund an escrow.

Impact

• Complete blocker: Users following UI instructions cannot purchase
• The documented purchase flow is non-functional
• Only workarounds: CLI tool or direct smart contract interaction
• Undermines trust in platform documentation

Expected Behavior

One of:

1. POST /api/v1/escrows should create/fund an escrow
2. POST /api/v1/skills/:id/buy should initiate purchase
3. OR UI should show accurate instructions for actual purchase method

Relation to Other Issues

This is distinct from #9 (skills not linked to escrows) and #10 (no wallet UI). Even if those were fixed, users still couldn't purchase via the documented API method.

Suggested Fix

Implement POST /api/v1/escrows endpoint that:

1. Accepts skill_id and buyer address
2. Validates skill exists and has content
3. Creates escrow record (or returns existing)
4. Returns escrow details for on-chain funding

OR update UI to show accurate purchase instructions.

Acceptance Criteria

• POST /api/v1/escrows endpoint exists and works
• OR UI updated with working purchase instructions
• API documentation matches actual endpoints

[crtahlin]

Architecture Question: What should POST /api/v1/escrows do?

@plur9 The UI currently shows "POST /api/v1/escrows" as the purchase method, but this endpoint doesn't exist.

After investigating the architecture, I found that escrows are created on-chain via the DataEscrowV3 smart contract. The agents-api only indexes blockchain events - it doesn't create escrows.

What was the intended behavior?

1. Option A: Transaction Helper

   • Endpoint returns unsigned transaction data
   • Frontend submits to blockchain via user's wallet
   • Similar pattern to how Uniswap/OpenSea work

2. Option B: Server-side Creation

   • Server has a wallet and creates escrows on-chain
   • Requires server to hold funds or use meta-transactions
   • More centralized approach

3. Option C: Update UI Only

   • Remove "POST /api/v1/escrows" from UI
   • Point users to CLI (sx escrows create) or SDK
   • Document the actual on-chain workflow

4. Option D: Off-chain Intent

   • Store "purchase intent" off-chain
   • Seller sees buyer interest
   • Actual escrow still created on-chain separately

Which approach was intended? This affects how we implement the fix.

[crtahlin]

Addressed in PR #38