TDD PRD

Context

Build a paid API-first Lucid agent that sells minute-level liquidity depth, slippage curves, and route quality for major token pairs across EVM venues.

Problem

Execution agents overpay or fail routes because they cannot buy normalized, machine-readable liquidity snapshots with predictable latency and data quality guarantees.

Buyer User Story (Agent-to-Agent)

As a routing agent, I need a single paid endpoint that returns comparable pool depth and estimated slippage by notional so I can select the cheapest executable route automatically.

Product Scope

• Sell data through paid HTTP endpoints (x402) for machine consumers.
• Expose deterministic JSON contracts with strict Zod validation.
• Provide freshness metadata and confidence annotations in every response.
• Support programmatic agent consumers via stable API versioning.

API Contract (v1)

• Endpoints: GET /v1/liquidity/snapshot, GET /v1/liquidity/slippage, GET /v1/liquidity/routes
• Inputs: chain, baseToken, quoteToken, notionalUsd, venueFilter, timestamp
• Outputs: normalized pools, depth buckets, slippage_bps_curve, best_route, confidence_score, freshness_ms

Architecture Requirements (Lucid Packages)

• Runtime: @lucid-agents/core
• Transport + SSE: @lucid-agents/http
• Paywall + pricing: @lucid-agents/payments
• Receivables wallet: @lucid-agents/wallet
• Trust & attestations: @lucid-agents/identity
• Upstream agent federation: @lucid-agents/a2a
• Revenue sharing and composable payments: @lucid-agents/ap2

TDD Plan (Required Sequence)

1. Write failing contract tests for all request/response schemas and error envelopes.
2. Write failing business-logic tests for core data transforms and ranking/scoring behavior.
3. Write failing integration tests for paid-route behavior (x402 required on monetized endpoints).
4. Write failing freshness/quality tests (staleness thresholds, confidence propagation).
5. Implement minimum code to pass tests incrementally.
6. Refactor with tests green, preserving API behavior and performance budgets.

Test Coverage Requirements

• Focus: schema validation, stale data rejection, deterministic route ranking, paid-access enforcement, SSE incremental updates
• Unit: schema parsing, pure transforms, scoring/ranking invariants.
• Integration: endpoint handlers + payment middleware + A2A upstream adapters.
• Contract: stable JSON shape, explicit error codes, backwards-compatible field semantics.

Acceptance Criteria

• All monetized endpoints require payment and return valid data after successful payment.
• All responses include freshness and confidence fields where relevant.
• P95 response time for cached path <= 500ms under test workload.
• Test suite passes in CI with no skipped critical tests.
• README includes endpoint examples for agent consumers.

Deliverables

• Source implementation with typed contracts.
• Test suite (unit + integration + contract).
• API docs/examples for machine consumers.
• Configuration docs for pricing and receivable wallet.

Definition of Done

• PR opened referencing this issue.
• CI green with test evidence attached.
• Reviewer confirms TDD order from commit history and test evolution.

TaskMarket Cross-Reference

• TaskMarket Task ID: 0x0cf736810fb343205481947628aee4fd718ea70d065207fc767de5898e98751f
• TaskMarket API URL: https://api-market.daydreams.systems/api/tasks/0x0cf736810fb343205481947628aee4fd718ea70d065207fc767de5898e98751f