iwant.fyi demand-side protocol

Abstract

The iwant.fyi demand-side protocol defines a standard way for AI agents to express structured purchase intent on behalf of a user, receive ranked matches from supply across multiple sources, and report outcomes back to the demand origin.

Existing agentic commerce protocols are supply-side: ACP and UCP define how an agent completes a purchase at a merchant, AP2 defines how payment is authorized, MCP defines how tools and data are accessed. None of them define how an agent expresses what its user wants in a structured, machine-matchable form, or how that demand persists across sessions and gets fulfilled across multiple sources.

This protocol fills that gap. It is small, MCP-native, transport-flexible, and intentionally agnostic about who matches the demand, who fulfills it, and how money moves.

Status of this document

This is a draft published for public comment. The protocol is implemented today by iwant.fyi as the reference implementation. Feedback, issues, and proposed extensions can be opened against this document.

The protocol is published under the Apache License 2.0. Anyone may implement, fork, extend, or commercialize the protocol or compatible implementations.

1. Introduction

1.1 The problem

Today, when a user expresses purchase intent inside an AI chat — "I need a torque wrench under $150, calibrated within the last two years" — the agent has poor options:

1. Run an unstructured web search and parse merchant pages (brittle, slow, often illegal).
2. Call a single retailer's API directly (limited inventory, no cross-merchant comparison).
3. Use a supply-side protocol like ACP/UCP, which only covers partner merchants and only at the checkout end of the funnel.

None of these treat the user's articulated demand as a first-class object. Each chat session re-derives the user's intent from scratch. Demand doesn't persist. Constraints can't be reliably communicated. Outcomes don't flow back to the demand origin.

1.2 What the iwant.fyi demand-side protocol does

The iwant.fyi demand-side protocol defines:

• A canonical Want object — structured purchase intent, durable beyond a single chat session.
• A vocabulary of Constraints — machine-evaluable filters that go beyond keyword search (price ranges, condition floors, locations, deadlines, specs).
• A Match response shape — how supply across multiple sources is presented back to the agent.
• Outcome events — how clicks, purchases, and abandonments attribute back to the originating agent and accumulate into demand signal.
• An MCP tool surface — the canonical way to call a iwant.fyi demand-side protocol implementation.
• An HTTP/REST fallback — for agents that don't speak MCP.

1.3 What it does NOT do

The iwant.fyi demand-side protocol does not:

• Process payments — that's ACP, AP2, or direct merchant flows.
• Define a checkout experience — once a Match is selected, the agent hands off to the merchant or to a checkout protocol.
• Mandate a specific matching algorithm — implementations can compete on match quality.
• Mandate a specific business model — implementations can be free, affiliate-funded, ad-supported, or paid.
• Replace MCP — it layers on top of MCP as the transport.

1.4 Design principles

1. Small. v1 is intentionally minimal. Negotiation, escrow, multi-party payment, identity verification — all deferred.
2. Composable. iwant.fyi demand-side protocol complements ACP, UCP, AP2, and MCP rather than competing with them. A typical flow: user → agent → iwant.fyi demand-side protocol (find the right thing) → ACP/UCP (checkout) → AP2 (payment authorization).
3. Source-agnostic. A compliant implementation can pull supply from anywhere — affiliate feeds, direct APIs, scraped catalogs (with proper licensing), user-generated listings, anywhere.
4. Identity-light. Users remain anonymous to the protocol by default. The originating agent is identified for attribution and outcome routing.
5. Open and forkable. Anyone can run a iwant.fyi demand-side protocol server. Anyone can extend the constraint vocabulary. Implementations are free to compete.

2. Relationship to other protocols

The mental model: iwant.fyi demand-side protocol is upstream of all the supply/checkout protocols. Agents express demand here, then hand off to whichever supply/payment protocol the user-selected match requires.

3. Terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

• Agent — Software acting on behalf of a user. Typically an AI assistant.
• Want — A structured purchase intent expressed by an agent on behalf of a user.
• Constraint — A machine-evaluable filter attached to a Want.
• Match — A specific piece of supply (a product or service listing) that satisfies a Want.
• Supply Source — A merchant, marketplace, or other origin of matchable inventory.
• Implementation — A server that speaks the iwant.fyi demand-side protocol. The iwant.fyi MCP server is the reference Implementation.
• Origin Agent — The agent that first created a Want. Outcomes attribute back to this agent.

