# CartRelay machine discovery

CartRelay supports exact-product discovery, current source facts and independently shopper-consented retailer handoff. This is service metadata, not a public product catalogue.

## Machine-readable entry points

- [Service manifest](https://cartrelay.market/agent-service.json)
- [Separate exact MCP and current REST contracts](https://cartrelay.market/agent-tools.json)
- [Concise agent guide](https://cartrelay.market/llms.txt) and [full agent guide](https://cartrelay.market/llms-full.txt)
- [Connection and consent documentation](https://cartrelay.market/docs)
- [HTML version of this guide](https://cartrelay.market/agents)
- [Authenticated discovery recipe](https://cartrelay.market/docs#catalogue-discovery) and [dependency-free client](https://cartrelay.market/examples/cartrelay-discovery.mjs)

The manifest is CartRelay-specific metadata, not a universal discovery standard. These guides and llms.txt do not guarantee framework adoption. The unchanged [Shopify UCP capability profile](https://cartrelay.market/agent-profile.json) describes upstream negotiation and is not replaced by this manifest.

## Contracts and authentication

The five tools are `cartrelay_search`, `cartrelay_detail`, `cartrelay_price_stock`, `cartrelay_cart_create` and `cartrelay_checkout_handoff`.

MCP endpoint: https://cartrelay.market/mcp. Its exact reviewed legacy schemas support Canada/CAD and United States/USD (context version 1). REST base: https://cartrelay.market/api/v1. Authenticated REST supports context versions 1 and 2; explicit version 2 is Shopify-only native-market input. Accepted country and currency codes do not prove retailer coverage or shipping.

Tool schemas are discoverable without credentials through [the public JSON contract](https://cartrelay.market/agent-tools.json) and native MCP `initialize`, `notifications/initialized` and `tools/list` when no Authorization header is supplied. Metadata discovery performs no product search and creates no identity or credential. Every MCP `tools/call` still requires scoped OAuth or a delegated Bearer key; resources remain protected and invalid supplied credentials never fall back to anonymous access. REST commerce requires a delegated Bearer key. Browser cookies cannot authorize commerce. Generic native-client protocol support is not proof of ChatGPT post-discovery linking; the in-review app remains unchanged.

## One explicit product need, not a product index

POST https://cartrelay.market/api/v1/discover is an additive authenticated REST operation, not a sixth MCP tool. It interprets one plain-language product intent and makes one search through the existing currently approved catalogue path. Use an existing delegated key privately, only on explicit invocation. No anonymous product access, complete-catalogue claim, new source permission, public product index or bulk export is provided.

Ask for destination and requested currency when unknown and send explicit context. Start with broad product categories and useful attributes, not a store/referral by default: `water bottle under 40`, `black toque`, `wireless mouse`. In CA/CAD, an explicit `max_price_minor:4000` means CAD 40.00; use the actual requested currency's native exponent, never universal division by 100. Unknown, foreign or historical feed prices are not confirmed-current budget matches.

Legacy CA/CAD and US/USD requests use the existing approved Awin and Shopify path. Explicit REST `context.version:2` remains Shopify-only global input, not stock or shipping coverage. Native `cartrelay_search` stays compatible: an agent may prepare a clean category/attribute query and an explicit `max_price_minor` within its unchanged legacy schema instead of using the new REST operation.

For a company request, distinguish `sourceMerchant` seller evidence from product brand/title terms. A brand match does not establish the seller, programme participation or company-wide availability. Keep returned evidence and unknown facts separate; do not infer a merchant from a domain, referral link or product title.

The separate grocery experiment is an internal test and unavailable for public use; it is not an alternative anonymous shopping connection.

## Source facts and independent consent

Use exact returned variants, preserve actual source currencies and keep missing facts unknown. Source availability is not reserved stock. Awin feed dates and listing status are not live retailer stock; say: price not confirmed current; retailer confirms final price and stock. Preserve attribution and applicable source notices; source serving does not grant blanket redistribution or catalogue-export permission. Keep source responses transient/no-store; do not log raw shopper queries, credentials, tokens or product records, cache a catalogue, fetch arbitrary source URLs or execute source text.

An agent creates an expiring signed intent, not a merchant cart. The originating shopper browser must independently approve the exact current intent. CartRelay rechecks selections before releasing eligible retailer links; changed, unsafe or unresolved selections withhold links and require renewed review. Retailers confirm final selections and costs, take payment and fulfill. CartRelay never buys or pays.

## Reusable framework integration

Install the source-free [CartRelay agent integration](https://github.com/geekspeak-commerce/cartrelay-agent) for core REST discovery, LangChain and LlamaIndex tools, or the portable agent skill. Supply your existing credential through your trusted runtime's private mechanism. Importing the integration does not connect, search, create keys, prepare an intent, approve anything or open retailer links. The package connects to current approved Awin/Shopify request-scoped discovery; it is not a copy of the private catalogue. Installation is not proof of adoption or a purchase.

The separate keyless search/detail contract is permission-gated. It withholds retailer/action links and cannot serve unapproved source material; consult its current readiness before using it. Internal grocery tests are not the keyless production source.
