# demand.json — the open agent demand standard (v0.1-draft)

> Agent Cards declare what agents sell. **demand.json declares what they buy.**
> The missing half of the agentic economy.

**Status:** draft v0.1 · **License:** CC-BY 4.0 (this spec) · MIT (reference code)
**Editor:** jishie (working name) · Reference implementation: this repository.
Read like an RFC: MUST/SHOULD/MAY are normative.

## 1. Problem statement

Every piece of agentic infrastructure describes **supply**: MCP registries, A2A
Agent Cards and x402 catalogs list who sells what. **Demand is invisible.** An
agent that needs something searches catalogs; it never *declares* "here is what
I buy, at what ceiling price, how often." Consequences: sellers aim blind,
buyers re-search identical needs millions of times, the only declared demand
lives siloed inside task marketplaces, and every seller-side growth tactic
degenerates toward spam. For humans, declaring demand never worked (effort +
strategy exposure). For agents the equation flips: publishing is one JSON file,
and declared demand makes competition come to you.

`demand.json` is the mirror of the Agent Card: a signed, machine-readable
declaration of what an agent or organization wants to buy.

## 2. Discovery

- **Well-known path (MUST):** `https://<domain>/.well-known/demand.json` — a
  *Demand Set* document (one publisher, many demands).
- **Link relations (SHOULD):** `<link rel="agent-demand" href=…>` in HTML; a
  `Demand:` line in `llms.txt`; a `demand` field in the publisher's A2A Agent
  Card extensions.
- **Registries (MAY):** demand sets can be pushed to demand indexes. The
  well-known file remains canonical; registries are caches.

## 3. Document format — Demand Set

```jsonc
{
  "demand_set": "0.1",
  "publisher": {
    "name": "Acme Ops GmbH",
    "domain": "acme.example",                    // identity anchor
    "agent_card": "https://acme.example/.well-known/agent-card.json",  // optional
    "contact": "https://acme.example/a2a"        // offer-submission endpoint (§6)
  },
  "signature": {                                  // MUST — unsigned sets are spam by definition
    "alg": "ed25519",
    "keys": "https://acme.example/.well-known/http-message-signatures-directory",
    "keys_inline": { "kty": "OKP", "crv": "Ed25519", "x": "…" },   // MAY (inline JWK)
    "signed_at": "2026-08-09T00:00:00Z",
    "sig": "base64(ed25519(canonical_json(demands)))"
  },
  "demands": [ { /* Demand objects, §4 */ } ]
}
```

Serving rules: `application/json`, cache TTL ≤ 1h, HTTPS only.
Canonicalization for signing: JCS (RFC 8785); this reference implementation
uses recursive lexicographic key ordering with `JSON.stringify` scalar
serialization.

## 4. The Demand object (normative fields)

```jsonc
{
  "id": "dmd_7c31",                        // stable per publisher
  "status": "open",                        // open | paused | filled | expired
  "visibility": "public",                  // public | index-only | sealed (§5)
  "instrument": "INVP-EU-T2@1.0",          // OPTIONAL — join a standard instrument's order book (§8)

  "capability": {                          // WHAT — the core of the match
    "skill": "invoice-parsing",            // from a referenced taxonomy…
    "taxonomy": "https://jishie.com/taxonomy/v1",   // …declared, not assumed
    "description": "Parse EU supplier invoice PDFs to structured JSON, line items + VAT.",
    "input_modes": ["application/pdf"],
    "output_modes": ["application/json"],
    "quality_bar": {                       // machine-checkable acceptance criteria
      "acceptance_test": "https://acme.example/tests/invoice-fixture.zip",
      "min_field_accuracy": 0.98
    }
  },

  "commercials": {                         // HOW MUCH / HOW OFTEN
    "pricing_model": "per_document",
    "ceiling": { "amount": 0.10, "currency": "USDC" },   // max we pay per unit
    "volume": { "expected": 500, "period": "day", "recurring": true },
    "budget_cap": { "amount": 1500, "currency": "USDC", "period": "month" },
    "settlement": ["x402", "escrow:eip155:8453"]          // accepted rails; chain-scoped
  },

  "constraints": {                         // hard filters — mismatches MUST NOT bid
    "regions": ["eu"], "data_residency": "eu",
    "max_p95_ms": 3000,
    "protocols": ["mcp"],
    "compliance": ["gdpr-dpa-required"],
    "min_provider_depth": 2                // e.g. only index-probed (T2+) sellers — optional
  },

  "window": { "opens": "2026-08-10", "expires": "2026-09-10" },   // MUST expire ≤ 90d
  "offer_endpoint": "https://acme.example/a2a",   // where offers go (§6)
  "escrow_required": true,                 // if true, offers MUST use an escrow rail
  "updated_at": "2026-08-09T00:00:00Z"
}
```

Non-normative extensions live under `x_` prefixes. **Anti-hallucination rule
(MUST):** publishers only declare needs they intend to transact; indexes MUST
drop demands that fail signature, expiry, or the abuse checks in §7.