4. The Want object

A Want is the central data structure. It represents one piece of structured purchase intent.

4.1 Required fields

{
  "id": "string (UUID v4)",
  "protocol_version": "1.0",
  "title": "string (5–200 chars)",
  "price_cents": "integer (>= 0)",
  "price_currency": "string (ISO 4217, e.g. \"USD\")"
}

• id — Implementation-assigned UUID. Stable across the Want's lifetime.
• protocol_version — The iwant.fyi demand-side protocol version this Want adheres to. v1 implementations MUST accept "1.0".
• title — Short, user-facing description. Length 5–200 characters. MUST be a single line.
• price_cents — The buyer's stated budget or willingness-to-pay, in the smallest unit of price_currency. For a $150 budget in USD, price_cents = 15000.
• price_currency — ISO 4217 currency code.

4.2 Optional fields

{
  "description": "string (max 2000)",
  "category": "goods | services | other",
  "vertical": "string (free-form, recommended values below)",
  "mode": "new | used | any",
  "location": { "text": "string", "lat": number, "lng": number, "radius_km": number },
  "constraints": { "rules": {...}, "negotiable": [...], "auto_accept": {...} },
  "origin": { "agent_id": "string", "agent_name": "string", "session_id": "string" },
  "expires_at": "string (ISO 8601)",
  "created_at": "string (ISO 8601)",
  "updated_at": "string (ISO 8601)"
}

category

One of goods, services, other. Implementations SHOULD use this for top-level routing. The protocol does not define richer top-level categories in v1.

vertical

A free-form hint identifying a more specific vertical within category. Recommended values for v1 (extensible by implementations):

• tools — hand tools, power tools, hardware, fasteners
• auto_parts — vehicle parts and components
• outdoor — camping, hiking, hunting, fishing
• kitchen — cooking equipment, knives, small appliances
• electronics — consumer electronics
• home_services — plumbing, HVAC, cleaning, moving
• professional_services — legal, accounting, design

Implementations MAY define additional vertical values. Wants without a vertical SHOULD still match within category.

mode

One of new, used, any. This is the buyer's preference for supply mode (catalog-driven vs reverse-auction / peer-to-peer). Default if omitted: any.

• new — Buyer prefers catalog supply from merchants.
• used — Buyer prefers used / peer-to-peer supply.
• any — Buyer accepts either; Implementation MAY rank but MUST return both.

location

{
  "text": "Brooklyn, NY",
  "lat": 40.6782,
  "lng": -73.9442,
  "radius_km": 25
}

All sub-fields OPTIONAL. text is the buyer's stated location (city, neighborhood, postal code, etc.). lat/lng are coordinates if known. radius_km is the maximum acceptable distance for location-relevant supply (mainly used goods, services). Default radius if omitted: implementation-defined (50km is recommended for mode: used; ignored for mode: new unless explicitly set).

constraints

The machine-evaluable filter object. See Section 5.

origin

{
  "agent_id": "string",
  "agent_name": "string",
  "session_id": "string"
}

The agent that originated this Want. All sub-fields OPTIONAL but RECOMMENDED.

• agent_id — Stable identifier of the originating agent (e.g., an MCP agent API key prefix, an OAuth client ID).
• agent_name — Human-readable agent name for display.
• session_id — Opaque identifier for the originating session, useful for grouping related Wants.

Outcomes (clicks, purchases) MUST attribute back to origin.agent_id when present.

expires_at

ISO 8601 timestamp. If present, Implementations MUST NOT surface the Want as "open" past this time. If absent, Implementation default expiration applies (RECOMMENDED: 30 days).

created_at, updated_at

ISO 8601 timestamps set by the Implementation.

4.3 Example Want

