Developer Documentation

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)
#    "name" is required; scopes outside the valid list are rejected with 400
curl -X POST https://trusteed.xyz/api/v1/agent-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","scopes":["search","compare","cart","merchants:read"]}'

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)

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)

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

MCP Gateway — per-key bucket

MCP store API keys carry no tier information, so the gateway applies the STARTER bucket (30 req/min) to every key regardless of plan. Size your backoff against that number, not against your plan's row. Tier differentiation is real on the agentic REST API below.

Per-tool limits (on top of the per-key bucket)

The other three layers

• Global, per IP or authenticated user: 500 requests per 15 minutes — note the window, it is not per minute. Anonymous traffic hits this one first.
• Demo store (/demo-store/mcp, no key): 20 req/min per IP.
• Agentic REST API (/api/v1/agent/*, X-Agent-Api-Key): per key and minute, by real tier — STARTER 100, GROWTH 500, PRO 2,000, ENTERPRISE 10,000.
• Public REST endpoints (trust score, directory): 30 req/min per IP.