For Integrators

Developer Documentation

Everything you need to integrate Trusteed with your application

MCP Agent Setup — 3 steps

Configure your AI agent to browse products, create carts, and initiate checkout through the MCP protocol.

Add the MCP server to your agent

Add Trusteed to your agent's MCP configuration. Replace {slug} with the merchant store slug.

{
  "mcpServers": {
    "trusteed": {
      "url": "https://trusteed.xyz/{slug}/mcp",
      "headers": { "X-Agent-Api-Key": "agnt_your_key" }
    }
  }
}

No key yet? Try the public demo: https://trusteed.xyz/demo-store/mcp (no auth, read-only)

Search products with filters

Call search_products to explore the catalog. Filter by category, price range, or availability.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": { "query": "running shoes", "max_price": 200, "in_stock_only": true, "limit": 5 }
  }
}

Recommended: only proceed to cart if merchant trustScore ≥ 0.70

Create cart and complete checkout

Use create_cart to add items, then preview_checkout to review totals, and complete_checkout to finalize. Always confirm with the user before checkout.

// Step 3a — create cart
{ "method": "tools/call", "params": { "name": "create_cart", "arguments": { "items": [{ "product_id": "prod_abc123", "quantity": 1 }] } } }

// Step 3b — preview checkout
{ "method": "tools/call", "params": { "name": "preview_checkout", "arguments": { "cart_id": "cart_xyz789" } } }

// Step 3c — complete checkout (returns URL, no payment processed)
{ "method": "tools/call", "params": { "name": "complete_checkout", "arguments": { "cart_id": "cart_xyz789" } } }

complete_checkout returns a URL — payment happens on merchant's secure page. Never auto-confirm without user approval.

Quick Start

No API key? Start with the public demo endpoint. Have a key? Jump to the authenticated REST examples below.

No API key — try nowLive

Zero setup — no registration required. Uses MCP protocol (JSON-RPC 2.0). 20 requests/min per IP.

curl https://trusteed.xyz/demo-store/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_products",
      "arguments": { "query": "running shoes" }
    }
  }'

Authenticated REST API (requires X-Agent-Api-Key)

curl

curl -X POST https://trusteed.xyz/api/v1/agent/search \
  -H "X-Agent-Api-Key: agnt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "running shoes", "limit": 5}'

Python

import requests

response = requests.post(
    "https://trusteed.xyz/api/v1/agent/search",
    headers={"X-Agent-Api-Key": "agnt_your_key"},
    json={"query": "running shoes", "limit": 5}
)
data = response.json()

JavaScript

const res = await fetch(
  "https://trusteed.xyz/api/v1/agent/search",
  {
    method: "POST",
    headers: {
      "X-Agent-Api-Key": "agnt_your_key",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ query: "running shoes", limit: 5 })
  }
);
const data = await res.json();

Authentication

Two authentication methods depending on your integration type.

Agent API Key (Recommended)

X-Agent-Api-Key: agnt_xxx

For autonomous AI agents. Create a key once — use it without a session.

• agent:read — catalog browsing
• agent:cart — cart creation
• agent:checkout — checkout initiation

JWT Bearer

Authorization: Bearer <token>

For authenticated users. Obtain via POST /api/v1/auth/login.

Create an Agent API Key

# 1. Obtain JWT first
curl -X POST https://trusteed.xyz/api/v1/auth/login \
  -d '{"email":"you@example.com","password":"..."}' | jq .token

# 2. Create Agent API Key (plaintext returned once — store securely)
curl -X POST https://trusteed.xyz/api/v1/agent-keys \
  -H "Authorization: Bearer <jwt>" \
  -d '{"scopes":["agent:read","agent:cart","agent:checkout"]}'

Try without a key — Demo & Health endpoints

Live

The demo-store MCP endpoint is public (read-only catalog, JSON-RPC 2.0). The health check is also unauthenticated.

Working cURL — copy and run immediately:

curl https://trusteed.xyz/demo-store/mcp \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_products","arguments":{"query":"shoes"}}}'