{
  "id": "8f3c2e10-3b4a-4d2e-9f8c-1a2b3c4d5e6f",
  "protocol_version": "1.0",
  "title": "Torque wrench, 1/4\" drive, 25–100 ft-lb",
  "description": "Calibrated within last 2 years. Open to new or used in good condition. Need by next weekend.",
  "category": "goods",
  "vertical": "tools",
  "mode": "any",
  "price_cents": 15000,
  "price_currency": "USD",
  "location": {
    "text": "Brooklyn, NY",
    "lat": 40.6782,
    "lng": -73.9442,
    "radius_km": 50
  },
  "constraints": {
    "rules": {
      "price_max": 15000,
      "condition_min": "good",
      "deadline": "2026-05-31T00:00:00Z",
      "specs": {
        "drive_size": "1/4\"",
        "torque_range_ftlb": [25, 100],
        "calibration_within_days": 730
      }
    },
    "negotiable": ["price_max", "deadline"],
    "auto_accept": null
  },
  "origin": {
    "agent_id": "claude_anthropic_001",
    "agent_name": "Claude (anthropic)",
    "session_id": "sess_abc123"
  },
  "expires_at": "2026-06-19T00:00:00Z",
  "created_at": "2026-05-19T15:00:00Z"
}

5. Constraint vocabulary

The constraints.rules object holds typed filters. v1 defines the following keys; implementations MAY extend with namespaced custom keys (e.g., "x_iwantfyi_priority": "high").

5.1 Pricing constraints

5.2 Condition constraints

5.3 Time constraints

5.4 Brand and provenance

5.5 Location

Location is also in the Want's top-level location object, but constraints can sharpen:

5.6 Vertical-specific specs

Vertical-specific constraints live under constraints.rules.specs as a free-form object. Implementations SHOULD support common patterns:

For vertical: auto_parts:

"specs": {
  "year_make_model": { "year": 2018, "make": "Honda", "model": "Civic", "trim": "EX" },
  "vin": "1HGFA16526L000000",
  "part_number": "string",
  "oem_required": true
}

For vertical: tools:

"specs": {
  "drive_size": "1/4\"",
  "voltage": 18,
  "torque_range_ftlb": [25, 100],
  "calibration_within_days": 730,
  "cordless_required": false
}

For vertical: outdoor:

"specs": {
  "capacity_persons": 2,
  "weight_max_grams": 1500,
  "temperature_rating_f": 20,
  "season": "3-season"
}

Implementations SHOULD document their supported spec keys per vertical. Unknown spec keys SHOULD be treated as "informational, not filtering" rather than rejecting the Want.

5.7 Negotiable fields and auto-accept

"constraints": {
  "rules": { ... },
  "negotiable": ["price_max", "deadline", "shipping_max_cents"],
  "auto_accept": {
    "price_lte": 12000,
    "condition_min": "like-new",
    "seller_trust_gte": 0.85
  }
}

• negotiable — Array of constraint keys the buyer is willing to flex on. Implementations MAY surface these to seller agents for counter-offers.
• auto_accept — Rules under which the Implementation MAY auto-accept a Match without further agent interaction. All conditions in auto_accept must be satisfied. v1 implementations MAY ignore this object; v2 makes it normative for negotiation.

6. The Match response

When an agent queries for matches against a Want, the Implementation returns a Match response.

6.1 Response shape

{
  "want_id": "string",
  "matches": [Match, ...],
  "match_count": integer,
  "sources_consulted": [string, ...],
  "generated_at": "ISO 8601"
}

6.2 Match object

{
  "id": "string",
  "source": "string",
  "source_id": "string",
  "title": "string",
  "description": "string (optional)",
  "price_cents": integer,
  "price_currency": "string",
  "shipping_cents": integer,
  "total_price_cents": integer,
  "condition": "new | like-new | good | fair | used | unknown",
  "mode": "new | used",
  "location": "string (optional)",
  "images": [string, ...],
  "url": "string (REQUIRED — link to fulfill)",
  "direct_url": "string (optional — unwrapped merchant URL for verification)",
  "score": number,
  "reasons": [string, ...],
  "attributes": object,
  "supply_metadata": object
}

• id — Implementation-assigned identifier for this match instance.
• source — Origin of the supply (e.g., "cj", "impact", "shopify", "ebay", "native").
• source_id — Source-specific product identifier.
• url — The URL the agent SHOULD surface to the user. This MAY include affiliate tracking by the Implementation; agents MUST NOT strip tracking parameters.
• direct_url — Optional, the unwrapped merchant URL. Useful for verification or for agents whose users prefer direct merchant relationships.
• score — Match quality from 0 to 1. Implementation-defined scoring. v1 does not mandate an algorithm.
• reasons — Human-readable strings explaining why this match scored. Helps agents explain to users.
• attributes — Source-specific fields (brand, manufacturer, GTIN, part_number, etc.). Free-form; agents MAY display.
• supply_metadata — Implementation- or source-specific metadata (refresh timestamp, inventory hint, seller trust score, etc.).