## 5. Visibility tiers

Declared demand leaks strategy. Three tiers solve it:

- **public** — full object visible to anyone. Best price discovery.
- **index-only** — the well-known file lists `{id, skill, window,
  offer_endpoint}` only; full commercials are delivered exclusively to
  registered indexes, which match without republishing. Sellers learn "someone
  buys invoice-parsing in the EU", not who or at what ceiling.
- **sealed** — even the skill is generalized in public
  (`"category": "document-processing"`); the index matches privately and
  forwards the full spec only to sellers it matched. Maximum discretion.

## 6. The offer flow (demand ↔ supply handshake)

1. **Discover** — the seller agent finds a Demand (crawl of well-knowns, or an
   index query like `find_buyers_for_capability`).
2. **Qualify** — the seller MUST verify: signature valid, window open, every
   `constraints` entry satisfiable. **Bidding on unmet constraints is protocol
   abuse** (indexes de-rank for it).
3. **Offer** — POST to `offer_endpoint` as an A2A task of type `demand.offer`
   (or plain HTTPS JSON where A2A is absent):

```jsonc
{ "offer": "0.1", "demand_id": "dmd_7c31",
  "seller": { "domain": "parsedesk.example",
              "agent_card": "https://parsedesk.example/.well-known/agent-card.json",
              "index_ref": "aix_9f2e" },            // optional trust proof
  "price": { "amount": 0.04, "currency": "USDC", "model": "per_document" },
  "capacity": { "max_per_day": 2000 },
  "sla": { "p95_ms": 900, "uptime": 0.998 },
  "settlement": { "rail": "escrow:eip155:8453", "contract": "0x…", "terms_hash": "0x…" },
  "valid_until": "2026-08-20",
  "signature": { /* same scheme as §3 */ } }
```

4. **Accept** — the buyer replies `demand.accept` with the chosen settlement;
   if `escrow_required`, acceptance = escrow creation. Both signed messages +
   `terms_hash` form the audit trail the escrow contract references.
5. **Deliver → settle** — via escrow (conditional settlement) or plain x402
   pay-per-call for spot micro-work.
6. **Close** — the buyer SHOULD update the demand (`filled`/renew); indexes
   prune expired/filled demands automatically.

## 7. Abuse resistance (blocking)

- **Fake demand:** signature MANDATORY (unsigned = dropped); the publisher
  domain must resolve and serve the key directory; indexes SHOULD require a
  small refundable listing stake (e.g. 5 USDC) for public demands from unknown
  domains, returned on expiry or first engagement; demands/domain/day are
  rate-limited; demand-fulfillment rate becomes a *buyer* reputation stat.
- **Offer spam:** `offer_endpoint` operators SHOULD require
  constraints-satisfaction proof and MAY require index verification
  (`min_provider_depth`); indexes penalize sellers bidding outside declared
  capabilities.
- **Price signaling:** ceilings are unilateral buyer maxima (classic RFQ
  mechanics). For oligopolistic B2B categories, prefer the sealed tier.
  Publishers MUST NOT embed personal data in demand objects.

## 8. Standard instruments (informative — the exchange layer)

A demand MAY reference a **standard instrument** — a frozen, versioned bundle
of taxonomy skill + unit + quality bar + constraint profile
(`"instrument": "INVP-EU-T2@1.0"`). Anything matching the bundle is fungible by
definition: demands become bids, standing offers become asks, and settled
engagements print to a public tape. Listing criteria at a reference index are
public and mechanical; nobody pays for a ticker. Only escrow releases and paid
test-calls print prices; below a volume floor, charts read "insufficient data".

## 9. Escrow settlement (informative)

For engagements larger than spot micro-calls, offers reference an escrow rail
(`escrow:eip155:8453:<contract>`). The reference lifecycle:

```
CREATED ──fund()──▶ FUNDED ──deliver()──▶ DELIVERED ──release()/timeout──▶ RELEASED ✔
   │                  │                      │
   │                  │                      └─dispute()─▶ DISPUTED ─resolve(split)─▶ RESOLVED ✔
   │                  └─cancel/expiry──▶ REFUNDED ✔
   └──expire unfunded──▶ VOID
```

Reference contract: `contracts/DemandEscrow.sol` (USDC-only, pull-payments,
arbiter-split-only, small-caps limits). **It MUST pass a professional audit
before holding third-party funds.**

## 10. Governance

This spec moves to a neutral foundation track once ≥3 independent
implementations exist. No trademark squatting, no compatibility breaks without
a 30-day window, no privileged position for any index in the spec text.

---
JSON Schema: [`demand.schema.json`](demand.schema.json) ·
Validator: `npm run demand -- validate <file>` ·
Reference implementation: `/v1/demands*`, `/.well-known/demand.json`, MCP tools
`find_buyers_for_capability` / `publish_demand` / `submit_offer`.