Demo store MCP endpoint (public, no auth)POST https://trusteed.xyz/demo-store/mcp
Health check (GET, no auth)GET https://trusteed.xyz/api/v1/health
Trust score methodology (GET, no auth) — 12 components, weights, verified vs declared, ELITE ≥0.95 / VERIFIED ≥0.85 / STANDARD ≥0.70GET https://trusteed.xyz/api/v1/trust/methodology

Auth & Compliance

Enterprise-grade authentication and regulatory compliance, machine-readable and verifiable.

OAuth 2.1 + PKCE (MCP spec 2025-11-25)

Authorization server: Auth0
Discovery: /.well-known/oauth-authorization-server(RFC 8414)

Protected Resource Metadata

RFC 9728: declares protected scopes and token endpoint
Machine-readable: /.well-known/oauth-protected-resource

EU AI Act Art. 50 — Transparency headers

X-AI-Agent-Initiated: true on all agent-originated requests
X-Human-Confirmation-Required: true on confirmation-required actions

MCP spec 2025-11-25 compliant

Server card: /.well-known/mcp.json

MCP Tools

40+ tools are available via the MCP endpoint, including a public discovery subset that works without auth. Read-only tools execute without human confirmation, while write tools always require it.

Tool	Method	Path	Auth Required	Human Confirmation
`search_products` Search catalog with filters (public)	POST	MCP tool	No	Never
`get_product_details` Full product data with policies (public)	POST	MCP tool	No	Never
`browse_categories` Browse product categories (public)	POST	MCP tool	No	Never
`compare_products` Side-by-side product comparison (public)	POST	MCP tool	No	Never
`nlweb_ask` AI semantic search with NLWeb (public)	POST	MCP tool	No	Never
`get_merchant_profile` Trust score, identity verification, policies (public)	POST	MCP tool	No	Never
`create_cart` Cart with stock validation	POST	MCP tool	Yes	Required
`get_shipping_rates` Calculate shipping costs	POST	MCP tool	Yes	Never
`preview_checkout` Order summary before payment (public)	POST	MCP tool	No	Never
`complete_checkout` Returns checkout URL — no payment processing	POST	MCP tool	Yes	Required
`onx_get_orders` Query fulfilled orders (post-checkout)	POST	MCP tool	Yes	Never
`onx_create_return` Initiate product return request	POST	MCP tool	Yes	Required

Webhooks

Subscribe to events in Settings > Webhooks. All payloads include an X-Webhook-Signature header.

order.createdorder.status_changedcheckout.abandoned

Example payload — order.created

{
  "event": "order.created",
  "timestamp": "2026-03-19T14:32:00Z",
  "orderId": "ord_xyz123",
  "merchantSlug": "running-gear-pro",
  "totalAmount": 124.99,
  "currency": "USD",
  "status": "pending"
}

Verify HMAC-SHA256 signature (Stripe-style with replay protection)

Python

import hmac, hashlib, time

