merx

Merx lets a buyer agent discover products, check evidence, negotiate within published rules and place an order with a signed spending mandate. One TypeScript engine exposes the same operations over MCP, A2A and REST.

Use it to prototype commerce agents, build protocol adapters or experiment with machine-readable catalogs. Early reference implementation: in-memory storage and example payment instructions; see the limitations.

Start in your browser: explore three real matching scenarios with explanations and rejected products. Results are generated by the engine at site build time; this is not a live store.

Quickstart

With Node.js 22.6+ and Git installed:

git clone https://github.com/kamilkubik89/merx.git
cd merx
npm run demo

No API key, model subscription or dependency installation is needed for the demo. It starts a local store, runs a scripted buyer and shuts down automatically. Matching is lexical and negotiation is deterministic.

The demo verifies a signed feed, selects coffee, negotiates a grinder and submits an order within a EUR 150 mandate. Its output includes:

6 items, signature valid: true
TOTAL 113.15 € (VAT incl.)
store-signed receipt valid: true
rejected as expected: 409 ... mandate nonce already used (replay)

This is an abbreviated excerpt of the example run. Payment instructions are returned; no money is transferred.

In Codespaces, wait for setup, then run npm run demo in the terminal. GitHub account quotas and billing apply.

If this is useful to your work, star Merx to bookmark it, or share your use case.

What the store exposes

$ curl https://tatra-coffee.example/
Tatra Coffee Roasters

This store has no website. It sells to software agents.
Start here: https://tatra-coffee.example/.well-known/merx.json

Related MCP server: io.github.Kosta1985/relaymarket

Why

Build the open agentic commerce ecosystem with us

Merx is an open-source project for developers exploring agentic commerce: AI shopping agents that discover products, compare evidence and request authorized purchases. We welcome catalog engineers, payment integrators, merchants and agent developers to build the merchant side together.

Bring a product-data problem, test a buying constraint or propose a protocol adapter. Start with the community guide, join a discussion, or explore first contributions.

Beyond the XML product feed

Agents need product data, but a complete catalog dump is not always the best answer to a buying decision. The experimental Merx Capability Feed returns a signed, intent-specific packet: reusable product facts, evidence references, current indicative offers, suitability warnings and next actions. Stable facts are cached by revision while price and availability are refreshed.

npm run demo:feed

This format is implemented over REST, MCP and A2A. It complements the bulk /feed; a fresh signed quote still determines checkout terms. Read the design and limitations.

Payments through adapters

Register multiple providers, discover them by currency and country, and bind the selected method to the signed quote. Payment setup uses a stable order idempotency key, with a server-side retry hook. See payment integration and the hosted-checkout factory.

Only fictional bank-transfer instructions are bundled. Stripe, PayPal, UCP payment handlers, AP2 and x402 need real adapters and their own verification; the extensible interface does not claim those integrations are complete.

Why a store engine?

Protocols for agent commerce now exist: UCP for discovery and carts, ACP for checkout inside AI surfaces, AP2 for proving a human authorized the spend, MCP and A2A as transports, x402 for machine payments. They define how agents talk to stores.

Merx explores what the store itself can look like in that world. Traditional storefronts are designed around human browsing: product pages written as ads, displayed prices, coupon codes and policies in separate documents.

Merx starts from the other end. If the buyer is an agent, the product catalog should be designed for how agents decide:

Five ideas that make it different

1. Facts, not copy. Every attribute carries a source (declared, measured, lab_test, certified, third_party). Every claim ("organic", "fair trade") needs evidence or strict agents ignore it. A built-in linter scores your catalog for agent-readiness and flags marketing language:

$ npm run lint:catalog
Agent-readiness: 82/100
100  beans-ethiopia-guji-250
  1  mug-tatra
       error summary: marketing language agents ignore or distrust: best, amazing, premium quality, must-have.
       error claims.dishwasher_safe: claim without evidence will be hidden from strict agents

2. not_for — explicit product limitations. Each product declares who should not buy it. The matcher penalises conflicts with those declarations and includes a warning in its result. This gives agents a concrete signal about product fit; Merx does not implement a reputation system.

3. Intent in, reasons out. Agents don't browse. They send a need plus hard constraints and get ranked matches with why, and every rejected product with why not:

{ "item_id": "grinder-hand-c40", "reasons": ["price 8900 > max 8000 (item is negotiable, try /negotiate)"] }

4. Negotiation as policy, not a chatbot. Merchants publish rules (volume and bundle discounts) and set a private floor per item. The engine concedes deterministically over a bounded number of rounds and returns a signed deal_token. Predictable for agents, auditable for merchants, never below the floor.

5. Mandates and signed receipts. An order is only accepted with a mandate signed by the human principal: spending limit, merchant scope, allowed categories, expiry, single-use nonce. The store returns a receipt signed with its key, a portable proof of purchase that any agent can verify. (Model inspired by AP2; an AP2 adapter is on the roadmap.)

The flow

sequenceDiagram
    participant H as Human wallet
    participant A as Buyer agent
    participant S as Merx store
    A->>S: GET /.well-known/merx.json
    S-->>A: manifest, public key, protocols
    A->>S: find_products {need, constraints}
    S-->>A: matches + reasons, rejected + reasons
    A->>S: negotiate {item, qty, price}
    S-->>A: counter … accepted + deal_token (signed)
    A->>S: create_quote {lines, ship_to}
    S-->>A: signed quote, stock held 15 min
    A->>H: request mandate (≤ total, this merchant)
    H-->>A: signed mandate
    A->>S: place_order {quote_id, mandate, buyer}
    S-->>A: order + payment instructions + signed receipt

