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

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

Python

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Node.js

import crypto from "crypto";

function verifyWebhook(body: Buffer, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

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
  }
}

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 /mcp/{store-slug}. MCP-compatible AI agents can connect to search products, check availability, and initiate checkout flows.

What rate limits apply to the API?

Public beta environments use protective fair-use limits and include standard rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Higher throughput for commercial rollout is handled through direct planning, not public self-serve tiers yet.

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

Ready to integrate?

Start free today and connect your store to AI agents.

Get Started