Draft v0.1 — published for review. Not final until approved; may change incompatibly before 1.0.
Protocol v0.1 draft
istointents.com

Isto Intents Protocol — Interface Specification v0.1 (draft)

On this page
  1. 1. Scope
  2. 2. Roles
  3. 3. Common rules
    1. 3.1 Envelope
    2. 3.2 Locale
    3. 3.3 Categories
  4. 4. Intent
    1. 4.1 Fields and rules
    2. 4.2 Hidden limit
  5. 5. Offer
  6. 6. Demand summary
  7. 7. Consent
  8. 8. Privacy
    1. 8.1 Data minimisation
    2. 8.2 Protected characteristics
    3. 8.3 AI agents
  9. 9. Hand-offs to other standards
  10. 10. Versioning and extension
  11. 11. Security considerations

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

1. Scope#

Isto Intents defines the interface through which buyers, their agents, sellers and partner operators connect to an intent holder: the format of a standing purchase Intent, of an Offer, and of a DemandSummary; how Consent is recorded; what privacy every party can rely on; and how the objects travel over MCP and hand off to AP2.

It deliberately does not define how an intent holder finds, compares, ranks, prices or selects offers for an intent. That is each holder's own service and is outside this specification.

Out of scope for v0.1: payment, escrow, contract formation, identity verification of sellers. Those are handed off to existing standards (§9).

2. Roles#

role does
Buyer a natural person (or business) who wants something
Buyer agent software acting for the buyer (website, bot, AI assistant)
Intent holder the operator that stores the intent and the buyer's consent; the ONLY party that can contact the buyer
Offer source anything that produces offers: a portal, a dealer's system, a seller replying to an intent

One organisation may play several roles. The intent holder never transfers the buyer's contact details; everything that crosses an organisational boundary is pseudonymous or aggregated.

3. Common rules#

3.1 Envelope#

Every object is a JSON object with:

field type rule
specVersion string protocol version, "0.1"
type string intent, offer, consent, demand-summary
id string (URI) globally unique; urn:uuid: or an HTTPS URL of the holder
created RFC 3339 timestamp
extensions object OPTIONAL; keys MUST be prefixed x- or be a URI

Receivers MUST ignore unknown fields and unknown object types. A field's meaning MUST NOT change within a major version.

3.2 Locale#

field standard example
country ISO 3166-1 alpha-2 SK
region ISO 3166-2 SK-ZI
currency ISO 4217 EUR
language BCP 47 sk
amounts integer, minor units NOT used; whole currency units 15000
distances kilometres; areas square metres

Implementations MAY display other units; the wire format is metric.

3.3 Categories#

category is one of the registered values or an extension URI:

value criteria schema
vehicle schemas/criteria-vehicle.schema.json
property schemas/criteria-property.schema.json

New categories are added by minor version (§10).

4. Intent#

An Intent is what a buyer wants, stated once and kept alive until it expires, is fulfilled or is withdrawn. Schema: schemas/intent.schema.json.

4.1 Fields and rules#

field required meaning
holder yes { id, name } of the intent holder
category, country, currency, language yes §3
statement yes the buyer's own words. Normative for humans; machines use criteria.
parser no identifier of the procedure that derived criteria from statement, if any
criteria.must yes category fields a delivered offer MUST satisfy
criteria.nice no fields the buyer would prefer; they never exclude an offer
area no { center: {lat, lon}, radiusKm }, { regions: [ISO 3166-2] } or { lau: [...] }
budget.max no the price cap the buyer is willing to show
hiddenLimit no a sealed private cap (§4.2); never a plain number
buyBy no date by which the buyer intends to buy
validUntil yes after this instant the intent MUST NOT be acted on
status yes active, paused, fulfilled, withdrawn, expired
buyer yes { pseudonym } — stable per holder, MUST NOT be derivable from contact data
consent yes id of the Consent object (§7) under which the intent exists
visibility yes private (holder only), aggregate (counted in demand summaries), pseudonymous (the intent may be shown to offer sources without contact)
allowedSellers no operator ids the buyer restricts the intent to

Rules:

  1. validUntil MUST NOT be more than 365 days after created. A holder MAY offer renewal; renewal requires a fresh action by the buyer.
  2. When statement and criteria disagree, the holder MUST resolve it with the buyer, not silently prefer one. A holder that derives criteria from statement automatically MUST record which procedure and version did so in parser.
  3. criteria.must MUST NOT be empty — an intent that matches the whole market is not an intent.
  4. For category: property in jurisdictions with fair-housing rules (at minimum US), criteria MUST NOT contain, and holders MUST reject, any field or statement that selects by a protected characteristic (§8.2).

4.2 Hidden limit#

