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 (inside the trust block); callers can verify staleness without trusting our bookkeeping.
• Signed responses. Every /ofac response carries an Ed25519 signature (_signature, _signature_alg, _signature_pubkey_hex) over the canonical JSON body, so a consumer can verify origin integrity.
• 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. The trust block carries _preview: true, 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.

chainId note: the OFAC SDN screen is wallet-address-level and chain-agnostic — the same 0x address is listed (or not) regardless of network. chainId is accepted for consistency with the full /v1/trust-check endpoint; it does not scope the OFAC match.

Coverage and limits

Response shape

trust_check_ofac_free

The freshness + scope markers live inside the trust block. The top level also carries an Ed25519 signature and a pointer to the paid full-composition endpoint.

{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chainId": 8453,
  "trust": {
    "recommendation": "allow",
    "factors": [
      { "source": "ofac", "signal": "not_listed", "weight": 0, "details": "", "real": true }
    ],
    "version": "1.1",
    "_real": true,
    "_scope": "ofac-only (wallet-address screen; use /v1/trust-check for full composition: GoPlus + Etherscan + anomaly heuristics)",
    "_ofac_list_updated_at": "2026-05-31T04:08:06Z",
    "_ofac_sdn_count": 93
  },
  "_signature": "<base64 Ed25519>",
  "_signature_alg": "ed25519",
  "_signature_pubkey_hex": "272b6b62230d9da810f3ed64b5e5147f1ae062cb46ad7f25044b0aab1d18fb6f"
}

A sanctioned address returns the same shape with trust.recommendation: "block" and a factor { "source": "ofac", "signal": "sdn_listed" }.

Programmatic safety check before consuming the verdict:

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

trust_check_preview

A SAMPLE FIXTURE — not a live evaluation. Same envelope (address, chainId, trust, plus top-level request_id and _mcp_paid_endpoint_info), but inside trust: _preview: true, recommendation is prefixed sample- (e.g. "sample-allow"), risk_score is null, every factor is real: false, and trust._message carries a do-not-use-as-real-verdict banner. There is no _real field on preview — the _preview: true marker and the sample- prefix are how you tell a fixture from a real screen.

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 trust._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

Zero-dependency, copy-paste runnable. Each defaults to screening one clean address and one genuinely OFAC-listed address, so you see both an allow and a block on first run. Pass your own addresses as arguments. Exit code: 0 all clean, 1 any address listed, 2 request error — drops straight into CI or a pre-send gate.

• examples/python/check_address.py — Python 3 (standard library only; no pip install). Run: python check_address.py.
• examples/typescript/check_address.ts — TypeScript with built-in fetch. Run: npx tsx check_address.ts.

For a browser/React integration of the same endpoint, see the tutorial at paladinfi.com/docs/screen-wallets/.

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.