# trust-check-mcp

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/paladinfi/trust-check-mcp  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/trust-check-mcp

## Description
Free OFAC SDN wallet screen + sample preview for AI agents on Base. Read-only, no payment surface.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "trust-check-mcp": {
    "command": "npx",
    "args": ["-y","trust-check-mcp"]
  }
}
```

## Documentation & README

# trust-check-mcp

**Open client and API spec for [PaladinFi Trust Check](https://paladinfi.com/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.

[![Status](https://img.shields.io/badge/status-live-3fb950)](https://trust.paladinfi.com/health)
[![Chain](https://img.shields.io/badge/chain-Base%208453-2563eb)](https://basescan.org/)
[![Source](https://img.shields.io/badge/source-US%20Treasury%20OFAC%20SDN-555)](https://www.treasury.gov/ofac/downloads/sdn.xml)
[![Refresh](https://img.shields.io/badge/refresh-daily-7c3aed)](#refresh-cadence)
[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-7c3aed)](https://modelcontextprotocol.io)
[![Registry](https://img.shields.io/badge/MCP%20Registry-com.paladinfi%2Ftrust--check--mcp-7c3aed)](https://registry.modelcontextprotocol.io/v0/servers?search=paladinfi)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 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](https://claude.com/claude-code) or any MCP-compatible client supporting Streamable-HTTP transport:

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

Verify the host is up before adding:

```bash
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`](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:

```bash
# 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`](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

| Dimension | Value |
|---|---|
| Chain | Base mainnet (chainId 8453) |
| Source | US Treasury OFAC SDN XML feed |
| Jurisdiction | US OFAC SDN only. No EU, UN, UK, or other sanctions regimes; callers in non-US jurisdictions are responsible for screening against locally-applicable lists. |
| Refresh cadence | Daily from the Treasury XML feed |
| List size | ~93 wallet/EOA addresses (see live `_ofac_sdn_count`) |
| Rate limit | 1 req/sec + burst 3 + 3 concurrent per IP |
| Auth | Anonymous (no API key, no signup) |
| Cost | Free |

## 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.

```json
{
  "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:

```python
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](https://paladinfi.com/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](https://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

| | On-chain oracle | `trust_check_ofac_free` |
|---|---|---|
| Access | Solidity call on a settlement contract | HTTP POST (anonymous) |
| Best for | In-contract gate logic (modifiers) | Off-chain agents, bots, web apps, MCP clients |
| Response | Bare `bool` | Structured JSON with freshness metadata |
| Cost | Gas per call | Free + rate-limited |
| Coverage | Often multi-jurisdiction | US OFAC SDN only |

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`](examples/python/check_address.py) — Python 3 (standard library only; no `pip install`). Run: `python check_address.py`.
- [`examples/typescript/check_address.ts`](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/](https://paladinfi.com/docs/screen-wallets/).

## Documentation

- Hosted MCP endpoint: [trust.paladinfi.com/mcp](https://trust.paladinfi.com/mcp)
- Live `/health`: [trust.paladinfi.com/health](https://trust.paladinfi.com/health)
- Apex docs: [paladinfi.com/trust-check/](https://paladinfi.com/trust-check/)
- Sister MCP for swap routing: [paladin-swap-mcp](https://github.com/paladinfi/paladin-swap-mcp)

## Contact

- General: [dev@paladinfi.com](mailto:dev@paladinfi.com)
- Security: see [SECURITY.md](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](LICENSE).