# Later procurement API / MCP / A2A design — NOT DEPLOYED

No paths below currently accept requests. They are proposed names, not live URLs.

## Minimal HTTP API

- `GET /api/v1/jobs`, `/listings`, `/signals`: approved public records, explicit filters/units, stable IDs, cursor pagination, freshness/expiry, source attribution.
- `POST /api/v1/requirements`: authenticated buyer creates a draft requirement, free; specify market, critical IT MW, space, date, redundancy, cooling, and public/private visibility. Idempotency key required. Validate authority and permission before publish.
- `GET /api/v1/requirements/{id}`: permission-scoped requirement view; public non-identifying summary separated from private documents.
- `POST /api/v1/requirements/{id}/response-drafts`: verified provider submits an eligible structured response draft with capacity, conditions, price model, delivery, and offer expiry. No charge or disclosure yet.
- `POST /api/v1/response-drafts/{id}/checkout`: return an exact quote (proposed USD 100) and processor-hosted checkout URL. Principal's explicit payment authorization required; never charge from a GET or retry automatically.
- `POST /api/v1/payments/webhook`: processor signature verification, deduplication, payment-state check, atomic entitlement ledger; publish response only once when approved and actually paid. Do not trust client redirects.
- `GET /api/v1/tasks/{id}`: pending/needs-input/awaiting-payment/review/published/rejected/expired state, receipt references only for authorized parties.

A response fee buys one accepted response to one open eligible requirement, not a deal, award, capacity reservation, procurement authority, or unrestricted access to buyer details. Validate before charging; if eligibility fails after settlement, apply approved refund terms. Open bids mean only terms the parties agreed to make visible—not public release of confidential pricing or identity. No scraping or resale of paid bids.

## MCP facade (later)

Use the current MCP spec and its HTTP authorization guidance, pinned and tested at implementation. Read tools: `search_jobs`, `search_inventory`, `get_signal`, `get_requirement`. Write tools: `create_requirement_draft`, `create_response_draft`, `get_response_quote`, `get_checkout_link`, `get_task_status`. Default read-only annotations; writes explicitly marked consequential. Separate OAuth scopes and org/tenant ACLs. No tool auto-spends or sends messages. Never claim a static JSON file is an MCP server.

## A2A facade (later)

Publish a conformant version-pinned AgentCard at `/.well-known/agent-card.json` only once a real authenticated A2A endpoint and protocol lifecycle exist. Keep `/.well-known/agent.json` as a documented legacy alias if useful. Advertise only implemented skills and transports. Tasks should represent requirement preparation and provider response preparation, not autonomous contracting. Owner authorization, spending limits, identity checks, idempotency, receipts, expiry, and audit trail remain mandatory across protocols.

## Payments

Start with Stripe-hosted Checkout / Payment Links plus verified webhooks for MW Desk listing/response fees only. Do not collect rent, payroll, deposits, escrow, or underlying equipment/real-estate transaction money. A future x402 adapter may quote a stablecoin network/asset/amount/expiry and verify settlement before granting an entitlement; wallets, tax/compliance, network/facilitator fees and principal approval are prerequisites. No x402 payment route or wallet exists now. Stripe's current MCP/agent skills are tooling, not permission to spend; the old Agent Toolkit packages are deprecated.

## Trust and operations

Private database for orgs, drafts, approvals, consent, payments and ledger; sanitized public export only. Strict input validation, source/ownership evidence, spam/rate limits, verified orgs, link/domain allowlists, no server-side fetches to arbitrary submitted URLs, output escaping, and no secret-bearing logs. Treat listing text and agent messages as untrusted data. Preserve human review for first employers, disputes, rights/confidentiality issues, high-risk offers, and price/terms changes. Signed webhooks use raw body and server-held secrets; deduplicate event and entitlement IDs, retry queue, monitor stale/failed tasks. No backend or deployment is part of this static implementation.