Build agents that find what your users want.
iwant.fyi is the reference implementation of the iwant.fyi demand-side protocol v1.0. AI agents express structured purchase intent on behalf of users and receive matched supply across multiple sources -- in one MCP call.
Why use iwant.fyi
One call, all the supply
Every AI lab is locked into a single supply protocol -- ACP, UCP, or a retailer's app. We aggregate across affiliate networks, marketplaces, and direct catalogs and return a single ranked list. Your agent makes one call; we do the fan-out.
Demand-side schema
Wants carry structured constraints -- price, condition, location radius, brand allowlists, vertical-specific specs (year/make/model for auto, drive size + torque range for tools). Filter on things keyword search can't.
Outcome attribution
Report viewed/clicked/purchased events with demand.record_outcome. Outcomes route back to your agent for attribution and feed into match-quality learning over time.
Quickstart
Pick your stack. Each adapter is pre-tested end-to-end against this production server. Need an API key?
import { IwantClient } from "@iwantfyi/sdk";
const client = new IwantClient({ apiKey: process.env.IWANT_API_KEY! });
const { want, matches } = await client.createWant({
title: 'Torque wrench, 1/4" drive, 25-100 ft-lb',
price_cents: 15000,
price_currency: "USD",
vertical: "tools",
mode: "any",
location: { text: "Brooklyn, NY" },
constraints: {
rules: { price_max: 15000, condition_min: "good" },
},
origin: { agent_id: "your-agent-id" },
});
for (const m of matches.matches) {
console.log(`${m.title} -- $${m.price_cents / 100} -- ${m.url}`);
}Get an API key
- Sign in to iwant.fyi.
- Go to your profile / agents and register an agent.
- Save the API key (format:
iwant_ak_...). It is shown once.
Free for now. Rate limits scale with your agent's trust tier: unverified, verified, trusted, preferred.
Tools
Seven canonical iwant.fyi demand-side protocol tools, available over MCP and HTTP. Full schemas in the spec.
| Tool | Spec | Description |
|---|---|---|
demand.create_want | section 8.1 | Create a buyer Want (structured purchase intent) and return matched supply. Use when the user articulates what they want to buy. |
demand.search | section 8.1 | Ephemeral matching -- no persistence. For browsing-style queries when you don't need to track an outcome later. |
demand.get_want | section 8.1 | Retrieve an existing Want by ID, including its current matches and constraints. |
demand.record_outcome | section 8.1 | Report a viewed/clicked/purchased/abandoned event back to iwant.fyi for attribution and match-quality learning. Idempotent. |
demand.list_verticals | section 8.2 | Discover supported verticals (tools, auto_parts in v1) and the spec keys each accepts. Call once at agent startup. |
demand.list_constraints | section 8.2 | Discover the constraint vocabulary supported by this implementation, including any extension keys. |
demand.health | section 8.2 | Liveness + readiness. Returns protocol version, server info, and active supply sources. |
SDKs and adapters
Four officially maintained adapters, all end-to-end verified against production. The source for each lives under packages/ in the iwant.fyi repo.
Recipes
Example agents that demonstrate full flows from intent to outcome attribution. Each ships as an open-source repo you can fork.
Test your implementation
The iwant.fyi demand-side protocol is open (Apache 2.0). Anyone can run their own implementation. The reference conformance kit verifies any MCP server against spec section 15.
# Run against any iwant.fyi demand-side protocol implementation
node --experimental-strip-types tools/conformance-kit/src/index.ts \
--mcp https://iwant.fyi/api/mcp \
--http https://iwant.fyi/api/v1 \
--api-key iwant_ak_...
# Expected output:
# [PASS] section 8.1 -- required MCP tools present
# [PASS] section 4 -- Want creation accepts canonical shape
# [PASS] section 6 -- Match response shape valid
# [PASS] section 7 -- Outcome event accepted
# COMPLIANT v1.0+httpFallback