6.3 Ranking

Matches MUST be returned in descending score order. Implementations SHOULD return at most 50 matches per response by default; agents MAY paginate via implementation-specific mechanisms.

6.4 Example response

{
  "want_id": "8f3c2e10-3b4a-4d2e-9f8c-1a2b3c4d5e6f",
  "matches": [
    {
      "id": "match_001",
      "source": "cj",
      "source_id": "home-depot-sku-12345",
      "title": "Husky 1/4\" Drive Torque Wrench 25-100 ft-lb",
      "price_cents": 8999,
      "price_currency": "USD",
      "shipping_cents": 0,
      "total_price_cents": 8999,
      "condition": "new",
      "mode": "new",
      "url": "https://www.anrdoezrs.net/links/PUB/.../homedepot.com/p/12345",
      "direct_url": "https://www.homedepot.com/p/12345",
      "score": 0.87,
      "reasons": ["price under budget", "exact drive size", "torque range match"],
      "attributes": {
        "brand": "Husky",
        "manufacturer_warranty_months": 12
      },
      "supply_metadata": {
        "feed_refresh": "2026-05-19T08:00:00Z",
        "affiliate_network": "cj"
      }
    },
    {
      "id": "match_002",
      "source": "ebay",
      "source_id": "ebay-listing-789",
      "title": "Snap-on TQR100 Torque Wrench (calibrated 2025)",
      "price_cents": 12500,
      "condition": "like-new",
      "mode": "used",
      "url": "https://rover.ebay.com/rover/1/.../itm/789",
      "score": 0.81,
      "reasons": ["calibrated within 1 year", "premium brand", "local pickup available"]
    }
  ],
  "match_count": 2,
  "sources_consulted": ["cj", "ebay", "shopify"],
  "generated_at": "2026-05-19T15:01:00Z"
}

7. Outcome events

After a Match is surfaced to the user, the agent SHOULD report outcome events back to the Implementation. This closes the demand-signal loop.

7.1 Event shape

{
  "want_id": "string",
  "match_id": "string",
  "event": "viewed | clicked | started_checkout | purchased | abandoned | not_purchased",
  "agent_id": "string (REQUIRED if Want had origin.agent_id)",
  "timestamp": "ISO 8601",
  "value_cents": integer,
  "metadata": object
}

7.2 Event types

7.3 Purpose

Outcome events drive:

• Match quality improvement (training data for the matching engine).
• Demand-signal aggregation (what was wanted but unmet at scale).
• Attribution for any revenue-share or commission-distribution arrangements between Implementations and originating agents.

Implementations MUST treat outcome events as informational and idempotent. Re-sending the same event SHOULD be a no-op.

8. MCP tool surface

A iwant.fyi demand-side protocol Implementation IS an MCP server. It MUST expose the following tools.

8.1 Required tools

demand.create_want

Create a new Want and return matches.

Input:

{
  "title": "string (required)",
  "price_cents": "integer (required)",
  "price_currency": "string (required)",
  "description": "string (optional)",
  "category": "goods | services | other (optional)",
  "vertical": "string (optional)",
  "mode": "new | used | any (optional)",
  "location": "object (optional)",
  "constraints": "object (optional)",
  "origin": "object (optional)"
}

Output:

{
  "want": Want,
  "matches": MatchResponse
}

demand.search

Run matching against existing supply without persisting a Want. For ephemeral queries.

Input: Same as create_want.

Output: Just the MatchResponse, no persisted Want.

demand.get_want

Retrieve a Want by ID, including any persisted matches.

Input: { "want_id": "string" } Output: { "want": Want, "matches": MatchResponse | null }

demand.record_outcome

Report an outcome event.

Input: Event object (see §7.1). Output: { "received": true }

8.2 Recommended tools

demand.list_verticals

Return the set of verticals this Implementation supports, with descriptive metadata. Useful for agent discovery.

Output:

{
  "verticals": [
    {
      "id": "tools",
      "display_name": "Tools and Hardware",
      "description": "Hand and power tools, fasteners, garage equipment",
      "supported_spec_keys": ["drive_size", "voltage", "torque_range_ftlb", ...],
      "active_supply_sources": ["cj", "shopify", "ebay"]
    },
    ...
  ]
}

demand.list_constraints

Return the constraint vocabulary supported by this Implementation, including custom (x_*) keys.

demand.health

Liveness + readiness check.

8.3 Tool naming convention

Tools SHOULD use the demand. prefix to disambiguate from other MCP tools in the agent's environment. Implementations MAY also expose ungated aliases (e.g., create_want without the prefix) for backwards compatibility with simpler MCP clients.

9. HTTP/REST fallback

Implementations SHOULD provide an HTTP fallback for agents that cannot speak MCP.

9.1 Required endpoints

Request and response bodies are JSON and follow the same schemas as the MCP tool surface.

9.2 Authentication

Agents authenticate via:

• Authorization: Bearer <api_key> header (RECOMMENDED), OR
• ?api_key=<key> query parameter (acceptable for GET endpoints), OR
• MCP-native auth when called via MCP transport.

API key issuance is implementation-specific. iwant.fyi's reference implementation issues keys prefixed iwant_ak_.

10. Identity and attribution

10.1 Agent identity

Agents identify themselves via:

• The API key used for authentication (RECOMMENDED).
• The origin.agent_id field on the Want (REQUIRED when reporting outcomes for that Want).

Implementations MUST NOT require users to disclose personal identity. The user is anonymous to the protocol by default.

10.2 User identity (optional)

Implementations MAY support user accounts (so users can persist their own Wants and receive alerts across agents). When supported:

• User identity is opaque to the agent (the agent only sees what the user has shared).
• An agent MAY pass an opaque user reference via origin.session_id or implementation-specific custom fields under origin.

10.3 Attribution

Outcomes MUST attribute back to the origin.agent_id of the Want, when present. This enables:

• Performance reporting for the originating agent.
• Revenue-share or commission distribution between Implementation and originating agent (if any such arrangement exists).
• Demand-signal aggregation by agent surface.

11. Errors

Error responses follow JSON-RPC 2.0 convention when transported over MCP:

{
  "jsonrpc": "2.0",
  "id": "...",
  "error": {
    "code": -32000,
    "message": "Unauthorized",
    "data": { "reason": "API key invalid" }
  }
}

11.1 Standard error codes

HTTP transport uses standard HTTP status codes (400/401/403/429/500) plus a JSON body of the same error shape under error.

12. Versioning and extensibility

12.1 Semantic versioning

The protocol follows semver. v1.x changes are backwards-compatible. Breaking changes ship as v2.

12.2 Adding fields

Implementations MAY add fields to any object. New fields:

• MUST NOT use top-level names defined by the protocol.
• SHOULD use the x_<implementation_or_vendor>_<field> namespace (e.g., x_iwantfyi_priority, x_anthropic_session_token).

12.3 Extending verticals and constraints

Implementations MAY define new verticals and new constraint keys. Implementations SHOULD expose these via demand.list_verticals and demand.list_constraints so agents can discover capabilities at runtime.

12.4 Deprecation

When the protocol deprecates a field or method:

• v1.x continues to support it.
• It is removed in v2 or later.
• A Deprecation header or _deprecated: true marker SHOULD accompany responses that include deprecated fields.

13. Privacy considerations

• Users SHOULD be anonymous to the protocol by default.
• Implementations MUST NOT log Want titles, descriptions, or constraint values for purposes other than serving the Want, improving match quality, and aggregate demand-signal analytics — and MUST disclose any such use in their privacy policy.
• Implementations MUST allow users to delete their persisted Wants if user accounts are supported.
• Implementations MUST NOT share individual Want data with third parties without explicit user consent. Aggregate, anonymized demand signal MAY be shared.
• Implementations SHOULD NOT include direct user identifiers in outcome events unless the user has opted in.

14. Security considerations