Run your own store

Requires Node.js 22.6+. Zero runtime dependencies: TypeScript runs directly through Node's type stripping.

npm start            # run the example store on :3000

For development checks, install the locked development dependencies:

npm ci               # dev tooling only
npm test             # unit + integration tests
npm run check        # what CI runs: typecheck, coverage gate, catalog lint

Then point any agent at it:

• MCP (clients supporting Streamable HTTP): http://localhost:3000/mcp

• A2A: agent card at http://localhost:3000/.well-known/agent-card.json

• REST: http://localhost:3000/openapi.json

• LLM-friendly summary: http://localhost:3000/llms.txt

Run your own store: write a catalog.json (see examples/stores/tatra-coffee), then

npm run merx -- lint my-catalog.json
MERX_CATALOG=my-catalog.json npm start

In PowerShell, set the environment variable before starting the server:

$env:MERX_CATALOG = "my-catalog.json"
npm start

Useful env vars: PORT, MERX_CATALOG, MERX_PRIVATE_KEY or MERX_KEY_FILE, MERX_WEBHOOK_URL (receives order.created).

To test ordering by hand, create a test mandate with npm run merx -- mandate --agent my-agent --max 15000 --merchants tatra-coffee.

Architecture

            ┌──────────── adapters (wire protocols) ─────────────┐
 agents ──▶ │  REST/OpenAPI   MCP   A2A   your-protocol.ts  …    │
            └──────────────┬─────────────────────────────────────┘
                           │ operations.ts (defined once, JSON Schema)
            ┌──────────────▼─────────────────────────────────────┐
            │ MerxEngine  feed · intent · negotiate · quote ·    │
            │             mandate · order · receipt · lint       │
            └──────────────┬─────────────────────────────────────┘
                           │ pluggable
          Scorer (lexical → embeddings) · PaymentProvider · catalog source

Every capability is defined once in src/adapters/operations.ts with a JSON Schema. MCP tools, A2A skills and the OpenAPI document are generated from that list, so adding an operation makes it available in every protocol. Writing an adapter for a new protocol is a single file: see docs/ADAPTERS.md.

Specification

The feed format, mandate and receipt formats are documented in docs/SPEC.md (Merx 0.1, draft). Short version of one feed item:

{
  "id": "beans-brazil-cerrado-1kg",
  "gtin": "8580000000028",
  "title": "Brazil Cerrado, whole bean, 1 kg",
  "summary": "Medium-dark roast, pulped natural. Cup notes: milk chocolate, hazelnut. Low acidity...",
  "category": ["coffee", "beans"],
  "attributes": [
    { "key": "net_weight", "value": 1000, "unit": "g", "source": "measured" },
    { "key": "acidity_level", "value": 1, "source": "declared", "note": "1 (low) to 5 (high)" }
  ],
  "claims": [{ "id": "rainforest_alliance", "statement": "Rainforest Alliance certified farm",
               "evidence": { "type": "certificate", "issuer": "Rainforest Alliance", "ref": "RA-C-0000000" } }],
  "best_for": ["espresso", "milk drinks", "low acidity"],
  "not_for": ["light roast", "fruity"],
  "offer": {
    "price": { "amount": 3290, "currency": "EUR" },
    "compare_basis": { "per": "kg", "amount": 3290 },
    "availability": { "in_stock": true, "quantity": 38, "lead_time_days": 1 },
    "negotiable": true,
    "valid_until": "2026-09-22T20:30:00.000Z"
  },
  "content_hash": "4f1c…",
  "updated_at": "2026-09-22T20:15:00.000Z"
}

Status and roadmap

Merx is a working reference implementation and a draft spec, not production software. Storage is in-memory, and the example payment provider only returns bank-transfer instructions. Capability Feed 0.1 is an experimental Merx format.

Roadmap, and good first contributions:

• Adapters: UCP (/.well-known/ucp), ACP checkout, AP2 mandate verification, x402

• Catalog sources: import from Shopify / WooCommerce / Google Merchant feeds, with an automatic "de-marketing" pass

• Storage: SQLite and Postgres adapters for orders, holds and sessions

• Payments: Stripe, GoPay, Adyen, stablecoin rails

• Matching: embedding scorer, cross-store comparison agent

• Trust: portable reputation from signed receipts (agents share verified purchase outcomes), did:web store identity

• Post-purchase: machine-readable returns and warranty claims

Quality

Every push and pull request runs on GitHub Actions against Node 22 and 24: typecheck, unit and HTTP integration tests covering all three transports, a coverage gate (≥ 90 % lines), an agent-readiness check of the example catalog, the end-to-end buyer-agent demo, and a Docker build with smoke test. Capability Feed signatures, cache reuse, payment routing and recovery have dedicated tests. CodeQL scans the code weekly. Tagging v* publishes a GitHub release.

Contributing

Start with the first-contribution guide, ask a question in Discussions, or use a bug / adapter / feature template. Small, tested improvements are welcome.

See the code of conduct and security policy. Want to share the project? The launch kit includes a demo outline and editable English copy.

License

MIT © Kamil Kubík