{"checkout_guide":"https://trusteed.xyz/.well-known/agent-checkout-guide.json","schema_version":"mcp-manifest/1.0","name":"trusteed","display_name":"Trusteed","description":"Multi-merchant MCP commerce network. Search products across connected Shopify, WooCommerce, PrestaShop and Odoo stores, manage carts, and initiate checkout flows autonomously.","version":"1.30.0","updated_at":"2026-10-05","mcp_version":"2025-11-25","mcp_supported_versions":["2025-11-25","2025-06-18","2025-03-26","2024-11-05","2024-10-07"],"sdk_version":"1.29.0","server_card":"/.well-known/mcp.json","public_endpoints":{"note":"store_directory, cross_store_search, deals_feed AND per_store_mcp's discovery tools (see below) are rate-limited by IP (120 req/min) and require NO authentication. EVERY checkout-bucket tool on per_store_mcp requires a Bearer token — create_cart included, building a cart is not a free step before checkout. demo-store is no exception: `demo.tools_checkout_simulated` below is empty, so on demo-store too every checkout tool needs a credential (the self-service sandbox key or the widget's cart token), on POST /{storeSlug}/mcp and on the dedicated checkout endpoint (POST /{storeSlug}/mcp/checkout) alike. On demo-store, an `X-Payment-Mandate` header is additionally required by the checkout tools that spend or settle (preview_checkout, complete_checkout, process_agent_payment, complete_visa_payment, ucp_complete_checkout); the other checkout tools (create_cart and attach_agent_identity and verify_age_over_n and verify_residence_country and verify_legal_person_authorization and apply_discount and get_shipping_rates and select_shipping_option and create_payment_mandate and update_payment_mandate and cancel_payment_mandate and ucp_create_checkout and ucp_update_checkout and ucp_add_items_to_checkout and ucp_get_checkout and ucp_cancel_checkout and get_trust_receipt) don't need it. Without it, demo-store answers HTTP 200 with a JSON-RPC error whose `error.data.code` is `demo_sandbox_mandate_required` (`demo_sandbox_mandate_malformed` plus `remediation.mandate_issues` if it does not parse); branch on that code, not on the HTTP status. A real merchant answers 403 `payment_mandate_required`.","store_directory":{"method":"GET","path":"/api/v1/stores/directory","description":"Paginated list of all active stores. Returns slug, name, platform, product_count, top_categories, trust_score, freshness_tier (fresh|recent|stale|unknown), mcp_endpoint.","params":"?page=1&limit=50&platform=SHOPIFY|WOOCOMMERCE|PRESTASHOP|EBAY|CUSTOM&q=name","example":"GET https://api.trusteed.xyz/api/v1/stores/directory?limit=10"},"cross_store_search":{"method":"POST","path":"/api/v1/search","description":"Cross-store product search with trust-weighted ranking (text_relevance×0.55 + trust_score×0.25 + freshness×0.10 + in_stock×0.10). Returns products from all connected merchants.","body":"{ query: string, filters?: { category, inStock, minPrice, maxPrice }, sort?: 'relevance|price_asc|price_desc|trust_score', limit?: number (max 50), page?: number }","headers":"X-Agent-Session-ID: optional session ID for funnel tracking across search→view→cart","example":"POST /api/v1/search { \"query\": \"waterproof jacket\", \"filters\": { \"inStock\": true }, \"limit\": 10 }"},"deals_feed":{"method":"GET","path":"/api/v1/deals","description":"Products with genuine discounts (compareAtPrice > price) from verified merchants. Sorted by discount% descending, then by merchant trust_score.","params":"?minDiscount=10&category=jackets&inStock=false&limit=20&page=1","example":"GET https://api.trusteed.xyz/api/v1/deals?minDiscount=15&inStock=true"},"per_store_mcp":{"method":"POST","path":"/{storeSlug}/mcp","description":"Direct MCP tool call on any store. Per-tool auth is declared per store in `tools_preview[].auth_required` below. Fix 2026-08-21 (C5/N4 contrast): the previous text here claimed discovery tools (search_products, get_product_details, browse_categories, get_merchant_profile, compare_products, onx_get_inventory, nlweb_ask) required OAuth Bearer except on `demo-store` — traced against the actual enforcement path (mcp-gateway.ts's PUBLIC_DISCOVERY_TOOLS gate + tool-bucket-registry.ts, the runtime SSOT) and found FALSE: those tools have `requiresAuth: false` / `bucket: \"discovery\"` and are genuinely callable without a token on EVERY store, not only `demo-store`. Checkout-session-and-above tools (preview_checkout, apply_discount, get_shipping_rates, create_cart, complete_checkout, select_shipping_option, ...) require an OAuth 2.1 Bearer token with scope mcp:checkout on every store. Since 2026-09-23 `demo-store` (`demo.auth_mode: \"public_sandbox\"` below) waives auth on NONE of them: `demo.tools_checkout_simulated` is empty, and every checkout tool there needs the self-service sandbox key (from the `create_sandbox_key` tool) or the widget cart token. Read `demo.tools_checkout_simulated` for the current exemption set instead of assuming any checkout tool is waived here.","body":"{ jsonrpc: '2.0', method: 'tools/call', params: { name: 'search_products', arguments: { query: string, limit: number } } }","headers":"Accept: application/json, text/event-stream","example":"POST /demo-store/mcp { \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": { \"name\": \"search_products\", \"arguments\": { \"query\": \"jacket\", \"limit\": 5 } } }"}},"agent_workflow_no_auth":["Steps 1-5 need no auth on any store. Step 6 needs a credential on every store: an OAuth Bearer token, or on demo-store the self-service sandbox key (checkout there is simulated, but not credential-free).","Step 1 — Discover stores: GET /api/v1/stores/directory → get slugs, top_categories, freshness_tier","Step 2 — Cross-store search: POST /api/v1/search { query } → ranked results from all merchants","Step 3 — Browse deals: GET /api/v1/deals?minDiscount=10 → discounted products cross-store","Step 4 — Product detail: POST /{slug}/mcp → get_product_details (no auth required; returns GTIN, Schema.org, variants)","Step 5 — Merchant trust: POST /{slug}/mcp → get_merchant_profile (no auth required; trust_score, protocols, policies)","Step 6 — Checkout: POST /{slug}/mcp → create_cart (requires OAuth Bearer token)"],"session":{"sandbox_key_ttl_seconds":86400,"sandbox_key_max_per_ip_per_day":25},"stores_directory":{"description":"Paginated directory of all active stores on the platform. Returns store metadata only (slug, name, platform, product_count, mcp_endpoint). Use to discover stores before calling their MCP endpoint.","endpoint":"https://api.trusteed.xyz/api/v1/stores/directory","pagination":"?page=1&limit=50 (max 100 per page)","filters":"?platform=SHOPIFY|WOOCOMMERCE|PRESTASHOP|EBAY|CUSTOM&q=store+name+search","auth_required":false,"cache_ttl_seconds":300,"agent_workflow":["1. GET /api/v1/stores/directory → discover store slugs, top_categories, freshness_tier (no auth)","2. POST /api/v1/search { query } → cross-store search with trust ranking (no auth)","3. GET /api/v1/deals?minDiscount=10 → discounted products across all stores (no auth)","4. POST /{storeSlug}/mcp → search_products, get_product_details, get_merchant_profile (no auth required, on every store)","5. POST /{storeSlug}/mcp → create_cart, complete_checkout (OAuth Bearer required on every store; on demo-store a self-service sandbox key is accepted instead — checkout there is simulated, not credential-free)"]},"platform_discovery":{"description":"Natural-language discovery over the platform's own documentation (protocols, beta access, integrations, partner programs), served by NLWeb. Deployed but NOT answering today — read status below before integrating.","status":"not_answering","status_detail":"Deployed on our side: the route exists and the search pipeline (pgvector retrieval plus re-ranking) is implemented. We cannot claim it indexes or answers. Measured 2026-09-03: nlweb_endpoint returns code NLWEB_NOT_ENABLED ('NLWeb is not enabled or index is not ready for this store'), a merchant store's /{slug}/ask returns code VECTOR_DB_UNAVAILABLE because the embedding step is failing upstream, and the nlweb_ask MCP tool answers on no surface (-32602 'Tool nlweb_ask not found' on demo-store and on the production merchant, on both deployments). Use POST /api/v1/search or the search_products MCP tool instead.","status_measured_at":"2026-09-03","fallback":{"cross_store_search":"https://api.trusteed.xyz/api/v1/search","mcp_tool":"search_products"},"nlweb_endpoint":"https://api.trusteed.xyz/mcpwebstore-platform/ask","browser_proxy":"https://trusteed.xyz/api/nlweb-proxy","browser_proxy_usage":"POST { storeSlug: 'mcpwebstore-platform', query: string, mode: 'list'|'summarize', streaming: boolean }","interactive_discover_page":"https://trusteed.xyz/en/discover","intended_content":"protocols, beta access status, rollout plans, features, integrations, partner programs, developer guides, FAQs. Not a count of what is currently indexed — see status_detail.","schema_org_types":["SoftwareApplication","WebPage","FAQPage","Offer"],"example_queries_when_available":["what payment protocols do you support?","what is currently available during beta access?","does the platform integrate with Shopify?","what is the white-label program?"]},"supported_platforms":[{"id":"shopify","name":"Shopify","description":"Hosted e-commerce platform. Supports products, variants, inventory, Storefront API checkout.","version_supported":["2023-07","2024-01","2024-07"],"auth_method":"oauth2"},{"id":"woocommerce","name":"WooCommerce","description":"WordPress-based e-commerce plugin. Supports products, orders, coupons via WooCommerce REST API.","version_supported":["7.x","8.x","9.x"],"auth_method":"api_key"},{"id":"prestashop","name":"PrestaShop","description":"Open-source e-commerce platform. Supports products, categories, stock via PrestaShop Web Services API.","version_supported":["1.7","8.x"],"auth_method":"api_key"},{"id":"odoo","name":"Odoo ERP","description":"Open-source ERP with e-commerce integration. Supports products, variants, stock from warehouse, pricelist pricing.","version_supported":["16","17","18"],"auth_method":"api_key"},{"id":"magento","name":"Magento","description":"Open-source e-commerce platform (Adobe Commerce family). NLWeb endpoint, signed manifest, standalone TrustReceipt verifier. No embedded dashboard panel yet.","version_supported":["2.4"],"auth_method":"api_key"}],"servers":[{"transport":"streamable-http","url":"https://trusteed.xyz/demo-store/mcp","label":"Public demo MCP Server (discovery access, no auth)","note":"Authenticated per-merchant MCP: POST /{storeSlug}/mcp with X-Agent-Api-Key"}],"auth":{"type":"oauth2","resource_metadata_url":"https://trusteed.xyz/.well-known/oauth-protected-resource/{storeSlug}/mcp","authorization_url":"https://auth.trusteed.xyz/authorize","token_url":"https://auth.trusteed.xyz/oauth/token","scopes":["mcp:read","mcp:write","mcp:search","mcp:checkout"],"pkce_required":true},"capabilities":{"tools":true,"resources":true,"prompts":false},"client_capabilities_used":{"elicitation":{"used_by":["get_shipping_rates","complete_checkout"],"required":false,"fallback":"form/URL response in the tool result when unsupported"},"sampling":{"used_by":[],"required":false}},"acp_feed":{"status":"active","description":"OpenAI ACP-compatible product feed (15-minute refresh). Use for ChatGPT product discovery visual surface.","feed_url":"https://api.trusteed.xyz/api/v1/public/{slug}/acp-feed","promotions_url":"https://api.trusteed.xyz/api/v1/public/{slug}/acp-promotions","formats":["tsv","json"],"refresh_rate_minutes":15,"schema_version":"2026-01-30","required_fields":["id","title","description","price","availability","image_url"]},"ucp_identity":{"status":"experimental","enabled":false,"description":"UCP Identity Linking — OAuth 2.0 for shopper identity across platforms. EXPERIMENTAL: the associated loyalty / member checkout-discount behaviour is feature-flagged OFF by default and is NOT generally available. Do not rely on loyalty pricing or member-discount scopes as stable.","authorize_url":"https://api.trusteed.xyz/api/v1/ucp/identity/authorize","token_url":"https://api.trusteed.xyz/api/v1/ucp/identity/token","profile_url":"https://api.trusteed.xyz/api/v1/ucp/identity/profile","revoke_url":"https://api.trusteed.xyz/api/v1/ucp/identity/revoke","supported_scopes":["loyalty:read","identity:link","checkout:discount"],"rollout_access":"guided_beta","access_note":"Identity linking is available during guided beta rollout for approved merchants and shopper flows, not as a self-serve paid tier."},"ui_protocols":{"a2ui":{"version":"0.9","status":"not_implemented","spec_url":"https://github.com/google/A2UI","description":"No A2UI renderer or component catalog is served. No tool accepts an 'a2ui' parameter. Trust component semantics are published transport-agnostically at /.well-known/trust-components.json and served today over MCP Apps.","planned_components":[],"compatible_tools":[],"trust_components_catalog":"https://trusteed.xyz/.well-known/trust-components.json","renderers_url":"https://github.com/google/A2UI/tree/main/renderers"},"mcp_apps":{"status":"code_complete","spec_url":"https://modelcontextprotocol.io/","description":"Widget resources implemented as ui:// resources and bound to tools via _meta.ui.resourceUri, carrying the merchant's trust posture (merchant_trust) and, after checkout, the state of its trust receipt (trust_receipt). Reachable through the endpoint this manifest documents: /{storeSlug}/mcp announces capabilities.resources and serves resources/list and resources/read for the ui:// templates (measured 2026-09-23). That any client has rendered them cannot be claimed.","served_by":["packages/mcp-server","apps/api/src/routes/mcp/legacy-dispatch.ts"],"components":["catalog-widget","product-detail-widget","cart-widget","receipt-widget","merchant-trust-widget"],"vocabulary_url":"https://trusteed.xyz/.well-known/trust-components.json"},"webmcp":{"status":"code_complete","spec_version":"2026-03-27","spec_url":"https://webmachinelearning.github.io/webmcp/","revision_hash":"90daeee7b123f0fc421d76bbba5d5b1353f328a2","description":"WebMCP (W3C CG Draft) support at two levels: (1) server-side tools fully compatible with browser agents via standard MCP transport — no snippet required, and reachable today; (2) browser-native bridge snippet for stores that need client-side session, cart and DOM access — implemented and served, but never verified against a browser with native navigator.modelContext, which is why this entry is code_complete and not active.","server_side_tools":{"description":"Available on all stores without any frontend installation. Discovery tools are public (no auth). Checkout tools require OAuth Bearer token.","discovery_tools":["search_products","get_product_details","browse_categories","get_merchant_profile","compare_products","onx_get_inventory"],"checkout_tools":["preview_checkout","apply_discount","create_cart","select_shipping_option","complete_checkout","ucp_create_checkout","ucp_complete_checkout"],"auth_required_for_checkout":true,"endpoint_pattern":"https://trusteed.xyz/{storeSlug}/mcp"},"browser_bridge":{"status":"code_complete","description":"JS snippet that registers navigator.modelContext tools bridging browser-side state (session, local cart, DOM) to the platform backend. Install once per store. The bundle IS served: GET /webmcp-bridge.js redirects to the CDN worker and returns the real IIFE. Code-complete, not verified native: the E2E suite injects a simulated navigator.modelContext and no run against a Chrome with real support exists. Telemetry: the snippet posts anonymous bridge diagnostics to /api/v1/webmcp/telemetry — see /.well-known/agent-policy.json → dataPrivacy.webmcpBridgeTelemetry.","snippet_capabilities":["authenticated_session_read","local_cart_sync","wishlist_read","user_preferences_read","dom_product_highlight"],"install_methods":[{"platform":"shopify","method":"Theme App Extension (App Embed Block)","merchant_action":"Activate from Shopify Theme Editor — no code changes required","distribution":"Shopify App Store"},{"platform":"woocommerce","method":"WordPress plugin via wp_enqueue_scripts()","merchant_action":"Install plugin from wp-admin → Plugins → Add New","distribution":"WordPress Plugin Directory"},{"platform":"prestashop","method":"PrestaShop module via displayHeader hook","merchant_action":"Install module from backoffice → Modules → Module Manager","distribution":"PrestaShop Marketplace"},{"platform":"odoo","method":"Odoo app module via ir.http hook","merchant_action":"Install module from Apps menu → activate WebMCP bridge","distribution":"Odoo Apps Marketplace"},{"platform":"custom","method":"Manual script tag","merchant_action":"Add <script src=\"https://trusteed.xyz/webmcp-bridge.js\" data-store=\"{storeSlug}\"></script> before </body>","distribution":"CDN"}],"compatible_browsers":["Chrome Canary (flag: #model-context-protocol)","Opera Comet"],"sandbox_url":"https://trusteed.xyz/en/demo-store/playground"},"features":["registerTool","requestUserInteraction","callTool","listTools","AbortSignal"]},"payment_request_api":{"status":"code_complete","version":"W3C CR Draft (27 Jan 2026)","spec_url":"https://www.w3.org/TR/payment-request/","author":"W3C Web Payments Working Group","layer":"L5 — Human-Confirmed Payment Execution","description":"W3C Payment Request API — browser-native payment sheet (Apple Pay, Google Pay, saved cards). Agent initiates checkout via MCP; browser shows native payment UI; human confirms; Stripe PaymentMethod token is sent to the browser-pay endpoint below. No agent can bypass this step. DEPLOYED, NOT IN USE: no merchant currently has a payment processor configured, so this path cannot complete a charge today — see /.well-known/trusteed-capabilities.json → payment_request_api.","settles_real_payments":false,"human_confirmation":"always_required","agentic_bypass":false,"endpoint":"https://api.trusteed.xyz/api/v1/checkout/{sessionId}/browser-pay","supported_methods":["apple_pay","google_pay","basic_card"],"supported_currencies":["USD","EUR","GBP"],"fallback":"Manual card form (PaymentFallbackForm) for browsers without Payment Request API support","security_model":"Client-side tokenization via Stripe.js — no card data reaches the server. paymentMethodId excluded from logs and DB.","browser_support":["Chrome 60+","Safari 11.1+","Firefox 55+","Edge 16+"],"spec":"026-browser-payment-api","testing_status":"27 tests (unit + integration); no production traffic"}},"ag_ui":{"endpoint":"/{storeSlug}/ag-ui","transport":"sse","version":"0.0.48","status":"production","author":"CopilotKit","spec":"https://docs.ag-ui.com","documentation_url":"https://trusteed.xyz/en/for-agents","testing":{"total_tests":311,"status":"311 tests total across the API service and route suites, 100% pass rate as of 2026-10-03 (static count of it()/test() blocks; 316 executions once parameterized cases expand; count verified live by CI gate ag-ui-test-count-drift, not a hand-typed phase breakdown — see apps/dashboard/src/__tests__/manifest-contracts.test.ts)"},"supported_events":["RunStarted","RunFinished","RunError","TextMessageStart","TextMessageContent","TextMessageEnd","ToolCallStart","ToolCallArgs","ToolCallEnd","StateSnapshot","StateDelta","Custom"],"confirmation_endpoint":"/{storeSlug}/ag-ui/confirm","human_in_the_loop":true,"state_sync":"RFC 6902 JSON Patch","confirmation_token":"HMAC-SHA256","confirmation_window_minutes":5,"description":"AG-UI (Agent-User Interaction Protocol, by CopilotKit) — Real-time agentic commerce with Server-Sent Events (SSE) streaming, bidirectional state synchronization via RFC 6902 JSON Patch, and human-in-the-loop cryptographic token confirmation. 311 tests passing."},"protocols":{"acp":{"status":"sandbox","provider":"stripe","description":"Stripe-based fiat checkout (test mode)"},"ap2":{"status":"experimental","provider":"mock","description":"Google Agent Payment Protocol — mandate-based confirmations (mock mode)"},"x402":{"status":"sandbox","provider":"mock","description":"USDC stablecoin payments via HTTP 402 (simulated settlement)"},"ucp":{"status":"production","version":"2026-08-25","discovery_url":"https://trusteed.xyz/.well-known/ucp","description":"Universal Commerce Protocol — standardized commerce operations. 6 checkout tools active plus 1 catalog tool. Full capability negotiation. The tools are served; no UCP transaction has been settled — the payment leg does not complete. See /.well-known/trusteed-capabilities.json → ucp.","settles_transactions":false,"spec_url":"https://github.com/universal-commerce-protocol/ucp","tools":["ucp_create_checkout","ucp_update_checkout","ucp_add_items_to_checkout","ucp_complete_checkout","ucp_get_checkout","ucp_cancel_checkout","ucp_get_catalog"]},"kyapay":{"status":"experimental","version":"0.1","settlement":"skyfire","tokenTypes":["pay","kya+pay"],"identity":true,"auth_required":true,"description":"KYApay identity-linked payments via Skyfire (JWT-based, no gas fees). Enabled in production since 2026-09-05 as IDENTITY verification only: keys auto-provisioned by the KYA path carry no `checkout` scope, so `/api/v1/agent/checkout` answers 403 to an agent authenticated with a Skyfire JWT alone. `/api/v1/health` reports protocols.kyapay.enabled = true with chargeCount24h = 0. Payment over this rail is a second phase. See /.well-known/trusteed-capabilities.json → kyapay."},"paypal":{"status":"coming-soon","version":"1.0","adapter":"paypal-inbound-v1","provider":"paypal","api":"Orders API v2","sandbox_url":"https://api-m.sandbox.paypal.com","supported_currencies":["USD","EUR","GBP","CAD","AUD","JPY"],"auth_required":true,"refunds_require_approval":true,"description":"PayPal Orders API v2 — card and PayPal wallet payments. Buyer approval flow. Refunds require merchant approval."},"mcap":{"status":"coming-soon","version":"1.0","adapter":"mcap-inbound-v1","provider":"stripe","auth_required":true,"description":"Mastercard Agent Pay — Ed25519 HTTP Message Signatures (RFC 9421) with Agentic Token pass-through via Stripe. Zero-code for merchants with existing Stripe setup.","tools":["process_agent_payment","check_agent_consent"]},"ag_ui":{"status":"production","version":"0.0.48","type":"UI/Communication Protocol","transport":"Server-Sent Events (SSE)","auth_required":true,"author":"CopilotKit","spec_url":"https://docs.ag-ui.com","description":"AG-UI (Agent-User Interaction Protocol, by CopilotKit) — Real-time agentic commerce with SSE streaming, RFC 6902 state sync, and human-in-the-loop confirmation. 311 tests passing.","endpoint":"/{storeSlug}/ag-ui","confirmation_endpoint":"/{storeSlug}/ag-ui/confirm","supported_events":12},"payment_request_api":{"status":"code_complete","version":"W3C CR Draft (27 Jan 2026)","type":"Browser-Native Human-Confirmed Payment (W3C)","layer":"L5 — Human-Confirmed Payment Execution","spec_url":"https://www.w3.org/TR/payment-request/","human_confirmation":"always_required","agentic_bypass":false,"settles_real_payments":false,"endpoint":"https://api.trusteed.xyz/api/v1/checkout/{sessionId}/browser-pay","supported_methods":["apple_pay","google_pay","basic_card"],"supported_currencies":["USD","EUR","GBP"],"security":"Client-side Stripe.js tokenization — card data never reaches server","description":"W3C Payment Request API — browser-native payment sheet. Agents initiate checkout via MCP; human confirms in browser; Stripe token returned to backend. Mandatory human-in-the-loop for all payment finalization. spec: 026-browser-payment-api. DEPLOYED, NOT IN USE: no merchant has a payment processor configured today, so no charge completes through this path."},"ixopay":{"status":"coming-soon","version":"1.0","type":"Multi-PSP Risk Orchestration","spec":"031-ixopay-unified-trust-layer","opt_in":true,"opt_in_note":"Requires MerchantPspConfig.enabled=true. Inactive for merchants without explicit configuration.","executes_real_payment":false,"execution_note":"Routing and vault are advisory/sandbox only. The selected PSP and vault token are returned for inspection — no real settlement is performed through this layer yet. Real payment execution remains on the merchant's existing ACP/Stripe path.","supported_psps":["stripe","adyen","paypal","braintree"],"routing_signal":"agent_trust_score","routing_mode":"advisory","routing_logic":"Advisory only (sandbox): if riskScore >= merchant threshold (default 0.7) the layer recommends fallbackPsp; if the primary PSP would decline with a retryable code it recommends a fallback attempt. No live charge is routed.","risk_signals":["IXOPAY normalized risk score (0-1, cross-PSP average)","Zip BNPL default rate (0-1, geographic guard: US/UK/AU)"],"token_vault":{"status":"coming-soon","description":"PSP-agnostic token vault (sandbox). Maps a single opaque vault token to PSP-issued tokens for Stripe, Adyen, PayPal, Braintree. No raw card data (PAN/CVV) ever stored.","pci_note":"PCI scope unchanged — vaultToken is an opaque reference, not card data.","productive_note":"Not yet usable for productive future purchases. Vault tokens are issued and stored for portability testing but are not redeemed against a live PSP charge while the layer is in sandbox.","migration":"Existing Stripe tokens are migrated on next checkout (idempotent upsert). The migration vault token is derived via HMAC-SHA256 — the raw Stripe token is never embedded in identifiers."},"agent_weight":0.08,"zip_bnpl_weight":0.06,"description":"IXOPAY multi-PSP risk orchestration with advisory smart routing and a PSP-agnostic token vault. Merchants opt-in via MerchantPspConfig (sandbox). Risk signals (ixopayRisk + zipBnplRisk) feed the agent risk score when active. Routing/vault are advisory and do not execute real settlement yet. spec: 031-ixopay-unified-trust-layer."}},"rate_limits":{"mcp_endpoint":{"effective_rpm_per_key":30,"tier_differentiation":false,"note":"The MCP gateway applies the STARTER quota to EVERY key regardless of its tier (mcp-gateway-rate-limit.ts hardcodes it). Plan your backoff against effective_rpm_per_key, not against declared_tier_rpm.","declared_tier_rpm":{"STARTER":30,"GROWTH":200,"PRO":1000,"ENTERPRISE":5000},"per_tool_rpm":{"search_products":20,"search_products_enriched":15,"complete_checkout":10,"create_cart":20,"ucp_create_checkout":20}},"demo_unauthenticated":"20 req/min per IP — this is the quota applied to demo-store calls made without an API key (discovery tools only: demo.tools_checkout_simulated is empty). It is a rate-limit bucket, NOT a blanket permission: every checkout tool denies without a credential — on demo-store in-band, as HTTP 200 with a JSON-RPC error whose error.data.code is no_credentials and no WWW-Authenticate challenge (a real merchant answers 401 with a challenge); branch on error.data.code, not on the HTTP status — and an X-Payment-Mandate header is also required by the checkout tools that spend or settle (preview_checkout, complete_checkout, process_agent_payment, complete_visa_payment, ucp_complete_checkout); the other checkout tools (create_cart and attach_agent_identity and verify_age_over_n and verify_residence_country and verify_legal_person_authorization and apply_discount and get_shipping_rates and select_shipping_option and create_payment_mandate and update_payment_mandate and cancel_payment_mandate and ucp_create_checkout and ucp_update_checkout and ucp_add_items_to_checkout and ucp_get_checkout and ucp_cancel_checkout and get_trust_receipt) don't need it.","sandbox_key":"50 req/hour (temporary keys from /api/v1/sandbox/key, valid 24h)","global_per_ip":"500 req per 15 minutes (applies before any per-key quota)","rest_agent_api":{"scope":"/api/v1/agent/* with X-Agent-Api-Key — NOT the MCP endpoint","tier_rpm":{"STARTER":100,"GROWTH":500,"PRO":2000,"ENTERPRISE":10000}},"headers":["RateLimit-Policy","RateLimit","X-RateLimit-Limit","X-RateLimit-Remaining","X-RateLimit-Reset"],"policies":["http-ip","discovery","customer","checkout","agent-global","agent-key","demo-ip","tool-<toolName>"],"retry_after_seconds_on_429":60,"note":"The /api/v1/agentfinder/search endpoint has a separate 100 req/min limit."},"trust":{"min_trust_score":0.3,"verification_levels":["UNVERIFIED","BASIC","STANDARD","PREMIUM","QUALIFIED"],"trust_info_url":"https://trusteed.xyz/en/trust","ranking_formula":"relevanceScore = (text_relevance × 0.55) + (store_trust_score × 0.25) + (freshness × 0.10) + (in_stock × 0.10)","agent_risk_signals":10,"agent_risk_signal_weights":{"checkoutVelocity":0.08,"promoProbing":0.1,"categoryDrift":0.08,"amountAnomaly":0.11,"returnRatio":0.18,"cancelPostShip":0.13,"disputeRate":0.14,"stripeRadar":0.04,"ixopayRisk":0.08,"zipBnplRisk":0.06},"smart_psp_routing":"Advisory only (sandbox). Merchants that have enabled the IXOPAY integration (MerchantPspConfig.enabled=true) receive a recommended PSP selection at checkout. Risk score is computed from 10 signals (including ixopayRisk + zipBnplRisk) and compared against merchant threshold (default 0.7) to recommend primary or fallback PSP. The recommendation does not execute real settlement yet."},"eu_ai_act_transparency":{"regulation":"EU AI Act Art. 50 (Reg. 2024/1689)","headers":{"X-Agent-Commerce":{"value":"1","scope":"all agent API and MCP gateway responses","description":"Identifies that the HTTP request was initiated by an AI agent acting on behalf of a human user."},"X-AI-Act-Transparency":{"value":"agent-initiated-transaction","scope":"transactional routes only — /checkout, /payment, /cart, /order","description":"Signals a financial or cart-mutation action performed by an AI agent. Triggers Art. 50 disclosure obligations for merchants and PSPs."}},"body_field":{"name":"agent_transaction","type":"boolean","value":true,"scope":"POST /api/v1/agent/checkout response body","description":"Indicates that the checkout was initiated by an AI agent. Available for consumers that process the response body but not HTTP headers."}},"legal":{"terms_url":"https://trusteed.xyz/en/terms","privacy_url":"https://trusteed.xyz/en/privacy","compliance_url":"https://trusteed.xyz/en/compliance"},"contact":{"email":"developers@trusteed.xyz","docs_url":"https://trusteed.xyz/api/v1/openapi.json","developer_portal":"https://trusteed.xyz/en/developers"},"demo":{"endpoint":"/demo-store/mcp","playground_url":"https://trusteed.xyz/en/demo-store/playground","agent_rules_playground":"https://trusteed.xyz/en/demo-store","agent_rules_tab":"agent-rules","agent_rules_description":"Interactive simulator: test 46 of the engine's 52 merchant rules and the KYAI policy engine against predefined agent profiles (conservative, aggressive, corporate, luxury, budget). No authentication required. Declared is not active: most rules are off in production and merchants start in observation mode.","auth_required":false,"auth_mode":"public_sandbox","no_real_payments":true,"note":"Sandbox slug for agent integration testing. Discovery tools need no credential (as on every store). Checkout tools need one here too — the self-service sandbox key from the `create_sandbox_key` tool (or POST /api/v1/sandbox/key), no OAuth required; tools_checkout_simulated is empty. Checkout responses are simulated — no payment is processed and no real order is created. Rate limit: 20 req/min per IP, max 3 concurrent demo sessions per IP, 30-minute session TTL. All other stores enforce per-tool auth_required as declared in tools_preview.","tools_semantics":"`tools_read` and `tools_checkout_simulated` are the AUTH-EXEMPTION set: the tools demo-store waives the OAuth token for. They are NOT a promise of what the endpoint registers. What `POST /demo-store/mcp` answers to `tools/list` depends on this store's own configuration and was measured at 10 tools on 2026-09-05 against the 18 these lists named then — every difference is a tool this store does not register, not a tool whose exemption is in doubt. Call `tools/list` and read the answer; use these lists only to know which of the tools you get back need no token.","tools_read":["search_products","get_product_details","browse_categories","get_merchant_profile","compare_products","get_site_map","get_page_content","search_docs","search_products_enriched"],"tools_checkout_simulated":[],"sandbox_key":"POST /api/v1/sandbox/key"},"i18n":{"default_locale":"en","supported_locales":["en","es"]},"tools_preview":[{"name":"search_tools","version":"1.0","idempotent":true,"schema_version":"2026-04-23","description":"Search available tools by keyword. Returns matching tool names and brief descriptions only. Use this instead of loading all tool definitions upfront when the catalog is large. Implements MCP Progressive Tool Discovery.","input_schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200,"description":"Keyword or phrase to match against tool names/descriptions"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20}},"required":["query"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"get_tool_details","version":"1.0","idempotent":true,"schema_version":"2026-04-23","description":"Retrieve the full schema and details for a specific tool by name. Use after `search_tools` identifies relevant candidates. Implements MCP Progressive Tool Discovery.","input_schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Exact tool name to fetch full schema for"}},"required":["name"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"explore_store","version":"1.0","idempotent":true,"schema_version":"2026-05-18","description":"Complete agent onboarding in one call — capability matrix (15 tools with available/unavailable status), 4 recommended journey paths (discovery/shopping/checkout/trust_verification), all discovery endpoints, agent-friendliness score 0–100, and a quick-start guide. Call this FIRST when connecting to a new store.","input_schema":{"type":"object","properties":{"depth":{"type":"string","enum":["quick","full"],"default":"full","description":"quick: capability matrix only. full: includes journeys, scoring, and quick-start guide."}},"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"run_scenario","version":"1.0","idempotent":true,"schema_version":"2026-05-18","description":"Run an autonomous test scenario against the store and receive structured pass/fail results with step-level evidence and suggestions. Scenarios: discovery, shopping, checkout, trust, full (runs all 4 in parallel).","input_schema":{"type":"object","properties":{"scenario":{"type":"string","enum":["discovery","shopping","checkout","trust","full"],"description":"Which scenario to run"}},"required":["scenario"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"search_products","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Search products across all verified merchants. Supports filters by category, price, stock and trust score. A2UI declarative UI grid rendering is planned but not in this schema — no 'a2ui' parameter until renderers ship. Eligibility requires BASIC+ verification and trustScore ≥ 0.3.","examples":[{"description":"Search sneakers under $100","input":{"query":"sneakers","max_price":10000,"limit":3},"output":{"products":[{"id":"prod-001","title":"Nike Air Max 90","price":9900,"currency":"USD","trustScore":0.85,"inStock":true}],"total":1}}],"a2ui_support":false,"a2ui_status":"coming_soon","a2ui_component":"ProductGrid","input_schema":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Search query (e.g. 'red sneakers', 'winter jacket'). Omit to list all products."},"category":{"type":"string","maxLength":200,"description":"Filter by category slug"},"min_price":{"type":"number","exclusiveMinimum":0,"description":"Minimum price filter"},"max_price":{"type":"number","exclusiveMinimum":0,"description":"Maximum price filter"},"sort_by":{"type":"string","enum":["relevance","price_asc","price_desc","newest","rating"],"default":"relevance","description":"Sort order for results"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Number of results (1-50)"},"cursor":{"type":"string","description":"Opaque pagination cursor from next_cursor of a previous response. Only valid for the SAME query, category, price range and sort_by — a cursor replayed against different filters is rejected, not silently applied."},"field_mask":{"type":"array","items":{"type":"string","enum":["title","price","compareAtPrice","currency","image","url","stockStatus","rating","reviewCount","rating_provenance","vendor","variants"]},"description":"Return only these product fields, to spend less of your context on a large catalogue. `id` is always included. Supplying a mask also drops the carousel/UI payloads, which are the bulk of a full response."},"compact":{"type":"boolean","default":false,"description":"When true, the same products are described only once instead of twice. `structuredContent.products` stays the full typed record — every field, every product, untouched — but the text reply becomes a short id/title/price/currency/availability line per product instead of a markdown re-narration of that same data (images, links, ratings inline). Nothing that asserts trust is affected: `merchant_trust`, `rating_provenance` and `sort_provenance_warning` are never trimmed by this flag. Ignored when `field_mask` is also set — a field mask already replaces the narration with a compact listing, so there is nothing left for `compact` to cut."}},"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"get_product_details","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Get full product info: price, variants, policies, merchant trust score, stock status.","examples":[{"description":"Get full details for a product by ID","input":{"product_id":"prod-001"},"output":{"id":"prod-001","title":"Nike Air Max 90","price":9900,"currency":"USD","description":"Classic running shoe with Air cushioning.","variants":[{"size":"42","inStock":true}],"trustScore":0.85,"returnPolicy":"30-day free returns"}}],"input_schema":{"type":"object","properties":{"product_id":{"type":"string","description":"Product ID — use the `id` field returned by search_products or nlweb_ask (e.g. 'prod-001'). Do not invent IDs."}},"required":["product_id"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"search_products_enriched","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Search products with enriched data: structured attributes (color, material, size), variants, GTIN, and multiple images. Ideal for side-by-side comparison and detailed product discovery. Backward-compatible with search_products filters.","input_schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200,"description":"Search query"},"category":{"type":"string","description":"Filter by category"},"min_price":{"type":"number","description":"Minimum price"},"max_price":{"type":"number","description":"Maximum price"},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"Max results (1-20)"}},"required":["query"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"compare_products","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Side-by-side comparison of 2-5 products with normalized attribute table, availability, ratings, and a bestValue recommendation based on price/rating ratio. Ratings are asserted by the merchant and are not verified by Trusteed, so neither is that recommendation.","input_schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":5,"description":"Array of product IDs to compare (2-5)"}},"required":["product_ids"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"get_merchant_profile","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Merchant trust score, verification level (BASIC/STANDARD/PREMIUM), return policies and shipping SLA.","input_schema":{"type":"object","properties":{},"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"browse_categories","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"List available product categories for a merchant. Returns category tree with product counts.","input_schema":{"type":"object","properties":{},"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"create_cart","version":"1.0","idempotent":false,"schema_version":"2026-01-30","description":"Create a shopping cart for a merchant. Returns a cart_id UUID. Validates stock and applies fraud detection rules.","examples":[{"description":"Create a cart with one item","input":{"items":[{"product_id":"prod-001","quantity":1}]},"output":{"cart_id":"cart_abc123","status":"NOT_READY_FOR_PAYMENT","items":[{"product_id":"prod-001","quantity":1,"price":9900}],"subtotal":9900,"currency":"USD"}}],"input_schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","description":"Product ID"},"variant_id":{"type":"string","description":"Variant ID (optional). Must match a variant id listed by get_product_details; an unknown id is rejected rather than silently replaced by the default variant."},"quantity":{"type":"integer","minimum":1,"default":1,"description":"Quantity"}},"required":["product_id"],"additionalProperties":false},"minItems":1,"description":"Items to add to cart"},"agent_session_id":{"type":"string","description":"Opaque agent session identifier for cart resume across sessions"},"display_context":{"type":"string","enum":["webview","headless"],"default":"headless","description":"Agent display capability: webview (browser) or headless"},"agent_token":{"type":"string","description":"JWS compact (EdDSA/Ed25519) signed by the agent. Required for Shopify enforcement rules R001/R002/R004. The token is embedded as a server-authoritative cart attribute — Trusteed does NOT verify the signature here; that is done offline by the Shopify Function WASM."},"idempotency_key":{"type":"string","description":"Idempotency key for this cart creation (UUID-v4 or bounded ASCII token, 1-128 chars). Equivalent to the `Idempotency-Key` header — send it here if your client cannot set headers. Retrying with the same key returns the same cart instead of creating a second one."},"agent_key":{"type":"string","description":"Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."}},"required":["items"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"complete_checkout","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Complete checkout via Shopify ACP or platform adapter. A2UI CheckoutWidget rendering is planned but not in this schema — no 'a2ui' parameter until renderers ship. Requires explicit human confirmation before execution. Idempotent by session/idempotency_key, but NOT unconditionally safe to retry: retry only on 5xx or network timeout, reusing the same idempotency_key (max 3 attempts) — never on a 4xx response (400/402/409/429), and verify via get_orders first if a response was received. Full decision tree: /.well-known/agent-playbooks.json#safe-checkout-retry.","examples":[{"description":"Complete checkout after preview (requires human confirmation for orders > $100)","input":{"checkout_session_id":"session_xyz789","idempotency_key":"idem_unique_key_001"},"output":{"status":"COMPLETED","order_id":"order_123","total":9900,"currency":"USD","confirmation_required":false}}],"human_confirmation_required":true,"a2ui_support":false,"a2ui_status":"coming_soon","a2ui_component":"CheckoutWidget","input_schema":{"type":"object","properties":{"checkout_session_id":{"type":"string","description":"Checkout session ID from preview_checkout — the same value as create_cart's cart_id (must be a valid UUID)"},"idempotency_key":{"type":"string","description":"Unique key to prevent duplicate charges on retry. Generate once per purchase attempt. Replay is enforced primarily on checkout_session_id (the existing order is returned). The first key seen for a session is recorded; reusing the same key short-circuits to the existing order."},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Buyer full name"},"email":{"type":"string","format":"email","description":"Buyer email address"},"phone":{"type":"string","description":"Buyer phone number"}},"additionalProperties":true,"description":"Optional buyer contact information"},"payment_method":{"type":"string","enum":["ACP","KYAPAY","PAYPAL","MOCK","X402"],"description":"Payment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY requires kyapay_token. ACP (Stripe-native settlement) returns a 'not enabled' response unless this deployment enables native settlement; when enabled it charges the Stripe Shared Payment Token passed as shared_payment_token. X402 is available through the configured x402 protocol flow, not this checkout tool. MOCK moves no money: it completes the order without charging. Whether a store accepts it depends on the store's configuration (it is the default on demo-store). Defaults to MOCK if not specified."},"payment_option":{"type":"string","enum":["demo_card","demo_wallet","own_wallet","merchant_card"],"description":"Payment method THE PERSON chose, when preview_checkout returned payment_options. Ask the person; never choose for them. Card numbers and wallet keys are never sent here: the person approves (and, with own_wallet, signs) on the approval page."},"kyapay_token":{"type":"string","description":"Skyfire pay or kya-pay JWT for autonomous payment via Skyfire (payment_method=KYAPAY). Alternative to passing the token in the skyfire-pay-id request header — the header takes precedence if both are provided. Claims required: sub, jti, amount (USD), cur=USD, sps."},"shared_payment_token":{"type":"string","pattern":"^spt_[A-Za-z0-9_]+$","description":"Stripe Shared Payment Token (spt_…) granted by the buyer's agent wallet for payment_method=ACP. Issued by Stripe, scoped to this merchant, amount and currency, and consumed when used: it can be charged once. Only honoured when this deployment enables native ACP settlement."},"cel_context":{"type":"object","properties":{"key_age_hours":{"type":"integer","minimum":0,"maximum":720,"description":"Age in hours of the API key/credential you are using with this store. Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"requested_scopes":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20,"description":"OAuth/permission scopes you requested when authenticating with this store — send only if it applies to you."},"product_categories":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50,"description":"Product categories present in this cart, as you understand them — send only if it applies to you."},"price_delta_bps":{"type":"integer","minimum":-10000,"maximum":10000,"description":"Difference, in basis points, between the price you discovered earlier and the cart's current price. The server may recompute this from the catalogue and replace your value."},"discount_codes_tried":{"type":"integer","minimum":0,"maximum":100,"description":"Number of discount codes you attempted before this checkout — send only if it applies to you."},"discount_bps":{"type":"integer","minimum":0,"maximum":10000,"description":"Discount applied to this cart, in basis points — send only if it applies to you."},"lowest_stock":{"type":"integer","minimum":0,"description":"Lowest remaining stock you observed across this cart's line items. Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"return_policy_mismatch":{"type":"boolean","description":"True if the return policy you were shown does not match what this store publishes elsewhere. Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"is_subscription":{"type":"boolean","description":"True if this checkout creates a recurring subscription. The server checks this itself; a value you send cannot hide what it detects."},"autorenew_consent":{"type":"boolean","description":"True if the buyer explicitly consented to auto-renewal for a subscription — send only if it applies to you."},"is_b2b":{"type":"boolean","description":"True if you are buying on behalf of a business — send only if it applies to you."},"purchase_order_hash":{"type":"string","maxLength":128,"description":"Hash of a purchase order backing a B2B purchase — send only if it applies to you."},"shipping_po_box":{"type":"boolean","description":"True if the shipping address is a PO box. The server checks this itself; a value you send cannot hide what it detects."},"shipping_freight_forwarder":{"type":"boolean","description":"True if the shipping address is a freight-forwarder address — send only if it applies to you."},"provider_confidence":{"type":"number","minimum":0,"maximum":1,"description":"Your confidence (0-1) in your own agent-provider identification — send only if it applies to you."},"stored_value_cents":{"type":"integer","minimum":0,"maximum":100000000,"description":"Stored-value amount (e.g. gift card) applied to this cart, in cents. The server checks this itself; a value you send cannot hide what it detects."},"cross_merchant_abuse":{"type":"boolean","description":"True if you have flagged this same buyer/agent for abuse at another merchant. Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"refund_ratio":{"type":"number","minimum":0,"maximum":1,"description":"This agent's refund ratio with this merchant (0-1). Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"dispute_count":{"type":"integer","minimum":0,"maximum":1000000,"description":"Number of payment disputes this agent has had with this merchant. Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"completed_orders_24h":{"type":"integer","minimum":0,"maximum":1000000,"description":"Orders this agent has completed with this merchant in the last 24 hours. Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"merchant_orders_1h":{"type":"integer","minimum":0,"maximum":1000000,"description":"Orders this merchant has received from any agent in the last hour. Merchant/platform fact — send only with evidence; it can only make a check stricter, never looser."},"digital_good_types":{"type":"array","items":{"type":"string","enum":["gift_card","license_key","downloadable","stored_value"]},"maxItems":10,"description":"Digital-good categories present in this cart — send only if it applies to you."},"agent_provider_id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9_\\-]+$","description":"Your provider identifier (e.g. \"openai\", \"anthropic\"), lowercase — send only if it applies to you."}},"additionalProperties":true,"description":"Optional enforcement context for Trusteed native MCP flows (no Shopify/WooCommerce/PrestaShop/Magento plugin). Providing these fields enables full evaluation of rules R004, R006, R008, R012-R013, R015-R017, R026-R028. See each field's own description for what it means and whether the server verifies it. These values are not signed into the receipt — do not include values you cannot substantiate."},"reconfirmed_state_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the authoritative merchant state, as returned in details.reconfirm_state_hash by a previous STATE_RECONFIRMATION_REQUIRED error. Required to proceed when the merchant state moved after the approved preview. Passing a stale hash is refused: it means the state moved again and must be reconfirmed anew."},"payment_mandate":{"anyOf":[{"type":"object","additionalProperties":{}},{"type":"string"}],"description":"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."},"agent_key":{"type":"string","description":"Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."}},"required":["checkout_session_id","idempotency_key"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"nlweb_ask","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Search products using natural language via NLWeb Discovery Layer. Returns Schema.org Product objects ranked by semantic relevance. Use when the user describes what they want in conversational language. Results include product_id for direct use in create_cart.","examples":[{"description":"Find noise-cancelling headphones under $200","input":{"query":"noise cancelling headphones under $200","mode":"list","limit":5},"output":{"query_id":"abc-123","mode":"list","results":[{"product_id":"prod-001","name":"Sony WH-1000XM5","score":0.92,"price":349.99,"currency":"USD","availability":"InStock"}],"total":1,"latency_ms":45}}],"rollout_access":"guided_beta","access_note":"Not served on any store today. Measured 2026-09-03: tools/call nlweb_ask returns -32602 'Tool nlweb_ask not found' on demo-store and on the production merchant, on both deployments, and the underlying /{slug}/ask route returns VECTOR_DB_UNAVAILABLE. Beyond the per-merchant flag, the NLWeb index has to be ready before this answers — use search_products meanwhile.","requires_nlweb_enabled":true,"input_schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":1000,"description":"Natural language product query"},"mode":{"type":"string","enum":["list","summarize","generate"],"default":"list","description":"list=ranked items, summarize=summary+items, generate=RAG answer"},"prev":{"type":"string","description":"Comma-separated previous queries for follow-up context"},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"Maximum results to return"}},"required":["query"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"requires_store_flag":"nlwebEnabled","enabled_by_default":false},{"name":"ucp_create_checkout","version":"1.0","idempotent":false,"schema_version":"2026-01-30","description":"Create a UCP checkout session from line items. Returns checkout ID and session URL.","human_confirmation_required":true,"input_schema":{"type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code (e.g. USD)"},"line_items":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"description":"Product identifier"},"title":{"type":"string","minLength":1,"description":"Ignored: the catalogue title is used. Any non-empty string is accepted."},"quantity":{"type":"integer","exclusiveMinimum":0,"description":"Quantity"},"variant_id":{"type":"string","minLength":1,"description":"Variant (size/colour) id as listed by get_product_details. Required when the product has more than one variant; the price and stock of THAT variant apply."},"price":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Ignored: the catalogue price is used and returned per line. Any non-negative integer is accepted."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}},"required":["amount","currency"],"additionalProperties":false}},"required":["product_id","title","quantity","price"],"additionalProperties":true},"minItems":1,"description":"Line items for the checkout"},"label":{"type":"string","description":"Optional label for additional identifiers (e.g. external order ref, multi-PSP reference)"},"idempotency_key":{"type":"string","description":"Required by the checkout bucket (UUID-v4 or bounded ASCII token). Choose one per purchase attempt and reuse it to retry safely. Alternatively send it as the Idempotency-Key header or params._meta[\"trusteed/idempotency-key\"]."},"intent":{"type":"object","properties":{"action":{"type":"string","description":"Intent action (e.g. 'purchase', 'gift', 'compare')"},"context":{"type":"string","description":"Natural language context for personalization"},"locale":{"type":"string","description":"ISO locale"}},"required":["action"],"additionalProperties":true,"description":"Intent context for relevance and personalization"},"agent_key":{"type":"string","description":"Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."}},"required":["currency","line_items"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"ucp_get_checkout","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Retrieve a UCP checkout session by ID. Returns status, line items and totals.","input_schema":{"type":"object","properties":{"checkout_id":{"type":"string","description":"UCP checkout session ID (valid UUID)"},"agent_key":{"type":"string","description":"Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."}},"required":["checkout_id"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"ucp_update_checkout","version":"1.0","idempotent":false,"schema_version":"2026-01-30","description":"Replace all line items in a UCP checkout session (full replace). Recalculates totals.","human_confirmation_required":true,"input_schema":{"type":"object","properties":{"checkout_id":{"type":"string","description":"UCP checkout session ID (valid UUID)"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code (e.g. USD). Optional: defaults to the checkout's currency."},"line_items":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"description":"Product identifier"},"title":{"type":"string","minLength":1,"description":"Ignored: the catalogue title is used. Any non-empty string is accepted."},"quantity":{"type":"integer","exclusiveMinimum":0,"description":"Quantity"},"variant_id":{"type":"string","minLength":1,"description":"Variant (size/colour) id as listed by get_product_details. Required when the product has more than one variant; the price and stock of THAT variant apply."},"price":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Ignored: the catalogue price is used and returned per line. Any non-negative integer is accepted."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"}},"required":["amount","currency"],"additionalProperties":false}},"required":["product_id","title","quantity","price"],"additionalProperties":true},"minItems":1,"description":"Replacement line items (replaces all lines). Omit to leave the lines as they are."},"fulfillment":{"type":"object","properties":{"destination":{"type":"object","properties":{"address1":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City"},"province_code":{"type":"string","description":"Province or state code (optional)"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. US, ES)"},"zip":{"type":"string","description":"Postal / ZIP code"}},"required":["address1","city","country_code","zip"],"additionalProperties":true,"description":"Delivery address. Sending it loads the shipping options for that destination; the response lists them in fulfillment.options."},"selected_option_id":{"type":"string","description":"Id of one of fulfillment.options. Choosing it adds the shipping amount to the totals."}},"additionalProperties":true,"description":"Delivery. Send destination first, then selected_option_id (or both in one call)."},"agent_key":{"type":"string","description":"Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."}},"required":["checkout_id"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"ucp_complete_checkout","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Complete a UCP checkout session. Idempotent by session/idempotency_key, but NOT unconditionally safe to retry — same retry policy as complete_checkout: retry only on 5xx/timeout with the same idempotency_key, never on 4xx. Full decision tree: /.well-known/agent-playbooks.json#safe-checkout-retry. Requires explicit user confirmation.","human_confirmation_required":true,"input_schema":{"type":"object","properties":{"checkout_id":{"type":"string","description":"UCP checkout session ID (valid UUID)"},"idempotency_key":{"type":"string","description":"Unique key to prevent duplicate completions. Generate once per attempt."},"payment_handler":{"type":"string","enum":["stripe","x402"],"description":"Payment handler the store profile publishes. Omit for default."},"payment_option":{"type":"string","enum":["demo_card","demo_wallet","own_wallet","merchant_card"],"description":"Payment method THE PERSON chose, when preview_checkout returned payment_options. Ask the person; never choose for them. Card numbers and wallet keys are never sent here: the person approves (and, with own_wallet, signs) on the approval page."},"shared_payment_token":{"type":"string","pattern":"^spt_[A-Za-z0-9_]+$","description":"Stripe Shared Payment Token (spt_…) granted by the buyer's agent wallet for payment_method=ACP. Issued by Stripe, scoped to this merchant, amount and currency, and consumed when used: it can be charged once. Only honoured when this deployment enables native ACP settlement."},"x402_payload":{"description":"x402: signed payment for the server offer (omit to get it)."},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Buyer full name"},"email":{"type":"string","format":"email","description":"Buyer email address"},"phone":{"type":"string","description":"Buyer phone number"}},"additionalProperties":true,"description":"Buyer name and email, needed to request the approval link."},"payment_mandate":{"anyOf":[{"type":"object","additionalProperties":{}},{"type":"string"}],"description":"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."},"agent_key":{"type":"string","description":"Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."}},"required":["checkout_id","idempotency_key"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"ucp_cancel_checkout","version":"1.0","idempotent":false,"schema_version":"2026-01-30","description":"Cancel a UCP checkout session. Releases any held inventory.","human_confirmation_required":true,"input_schema":{"type":"object","properties":{"checkout_id":{"type":"string","description":"UCP checkout session ID (valid UUID)"},"idempotency_key":{"type":"string","description":"Optional idempotency key to prevent duplicate cancellations."},"reason":{"type":"string","description":"Optional cancellation reason"},"agent_key":{"type":"string","description":"Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."}},"required":["checkout_id"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"ucp_get_catalog","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Get real-time product prices and inventory (UCP catalog capability)","confirm":false,"capability":"dev.ucp.catalog.realtime","input_schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"description":"Product IDs to fetch. Omit for first page of catalog."},"cursor":{"type":"string","description":"Pagination cursor from previous response"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum products to return per page (1-100, default 20)"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"requires_store_flag":"ucpCatalogEnabled","enabled_by_default":false},{"name":"onx_get_orders","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Retrieve orders for a merchant store. Supports filtering by status, date range, and customer. Returns order details including line items, totals, fulfillment status, and tracking info.","confirm_required":false,"input_schema":{"type":"object","properties":{"orderId":{"type":"string","minLength":1,"description":"Specific order ID to look up"},"status":{"type":"string","enum":["pending","confirmed","processing","shipped","delivered","cancelled","refunded"],"description":"Filter by order status (pending, confirmed, processing, shipped, delivered, cancelled, refunded)"},"dateFrom":{"type":"string","format":"date-time","description":"Filter orders created on or after this ISO 8601 date"},"dateTo":{"type":"string","format":"date-time","description":"Filter orders created on or before this ISO 8601 date"},"page":{"type":"integer","exclusiveMinimum":0,"default":1,"description":"Page number for pagination (default: 1)"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Number of orders per page (1-50, default: 20)"}},"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"onx_get_fulfillments","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Retrieve fulfillment records for an order. Returns shipment tracking numbers, carrier info, line items included in each fulfillment, and delivery status.","confirm_required":false,"input_schema":{"type":"object","properties":{"orderId":{"type":"string","minLength":1,"description":"Order ID to retrieve fulfillment/tracking details for"}},"required":["orderId"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"onx_get_inventory","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Retrieve current inventory levels for products. Returns stock quantities per location, reserved units, and restock dates when available.","confirm_required":false,"input_schema":{"type":"object","properties":{"sku":{"type":"string","minLength":1,"description":"Product SKU to check inventory for"},"productId":{"type":"string","minLength":1,"description":"Platform product ID to check inventory for"},"locationId":{"type":"string","minLength":1,"description":"Warehouse / location ID to filter results"}},"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":false,"enabled_by_default":true},{"name":"onx_create_return","version":"1.0","idempotent":false,"schema_version":"2026-01-30","description":"Initiate a return request for one or more items in an order. Validates return eligibility against merchant return policy window. Requires explicit human confirmation before execution.","confirm_required":true,"human_confirmation_required":true,"input_schema":{"type":"object","properties":{"orderId":{"type":"string","minLength":1,"description":"The order ID to create a return for"},"lineItems":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","minLength":1,"description":"The line item ID to return"},"quantity":{"type":"integer","exclusiveMinimum":0,"description":"Quantity to return"},"reason":{"type":"string","description":"Reason for returning this item"}},"required":["lineItemId","quantity"],"additionalProperties":true},"minItems":1,"description":"Line items to return with quantities and optional reasons"}},"required":["orderId","lineItems"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"onx_get_returns","version":"1.0","idempotent":true,"schema_version":"2026-01-30","description":"Retrieve return requests for an order or store. Returns return status, refund amount, return shipping label URL, and processing timeline.","confirm_required":false,"input_schema":{"type":"object","properties":{"orderId":{"type":"string","minLength":1,"description":"Filter returns by order ID"},"returnId":{"type":"string","minLength":1,"description":"Look up a specific return by its ID"}},"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true},{"name":"onx_cancel_order","version":"1.0","idempotent":false,"schema_version":"2026-01-30","description":"Cancel an order that has not yet been fulfilled. Validates cancellation eligibility. Triggers refund if payment was captured. Requires explicit human confirmation before execution.","confirm_required":true,"human_confirmation_required":true,"input_schema":{"type":"object","properties":{"orderId":{"type":"string","minLength":1,"description":"The order ID to cancel"},"reason":{"type":"string","description":"Reason for cancellation"}},"required":["orderId"],"additionalProperties":true,"$schema":"http://json-schema.org/draft-07/schema#"},"auth_required":true,"enabled_by_default":true}]}