# Header format: X-Webhook-Signature: t=<unix_ts>,v1=<hex_sig>
# v1 = HMAC_SHA256(secret, "<unix_ts>.<raw_body>")
def verify_webhook(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    ts, v1 = parts.get("t"), parts.get("v1")
    if not ts or not v1: return False
    if abs(int(time.time()) - int(ts)) > tolerance: return False  # replay guard
    signed = f"{ts}.".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Node.js

import crypto from "crypto";

// Header format: X-Webhook-Signature: t=<unix_ts>,v1=<hex_sig>
// v1 = HMAC_SHA256(secret, "<unix_ts>.<raw_body>")
function verifyWebhook(body: string, header: string, secret: string, toleranceSec = 300): boolean {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=", 2)));
  const ts = Number(parts.t);
  if (!ts || !parts.v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > toleranceSec) return false; // replay guard
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
  const a = Buffer.from(parts.v1, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

API Response Format

All agent endpoints return a consistent JSON envelope. Product records are designed to be passed directly to LLM context windows.

{
  "success": true,
  "data": [
    {
      "id": "prod_abc123",
      "name": "Ultra Boost Running Shoe",
      "price": 119.99,
      "currency": "USD",
      "stock_status": "in_stock",
      "merchant": {
        "slug": "running-gear-pro",
        "trust_score": 0.91,
        "verification_level": "STANDARD"
      },
      "policies": {
        "return_window_days": 30,
        "free_shipping_threshold": 75,
        "shipping_estimate_days": "2-4"
      }
    }
  ],
  "meta": {
    "total": 48,
    "page": 1,
    "limit": 5
  }
}

Rate Limits

All MCP Gateway requests count against two independent limits: a per-tier bucket and a per-tool bucket. Both must have capacity for a request to succeed.

MCP Gateway — limits by tier

Plan	Req / min
FREE	30
STARTER	30
GROWTH	200
PRO	1,000
ENTERPRISE	5,000

Per-tool limits (additional to tier limit)

Tool	Limit
`search_products`	20 / min
`search_products_enriched`	15 / min
`create_cart`	20 / min
`complete_checkout`	10 / min

Public REST endpoints (trust score, directory): 30 req/min per IP.

Response headers

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1714000800

Retry logic for agents

1On 429, read X-RateLimit-Reset (Unix timestamp in seconds).
2Wait until that timestamp before retrying.
3Use exponential backoff: 1 s → 2 s → 4 s → 8 s.
4Never retry more than 4 times per call chain.

Interactive API Docs

Browse and test all endpoints with Swagger UI. Try requests directly from your browser.

Open Swagger UI

GET /api/docs
HTTP/1.1 200 OK

Swagger UI - Interactive
API Documentation

Developer FAQ

View full FAQ

What authentication method does the Trusteed API use?

The API uses Bearer token authentication via JWT. Obtain a token by calling POST /api/v1/auth/login, then include it in the Authorization header of subsequent requests.

Is there an MCP endpoint I can connect AI agents to?

Yes. Each store gets a unique MCP endpoint at /{store-slug}/mcp. MCP-compatible AI agents can connect to search products, check availability, and initiate checkout flows.

What rate limits apply to the API?

The MCP Gateway enforces two independent limits: a per-tier bucket (FREE/STARTER 30 req/min, GROWTH 200, PRO 1,000, ENTERPRISE 5,000) and a per-tool bucket (e.g. complete_checkout capped at 10/min). On a 429 response, read X-RateLimit-Reset and wait until that Unix timestamp before retrying. See the Rate Limits section for full details.

Which e-commerce platforms are supported natively?

Shopify, WooCommerce, and Odoo are supported natively with automated sync. PrestaShop is supported in beta via the Webservice API. Any other platform can be integrated via our REST API by pushing catalog and order data manually.

What is merchant identity verification and how does it affect trust scores?

Merchant identity verification is the process by which we confirm a merchant's legal business identity. Merchants with VERIFIED status have completed KYB checks and receive higher trust scores. Agents should only proceed to checkout with merchants scoring ≥ 0.70.

How do I get an Agent API key for autonomous AI agents?

Create a key via POST /api/v1/agent-keys with your JWT. The plaintext key is returned once — store it securely. Keys follow the format agnt_xxx and support scopes: search, checkout, and orders.

Does the API return structured product data compatible with LLMs?

Yes. Product responses include normalized fields: name, description, price, currency, stock status, return policy, and shipping estimate — designed to be passed directly to LLM context windows.

How do I handle webhooks for order status updates?

Register a webhook URL in Settings > Webhooks. We POST JSON payloads for events: order.created, order.status_changed, and checkout.abandoned. Verify payloads with the HMAC-SHA256 signature in X-Webhook-Signature.

Is there an OpenAPI / Swagger spec I can import?

Yes. The full OpenAPI 3.0 spec is at /api/v1/openapi.json. Import it into Postman or Insomnia.

Related resources

Protocol Matrix

ACP, AP2, x402, UCP — full comparison

Market Outlook

Agentic commerce data and forecasts

For AI Agents

Trust scores, rate limits, and MCP contracts

SDK Quickstarts

Connect from OpenAI Agents, Claude, or Vercel AI SDK in minutes

Ready to integrate?

Start free today and connect your store to AI agents.

Get Started