The hidden limit is the highest price the buyer would pay. It exists so that the buyer can tell the holder more than they want to show anyone else.

  1. On the wire a hidden limit is only ever a sealed value { scheme, ciphertext, keyId }, opaque to everyone but the holder that sealed it. The sealing scheme is the holder's choice.
  2. A buyer agent MAY pass a plain number to the holder over an authenticated channel (see the MCP binding); the holder seals it on receipt and never returns it.
  3. A hidden limit MUST NOT appear in logs, exports, dashboards, analytics, support tools, demand summaries or any response to anyone, including the buyer's own agent (which may learn only that a limit is set).
  4. A holder MUST NOT reveal to a seller, directly or by behaviour it describes, whether a hidden limit exists or what it is.

5. Offer#

An Offer is one concrete item available on the market. Schema: schemas/offer.schema.json.

field required meaning
source yes { operator, kind, url?, feedFormat? }; kind = listing (seen on a market), feed (supplied by the seller's system), reply (submitted in answer to an intent)
category, country, currency yes
price yes asking price, whole units
item yes category fields (same vocabulary as criteria) plus identifiers: vin for vehicles, address for property
location no { geo, region, locality }
seller yes `{ kind: dealer
observedAt yes when the source last confirmed the offer exists
inReplyTo with reply Intent id the offer answers

An offer source MUST NOT include personal contact details of a private seller in an Offer sent to another organisation; contact happens through the source's own channel.

Which offers a holder delivers for an intent, in what order and with what commentary, is the holder's own service and is not specified here. A holder MUST NOT deliver the same offer for the same intent twice, and MUST NOT deliver anything once the intent is no longer active.

6. Demand summary#

A DemandSummary tells sellers how many active intents fit a band of their stock, without identifying anyone. Schema: schemas/demand-summary.schema.json.

field meaning
bands the band of stock: make, model, propertyType, price {from, to}, years {from, to}, rooms {from, to}, area, transaction
buyers number of distinct buyers whose active intents fit the band
asOf when the count was taken

Guarantees every holder MUST give:

  1. A minimum count. Each holder sets an anonymity threshold. Below it the count is withheld entirely — not rounded, not shown as "fewer than".
  2. Coarse, fixed bands. Summaries are served only on the holder's fixed band grid, never for arbitrary ranges. Bands, areas included, are coarse enough not to single out a buyer.
  3. Nothing personal. Summaries MUST NOT contain statements, pseudonyms, budgets or hidden limits.
  4. For property, a band with a price MUST carry transaction (a sale price and a monthly rent are not comparable), and bands MUST NOT carry any feature that would describe the buyer rather than the stock, and never a protected characteristic (§8.2). A vehicle band is always a sale.
  5. In a price band to is greater than from.

Band values in the examples are illustrative and do not show any holder's grid.

A Consent records what the buyer agreed to. Schema: schemas/consent.schema.json.

field meaning
subject buyer pseudonym
purposes any of delivery (tell me about offers), aggregate-demand (count me in demand summaries), pseudonymous-visibility (sellers may see my intent without my contact); holders MAY add x- purposes for services of their own
text { uri, version, sha256 } of the exact wording shown
channels verified channels: `{ kind: email
grantedAt, validUntil, withdrawnAt

Rules:

  1. Consent is per buyer, not per channel: a buyer who verified two channels has one Consent listing both. Channels MUST be linked only by proof of control of both (a code sent to one and entered in the other), never by matching names or addresses.
  2. Withdrawal MUST be possible in one action from every delivered message, and MUST stop all processing of the intent immediately.
  3. An intent and everything delivered for it MUST be deleted no later than 30 days after expiry or withdrawal.
  4. A holder MAY express Consent as a signed JWS so that other parties can verify it without access to the holder's database.
  5. Consent is obtained by the holder on its own page. An agent cannot grant it, and an AP2 mandate is not consent (see bindings/ap2.md).

8. Privacy#

8.1 Data minimisation#

Offers sent between organisations carry no private-seller contact; intents sent between organisations carry no buyer contact. Contact is established only by the party the person chose to talk to.

8.2 Protected characteristics#

For property, holders MUST maintain a list of prohibited criteria for each jurisdiction they serve. v0.1 defines the US list: race, colour, religion, sex, disability, familial status, national origin, and proxies (e.g. "family-friendly neighbourhood", "near [house of worship]" as a filter on area). Schemas reject the explicit fields; holders MUST also screen statement.

8.3 AI agents#

An AI agent acting for a buyer or a seller MUST identify itself as an AI agent to the other party (EU AI Act Art. 50).

9. Hand-offs to other standards#

step standard
buyer authorises a purchase AP2 mandate or Verifiable Intent — see bindings/ap2.md
checkout and payment ACP or UCP
agent ↔ holder MCP — see bindings/mcp.md

10. Versioning and extension#

See VERSIONING.md. In short: SemVer on the specVersion field; 0.x may change incompatibly with notice; extensions use x- keys or URIs and MUST NOT redefine core fields.

11. Security considerations#