{"openapi":"3.1.0","info":{"title":"Trusteed API","description":"REST API for multi-protocol commerce with MCP integration. Powers agent-driven shopping across Stripe (ACP), Google (AP2), Visa VIC, PayPal, Mastercard Agent Pay, and USDC stablecoin (x402) payments.","version":"1.2.0","contact":{"name":"Trusteed","url":"https://trusteed.xyz"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.trusteed.xyz/api/v1","description":"Production API"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Products","description":"Product search, details, comparison, and discovery"},{"name":"Checkout","description":"Cart, checkout, orders, refunds, and coupons"},{"name":"Wallet","description":"Onchain wallet provisioning for x402 settlement"},{"name":"Merchant","description":"Merchant profile, protocols, and policies"},{"name":"System","description":"System health and status"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Agent-Api-Key","description":"Agent API key for authentication"}},"schemas":{"MerchantSummary":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"trustScore":{"type":["number","null"],"minimum":0,"maximum":1},"verificationLevel":{"type":"string","enum":["UNVERIFIED","BASIC","STANDARD","PREMIUM"]},"storeStatus":{"type":"string","enum":["active","deprioritized"]},"lastSyncAt":{"type":["string","null"],"format":"date-time"}},"required":["slug","name","trustScore","verificationLevel","storeStatus"]},"ProductSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"price":{"type":"number"},"compareAtPrice":{"type":["number","null"]},"currency":{"type":"string"},"inStock":{"type":"boolean"},"imageUrl":{"type":["string","null"]},"category":{"type":["string","null"]},"merchant":{"$ref":"#/components/schemas/MerchantSummary"},"relevanceScore":{"type":"number"},"freshnessTier":{"type":"string","enum":["fresh","good","stale","very_stale","unknown"]},"stockConfidence":{"type":"string","enum":["high","medium","low"]},"priceConfidence":{"type":"string","enum":["high","medium","low"]},"why_ranked":{"type":"string","description":"Human-readable explanation of ranking"},"euQualified":{"type":"boolean"}},"required":["id","title","description","price","compareAtPrice","currency","inStock","imageUrl","category","merchant","relevanceScore","freshnessTier","stockConfidence","priceConfidence","why_ranked","euQualified"]},"SearchResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true},"data":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["total","page","limit","totalPages"]},"queryMeta":{"type":"object","additionalProperties":{}}},"required":["products","meta","queryMeta"]},"meta":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["success","error"]},"SearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"filters":{"type":"object","properties":{"minPrice":{"type":"number","minimum":0},"maxPrice":{"type":"number","minimum":0},"category":{"type":"string"},"inStock":{"type":"boolean","default":true},"minTrustScore":{"type":"number","minimum":0,"maximum":1},"verificationLevel":{"type":"string","enum":["BASIC","STANDARD","PREMIUM","QUALIFIED"]}}},"sort":{"type":"string","enum":["relevance","price_asc","price_desc","trust_score","newest"],"default":"relevance"},"page":{"type":"integer","minimum":1,"default":1},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Server caps the effective limit at 100 regardless of the value sent."},"deduplicate":{"type":"boolean","description":"Read directly from the raw body (not part of the validated schema) — collapses near-duplicate titles across merchants, keeping the highest-scoring result."}},"required":["query"]},"ProductDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"price":{"type":"number"},"compareAtPrice":{"type":["number","null"]},"currency":{"type":"string"},"inStock":{"type":"boolean"},"stockQuantity":{"type":["number","null"]},"images":{"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"type":"object","additionalProperties":{}}},"attributes":{"type":"object","additionalProperties":{}},"category":{"type":["string","null"]},"merchant":{"$ref":"#/components/schemas/MerchantSummary"},"policies":{"type":"object","properties":{"returnWindowDays":{"type":"number"},"acceptsReturns":{"type":"boolean"},"freeShippingThreshold":{"type":"number"},"restockingFeePercent":{"type":"number"},"shippingEstimateDays":{"type":"string"},"supportResponseTimeSla":{"type":"string"}},"required":["acceptsReturns"]},"freshnessTier":{"type":"string","enum":["fresh","good","stale","very_stale","unknown"]}},"required":["id","title","description","price","compareAtPrice","currency","inStock","stockQuantity","images","variants","attributes","category","merchant","policies","freshnessTier"]},"ProductDetailResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true},"data":{"$ref":"#/components/schemas/ProductDetail"},"meta":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"CompareProductsRequest":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":10}},"required":["productIds"]},"RecommendationsRequest":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"limit":{"type":"number","exclusiveMinimum":0,"description":"Capped at 20 server-side. Default 5."}},"required":["productId"]},"NegotiateRequest":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"merchantSlug":{"type":"string"},"bidPrice":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"3-letter ISO 4217 code","example":"USD"}},"required":["productId","merchantSlug","bidPrice","currency"]},"ShippingEstimateRequest":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"2-letter ISO 3166-1 code","example":"US"}},"required":["productId","postalCode","countryCode"]},"SearchByImageRequest":{"type":"object","properties":{"imageUrl":{"type":"string","format":"uri"}},"required":["imageUrl"]},"CreateCartRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"variant_id":{"type":"string","format":"uuid"}},"required":["product_id","quantity"]},"minItems":1}},"required":["items"]},"InitiateCheckoutRequest":{"type":"object","properties":{"cartId":{"type":"string","format":"uuid"},"payment_rail":{"type":"string","enum":["stripe","x402"],"default":"stripe"},"x402_payload":{"type":"object","additionalProperties":{},"description":"Required when payment_rail='x402'. Full x402 v2 PaymentPayload (X402PaymentPayloadSchema) — see the x402 protocol spec."},"x402_config":{"type":"object","properties":{"merchant_wallet_address":{"type":"string","minLength":1},"network":{"type":"string","minLength":1},"facilitator_url":{"type":"string","format":"uri"},"asset_address":{"type":"string"},"facilitator_version":{"type":"string","enum":["v1","v2"]}},"required":["merchant_wallet_address","network","facilitator_url"],"description":"Required when payment_rail='x402'. The merchant's server-configured x402 wallet/facilitator overrides this when present; a mismatched merchant_wallet_address is rejected when SPEC005_X402_CONFIG_ENFORCED=true, otherwise observed and overridden."}},"required":["cartId"]},"ProposeRefundRequest":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Cents. Omit for a full refund."},"reason":{"type":"string","maxLength":255}}},"ApplyCouponRequest":{"type":"object","properties":{"cartId":{"type":"string","format":"uuid"},"code":{"type":"string"}},"required":["cartId","code"]},"ProvisionWalletRequest":{"type":"object","properties":{"network":{"type":"string","enum":["eip155:8453","eip155:84532"],"default":"eip155:84532","description":"CAIP-2 chain id. 8453 = Base mainnet, 84532 = Base Sepolia."}}}},"parameters":{}},"paths":{"/agent/search":{"post":{"summary":"Search products","operationId":"search_products","description":"Search products across eligible merchants (verificationLevel BASIC+, trustScore ≥0.3, not suspended). Ranking: text_relevance×0.55 + store_trust_score×0.25 + freshness×0.10 + in_stock×0.10.","tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful search response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent/products/{id}":{"get":{"summary":"Get product details","operationId":"get_product_details","description":"Get detailed information about a specific product.","tags":["Products"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Product details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetailResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent/availability/{id}":{"get":{"summary":"Check product availability","operationId":"check_product_availability","description":"Check stock and data-freshness for a product, with a freshnessTier and an actionable agentHint.","tags":["Products"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Availability retrieved successfully"},"404":{"description":"Product not found"}}}},"/agent/products/{id}/price-history":{"get":{"summary":"Get product price history","operationId":"get_product_price_history","description":"Historical pricing data and trend for a product. Requires the `price_history` feature tier.","tags":["Products"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["30","60","90"],"description":"Default 30."},"required":false,"name":"days","in":"query"}],"responses":{"200":{"description":"Price history retrieved successfully"},"400":{"description":"days must be 30, 60, or 90"},"404":{"description":"Product not found or not available"}}}},"/agent/products/{id}/sustainability":{"get":{"summary":"Get product sustainability score","operationId":"get_product_sustainability","description":"ESG sustainability score for a product. Requires the `sustainability` feature tier.","tags":["Products"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Sustainability score retrieved successfully"},"404":{"description":"Product not found or not available"}}}},"/agent/compare":{"post":{"summary":"Compare products","operationId":"compare_products","description":"Compare up to 10 products side-by-side: price range, best value/trust/return-policy/shipping, and a recommendation.","tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareProductsRequest"}}}},"responses":{"200":{"description":"Comparison generated successfully"},"400":{"description":"Invalid request"}}}},"/agent/recommendations":{"post":{"summary":"Get product recommendations","operationId":"get_recommendations","description":"Cross-merchant recommendations related to a product. Requires the `recommendations` feature tier.","tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationsRequest"}}}},"responses":{"200":{"description":"Recommendations retrieved successfully"},"404":{"description":"Product not found or not available"}}}},"/agent/negotiate":{"post":{"summary":"Submit a price negotiation bid (BETA)","operationId":"negotiate_price","description":"Submit a price negotiation bid for a product. Requires the `negotiate` feature tier. BETA.","tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiateRequest"}}}},"responses":{"200":{"description":"Negotiation processed"},"400":{"description":"Invalid bid price"},"404":{"description":"Product or merchant not found/available"}}}},"/agent/shipping-estimate":{"post":{"summary":"Estimate shipping for a product","operationId":"get_shipping_estimate","description":"Estimate shipping cost and delivery time for a product to a destination. Requires the `shipping_estimate` feature tier.","tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingEstimateRequest"}}}},"responses":{"200":{"description":"Shipping estimate generated"},"400":{"description":"Invalid request"},"404":{"description":"Product not found or merchant not eligible"}}}},"/agent/search-by-image":{"post":{"summary":"Search products by image (not yet implemented)","operationId":"search_by_image","description":"Requires the `search_by_image` feature tier. Currently always returns 501 Not Implemented — reserved for an upcoming release.","tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchByImageRequest"}}}},"responses":{"501":{"description":"Not implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent/cart":{"post":{"summary":"Create a shopping cart","operationId":"create_cart","description":"Initialize a new shopping cart with items. Requires the agent key's `cart` scope; not available to SANDBOX-tier keys.","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCartRequest"}}}},"responses":{"201":{"description":"Cart created successfully"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Missing `cart` scope, or a SANDBOX-tier key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent/checkout":{"post":{"summary":"Initiate checkout","operationId":"initiate_checkout","description":"Initiate checkout for a cart (ACP by default). Requires the agent key's `checkout` scope; not available to SANDBOX-tier keys. Runs the KYAI risk gate before settlement (observe or enforce, per SPEC005_KYAI_GATE_MODE) and may return 202 user_action_required for a human-in-the-loop step-up. Requests detected as a different protocol (AP2, x402, UCP, ... via the `x-protocol` header or body shape) are routed through the Protocol Bridge instead, with a different response shape. payment_rail='x402' dispatches settlement over x402 and may return 402 or 207 (partial multi-store success).","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout initiated (ACP flow) or completed"},"202":{"description":"user_action_required — human confirmation needed"},"207":{"description":"Partial success across a multi-store x402 checkout"},"400":{"description":"Invalid cart ID or missing x402 fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Payment required (x402)"},"403":{"description":"Missing `checkout` scope, SANDBOX-tier key, KYAI policy block, or Shopify store on a non-native rail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Cart not found (including cross-tenant ownership mismatch)"}}}},"/agent/orders/{id}":{"get":{"summary":"Get order status","operationId":"get_order_status","description":"Order status with event history. Scoped to orders owned by the calling agent key.","tags":["Checkout"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Order status retrieved successfully"},"404":{"description":"Order not found"}}}},"/agent/orders/{orderId}/refund":{"post":{"summary":"Propose a refund","operationId":"propose_refund","description":"Propose a refund for a PayPal order (status PENDING_APPROVAL) — requires human merchant approval via the dashboard. The calling agent key must hold a non-blocked merchant allowlist binding for the order's store.","tags":["Checkout"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"orderId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposeRefundRequest"}}}},"responses":{"201":{"description":"Refund request created — awaiting merchant approval"},"400":{"description":"Invalid order ID or refund request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Order not found (including cross-merchant allowlist mismatch)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent/apply-coupon":{"post":{"summary":"Apply a coupon to a cart","operationId":"apply_coupon","description":"Apply a coupon code to a cart. Requires the `apply_coupon` feature tier. MVP: matches against a hardcoded fixture list (WELCOME10, SAVE20, FLAT5, FREESHIP, TEST*), not per-merchant discount codes.","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyCouponRequest"}}}},"responses":{"200":{"description":"Coupon applied (or rejected as invalid) successfully"},"400":{"description":"Invalid cartId or code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Cart not found (including cross-tenant ownership mismatch)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Cart is not open","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent/cart/apply-coupon":{"post":{"summary":"Apply a coupon to a cart (alias)","operationId":"apply_coupon_cart_alias","description":"Identical handler to POST /agent/apply-coupon — kept so this path and the one documented in llms-tools.txt never diverge.","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyCouponRequest"}}}},"responses":{"200":{"description":"Coupon applied (or rejected as invalid) successfully"},"400":{"description":"Invalid cartId or code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Cart not found (including cross-tenant ownership mismatch)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Cart is not open","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent/wallet/provision":{"post":{"summary":"Provision an onchain wallet","operationId":"provision_wallet","description":"Provision a Coinbase CDP wallet for the calling agent identity, for x402 settlement. One wallet per agent identity.","tags":["Wallet"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionWalletRequest"}}}},"responses":{"201":{"description":"Wallet provisioned successfully"},"400":{"description":"Invalid network"},"409":{"description":"A wallet already exists for this agent identity"}}}},"/agent/wallet":{"get":{"summary":"Get the agent's onchain wallet","operationId":"get_wallet","description":"Fetch the calling agent identity's provisioned CDP wallet.","tags":["Wallet"],"responses":{"200":{"description":"Wallet retrieved successfully"},"404":{"description":"No wallet provisioned for this agent identity"}}}},"/agent/merchants/{slug}":{"get":{"summary":"Get merchant information","operationId":"get_merchant","description":"Merchant info with trust score, verification level, storeStatus, and policies. Only merchants with verificationLevel BASIC+ and trustScore ≥0.3 are returned.","tags":["Merchant"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Merchant retrieved successfully"},"404":{"description":"Merchant not found or not eligible"}}}},"/agent/merchants/{slug}/protocols":{"get":{"summary":"Discover merchant payment protocols","operationId":"get_merchant_protocols","description":"Payment protocols supported by a merchant, and the preferred one.","tags":["Merchant"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Protocols retrieved successfully"},"404":{"description":"Merchant not found"}}}},"/agent/merchants/{slug}/return-policy":{"get":{"summary":"Get merchant return policy","operationId":"get_merchant_return_policy","description":"Structured, machine-readable return/refund policy for a merchant. Requires the `return_policy` feature tier.","tags":["Merchant"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Return policy retrieved successfully"},"404":{"description":"Merchant not found or not eligible"}}}},"/agent/merchants/{slug}/trust-explanation":{"get":{"summary":"Explain a merchant's trust score","operationId":"get_merchant_trust_explanation","description":"Human-readable explanation of a merchant's trust score: strengths, weaknesses, trend, and recommendation.","tags":["Merchant"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Trust explanation retrieved successfully"},"404":{"description":"Merchant not found or not eligible"}}}},"/health":{"get":{"summary":"Health check","operationId":"health_check","description":"API health status, protocol availability, and subsystem readiness. No authentication required.","tags":["System"],"security":[],"responses":{"200":{"description":"API is healthy or degraded (still 200/503 by db status)"}}}},"/agent/docs":{"get":{"summary":"Redirect to the OpenAPI spec","operationId":"get_api_docs_redirect","description":"302 redirect to GET /api/v1/openapi.json. No authentication required.","tags":["System"],"security":[],"responses":{"302":{"description":"Redirect to the OpenAPI specification JSON"}}}}},"webhooks":{}}