Trust Check MCP Server

trust-check-mcp

Open client and API spec for PaladinFi Trust Check — free wallet-OFAC SDN screening and sample-fixture trust-check preview for AI agents on Base. This repository contains the public REST and MCP API specification, working code examples, and thin client wrappers. The hosted backend is proprietary.

Operated by Malcontent Games LLC, doing business as PaladinFi.

---

What is PaladinFi Trust Check?

A free wallet-OFAC-SDN screening surface for AI agents on Base. Single MCP tool call returns a binary allow / block verdict against the US Treasury OFAC SDN list.

• No auth surface. No API key, no signup, no billing.
• Live US Treasury OFAC SDN data. Refreshed daily from the Treasury XML feed.
• Freshness metadata per response. _ofac_list_updated_at (ISO timestamp) and _ofac_sdn_count exposed in every response; callers can verify staleness without trusting our bookkeeping.
• Rate limit. 1 request per second per IP + burst 3 + 3 concurrent connections per IP.
• Non-custodial, read-only. No money handling, no calldata, no signing surface, no transaction execution.

This MCP is the off-chain HTTP surface for sanctions screening. For in-contract gate logic (Solidity modifiers running inside settlement contracts), on-chain sanctions oracles remain the canonical surface.

Install (MCP)

For Claude Code or any MCP-compatible client supporting Streamable-HTTP transport:

claude mcp add --transport http --scope user paladin-trust https://trust.paladinfi.com/mcp

Verify the host is up before adding:

curl -i https://trust.paladinfi.com/health
# Expect: HTTP/1.1 200 OK

After mcp add, restart your client. Three tools become available:

• trust_check_ofac_free(address, chainId?) — live US Treasury OFAC SDN wallet-screen. Returns recommendation: "allow" | "block" with _real: true plus freshness metadata.
• trust_check_preview(address, chainId?) — sample-fixture preview of the broader trust-check response shape. Returns _real: false, every factor is real: false, and recommendation is prefixed sample-. Do not use the preview verdict to gate real swaps, signing, or any production agent decision.
• trust_check_health() — liveness, supported chains, OFAC list refresh timestamp + size.

See mcp-tools.json for the full tool schemas.

REST API

The MCP server fronts three REST endpoints. The backend is hosted alongside other PaladinFi services on a shared origin (swap.paladinfi.com); this MCP is scoped to read-only OFAC screening and does not expose calldata, signing, or transaction surfaces from the broader platform. The REST endpoints can be called directly via curl:

# Free OFAC SDN screen
curl -X POST https://swap.paladinfi.com/v1/trust-check/ofac \
  -H "content-type: application/json" \
  -d '{"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'

# Sample-fixture preview
curl -X POST https://swap.paladinfi.com/v1/trust-check/preview \
  -H "content-type: application/json" \
  -d '{"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'

See openapi.yaml for the full schemas.

Coverage and limits

Response shape

trust_check_ofac_free

{
  "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "chainId": 8453,
  "_real": true,
  "_ofac_list_updated_at": "2026-05-23T04:06:35Z",
  "_ofac_sdn_count": 93,
  "_scope": "ofac-only",
  "trust": {
    "recommendation": "allow",
    "factors": [
      {
        "source": "ofac",
        "signal": "not_listed",
        "real": true,
        "weight": 0
      }
    ],
    "version": "1.1"
  }
}

Programmatic safety check before consuming the verdict:

resp = httpx.post("https://swap.paladinfi.com/v1/trust-check/ofac",
                  json={"chainId": 8453, "address": addr}).json()
assert resp["_real"] is True              # not a fixture
assert resp["_scope"] == "ofac-only"      # not a different evaluation path
verdict = resp["trust"]["recommendation"] # "allow" or "block"

trust_check_preview

Identical schema, with _real: false, every factor real: false, recommendation prefixed sample-, and a _HUMAN_DO_NOT_USE_AS_REAL_VERDICT top-level banner.

Refresh cadence

The OFAC SDN list is fetched from https://www.treasury.gov/ofac/downloads/sdn.xml daily. The exact timestamp of the in-memory list is returned per-response in _ofac_list_updated_at, so callers can detect stale data without trusting a separate bookkeeping layer.

If the source feed is unreachable, the in-memory list is held over and _ofac_list_updated_at continues to reflect the last successful refresh. Stale lists do not auto-degrade to block — callers responsible for enforcing maximum-acceptable staleness check _ofac_list_updated_at themselves.

Logging and retention

The server records request timestamp, source IP (for rate-limit accounting only), and the queried address in standard nginx access logs. Logs are retained for 30 days for operational debugging and then rotated. No persistent association is built between caller identity and queried addresses beyond the rate-limit window. No analytics, no third-party tracking, no PII enrichment.

Rate-limit behavior

Requests exceeding 1 r/s + burst 3 receive HTTP 429. The rate-limit window is per-IP; there is no IP ban or escalating block — the next request after the window clears is served normally. The Retry-After header indicates when to retry.

Use of this endpoint is subject to the PaladinFi Terms.

Related packages

For evaluations that compose multiple signals (OFAC + GoPlus token security + Etherscan source verification + anomaly heuristics), PaladinFi offers other npm packages — see paladinfi.com/trust-check for details. Migration from this MCP to one of the multi-signal packages: install the chosen npm package alongside (or instead of) this MCP; tool names overlap so callers can migrate without rewriting call sites.

When to use this vs. an on-chain sanctions oracle

These are complementary surfaces: an off-chain HTTP screen for agent / web-UI display, and an on-chain modifier for the settlement contract.

Examples

• examples/python/check_address.py — direct REST call demonstrating the OFAC screen + preview shape inspection.
• examples/typescript/check_address.ts — same flow in TypeScript with fetch.

Documentation

• Hosted MCP endpoint: trust.paladinfi.com/mcp
• Live /health: trust.paladinfi.com/health
• Apex docs: paladinfi.com/trust-check/
• Sister MCP for swap routing: paladin-swap-mcp

Contact

• General: dev@paladinfi.com
• Security: see SECURITY.md

Legal

Operated by Malcontent Games LLC, doing business as PaladinFi. The hosted backend at swap.paladinfi.com and the MCP server at trust.paladinfi.com are proprietary; this repository covers the client-facing spec and examples under MIT.