• Implementations MUST authenticate every request (no anonymous access for create_want or record_outcome).
• API keys MUST be transmitted over TLS only.
• Implementations SHOULD support rate limiting per API key.
• Implementations MUST validate all incoming Wants against the schema and reject malformed inputs with appropriate errors.
• Implementations SHOULD treat outcome events as untrusted input and validate that the agent_id matches the authenticated API key.
• Implementations SHOULD support API key revocation and rotation.

15. Conformance

An Implementation is iwant.fyi demand-side protocol v1.0 compliant if it:

1. Exposes all required MCP tools defined in §8.1.
2. Accepts Wants conforming to §4 and §5.
3. Returns Match responses conforming to §6.
4. Accepts outcome events conforming to §7.
5. Authenticates requests per §10.1.
6. Supports the error shape in §11.

Implementations are iwant.fyi demand-side protocol v1.0 compliant with HTTP fallback if they additionally expose the endpoints in §9.

A conformance test kit accompanying this spec exercises these behaviors. (Test kit forthcoming alongside the spec — see test/.)

16. License

This specification is licensed under the Apache License 2.0.

Implementations of the iwant.fyi demand-side protocol are not required to be open source. Any party may implement, fork, extend, or commercialize the protocol or compatible implementations without restriction beyond the Apache License terms applicable to the spec text itself.

17. Appendix: Complete flow example

End-to-end agent interaction with a iwant.fyi demand-side protocol Implementation:

Step 1 — Agent receives user prompt:

User: "I need a torque wrench for my Honda Civic — something good but not pro-shop expensive. Under $150."

Step 2 — Agent calls demand.create_want via MCP:

{
  "method": "demand.create_want",
  "params": {
    "title": "Torque wrench, 1/4\" drive, mid-range for Honda Civic maintenance",
    "description": "User wants quality but not pro-shop pricing. Good condition acceptable.",
    "category": "goods",
    "vertical": "auto_parts",
    "mode": "any",
    "price_cents": 15000,
    "price_currency": "USD",
    "constraints": {
      "rules": {
        "price_max": 15000,
        "condition_min": "good",
        "specs": {
          "drive_size": "1/4\"",
          "torque_range_ftlb": [20, 100]
        }
      },
      "negotiable": ["price_max"]
    },
    "origin": {
      "agent_id": "claude_anthropic_001",
      "agent_name": "Claude",
      "session_id": "sess_abc123"
    }
  }
}

Step 3 — Implementation returns matches:

3 matches: Husky ($89, new, Home Depot), Snap-on used ($125, like-new, eBay), Tekton ($65, new, Amazon).

Step 4 — Agent surfaces matches to user, who picks the Snap-on:

{
  "method": "demand.record_outcome",
  "params": {
    "want_id": "8f3c2e10-...",
    "match_id": "match_002",
    "event": "clicked",
    "agent_id": "claude_anthropic_001",
    "timestamp": "2026-05-19T15:05:00Z"
  }
}

Step 5 — User completes purchase on eBay. Agent reports:

{
  "method": "demand.record_outcome",
  "params": {
    "want_id": "8f3c2e10-...",
    "match_id": "match_002",
    "event": "purchased",
    "agent_id": "claude_anthropic_001",
    "timestamp": "2026-05-19T15:18:00Z",
    "value_cents": 12500
  }
}

Step 6 — Implementation:

• Marks the Want fulfilled.
• Attributes the conversion to claude_anthropic_001.
• Routes any affiliate commission according to its business model.
• Feeds the outcome into match-quality training data.

18. Appendix: Changelog

• 1.0 (2026-05-19) — Initial draft. Want schema, constraint vocabulary, match response, outcome events, MCP tool surface, HTTP fallback, identity, errors, versioning, privacy, security, conformance.

19. Open questions

These are intentionally unresolved in v1 and may be addressed in v1.1 or v2:

• Negotiation — How seller agents counter-offer against a Want. v2.
• Multi-step demand — How a Want with sub-Wants (a kit, a project, a procurement bundle) is expressed.
• Escrow / trust mechanics — How buyer protection is signaled in a Match.
• Cross-Implementation federation — Can Implementations forward Wants to each other for broader supply coverage?
• Agent revenue-share standardization — Whether commission attribution between Implementation and originating agent should be part of the protocol or strictly an implementation concern.
• Demand signal data licensing — Whether aggregated demand signal can be shared between Implementations, and under what terms.

Feedback on any of these is welcome.