What changed on the PaladinFi homepage — and why

2026-05-12 · Engineering / Brand homepage operational-posture

The PaladinFi homepage was rewritten on 2026-05-07 alongside the v0.11.73 server release. The rewrite isn't cosmetic: it tightened the framing around who the service is for, surfaced concrete JSON examples in both product cards, and added an "operational posture" section that names refresh cadence, failure-mode contract, rate limits, and custody model in writing.

This post walks through what changed section-by-section and the reasoning behind each call. If you're evaluating PaladinFi for an agent runtime — ElizaOS, Coinbase AgentKit, a custom one — the operational posture section is the part to read first. That's where the commitments live.

The new opening: failure modes named, audience named

The pre-rewrite lede led with the service capabilities; the rewrite leads with what fails without them. From the homepage:

Two failure modes routinely cost AI agents real money on Base. The first is signing into a honeypot or sanctioned token contract — an output you can't exit, an address you shouldn't touch. The second is routing through one aggregator without comparing — leaving buy-amount on the table because the cheapest route on this minute's liquidity isn't the one you hit.

Two design decisions in that paragraph:

Name the audience. The lede ends "Built for ElizaOS plugin authors, Coinbase AgentKit integrators, and custom agent operators on Base." This isn't broad. PaladinFi doesn't serve passive yield-chasers, retail swappers, or institutional desks.

Lead with what breaks, not what we ship. "Signing into a honeypot" and "routing through one aggregator without comparing" are concrete, specific, agent-flavored failure modes — common enough in production agent operation on Base that the homepage names them by surface instead of leaving the audience to extract them from a feature list. The lede points at those breakages, then says PaladinFi addresses both — instead of opening with "the best swap router on Base" or similar.

JSON in both product cards

Both product cards on the rewritten homepage show actual response shapes.

The Swap card shows a /v1/quote response with buyAmount, minBuyAmount, source, router, calldata, and an embedded trust block:

"trust": { "recommendation": "allow", "version": "1.1", … }

The embedded trust block is doing real work for agents that want a one-call interaction: hit /v1/quote, branch on quote.trust.recommendation, no second call needed for routine cases. The shape exists because v0.11.73 made it production-stable — per-source failures flag clearly, all-source failure forces warn.

The Trust Check card shows the standalone /v1/trust-check response with the full factors[] array enumerating ofac, paladin.anomaly, etherscan_source, and goplus signals — alongside risk_score, recommendation, and the contract version field.

Why JSON on a homepage at all? Two reasons. First, agents read the homepage too, and screenshots don't introspect. Second, JSON is hard to hedge. If the homepage shows the shape, the team is committing to the shape. Field-name drift was an early HIGH catch in the rewrite review: the draft had to / data but production returns router / calldata. The shape on the page now matches production byte-for-byte.

Operational posture, in writing

The new "Operational posture" section is four rows. Each one names something that DeFi infrastructure typically leaves unstated.

Refresh cadence

The OFAC SDN list is pulled daily from the U.S. Treasury XML feed via systemd timer. The homepage explicitly notes that "operationally may skip during outages" — for sub-daily / audit-grade compliance, callers should query Treasury directly. The other three trust-check sources (GoPlus, Etherscan, internal anomaly heuristics) evaluate per-request with a short cache; they don't have a refresh cadence in the same sense — they're hit live on each call.

The "OFAC daily target" framing on the homepage tells the truth: we run a daily timer, the daily target may miss, and for hard guarantees the source is upstream. The original "OFAC refreshed daily" draft was caught by the review as carrying a stronger implication than the implementation enforces.

Failure mode — fail-closed, never silent-allow

If a single source is unreachable, the response includes a flagged factor with signal: "unreachable", real: false, and the verdict is derived from the remaining sources. If all sources are unreachable, the verdict is forced to warn. OFAC SDN hit forces block as the highest-priority override. This is the v0.11.73 contract — there's a dedicated post on what changed and why.

The homepage section pointing at the failure-mode contract is load-bearing for a specific reason: a trust gate that silently returns allow when it couldn't actually run isn't a gate. Stating "fail-closed, never silent-allow" on the homepage commits PaladinFi to it. If a regression ever ships that returns allow on an unreachable source, this homepage line is the receipt.

What happens on the swap side when upstreams fail

The homepage's fail-closed contract is stated for the trust gate. The symmetric question for Swap: what does an agent see when both 0x and Velora are unreachable? /v1/quote returns HTTP 502 with a JSON error body — never a degraded route, never a fallback to a single source returning silently. If only one source is down, the response carries whichever route remains and the source field reflects it. Agents should treat HTTP 502 as do-not-trade-now and retry the quote rather than synthesizing one.

Rate limits

Free tier: 2 r/s per IP, burst 10. Paid tier: 10 r/s per IP, burst 30. Excess returns HTTP 429 with Retry-After. The free preview endpoint (/v1/trust-check/preview) caps at 5 concurrent connections per IP. These numbers match nginx config in production. The rewrite review caught a pre-edit draft that had free-tier burst at 30 (3× the actual), which would have been a wrong-direction overpromise.

Custody — PaladinFi never holds funds or keys

Endpoints return calldata and verdicts; the agent signs the transaction with its wallet and submits it. The 10 bps fee on Swap is integrated via the upstream aggregator's partner-fee mechanism — collected from the buy token at settlement, not by a separate transfer. This row exists because the absence of custody is asymmetric information: most DeFi services have it, few say it explicitly, and a B2B buyer evaluating PaladinFi needs the explicit answer to one question — "are you the agent's counterparty for the swap?" The answer is no, and saying so explicitly is faster than letting them infer.

What's intentionally not on the homepage

A few things the rewrite deliberately left off:

No SLA promise. /health is linked from the footer as the live receipt; we publish the endpoint instead of a number we can't enforce.
No team page. The signal of record is the engineering work itself — the GitHub org, the changelog cadence, the live /health endpoint. Buyers who need named founders can ask via dev@paladinfi.com; we don't put a roster on the homepage as a substitute for ship history.
No comparative claims. No "vs 1inch" or "vs ParaSwap." The "PaladinFi does not represent any returned route as the best available across the broader DeFi market" disclaimer in the Swap product card is explicit about scope: post-fee compare across two aggregators end-to-end, not the entire DeFi market.

The homepage is built to be falsifiable. If /health returns 503, the homepage's implicit claims have receipts. If a trust-check response misses signal: "unreachable" on a flagged factor, the fail-closed claim has receipts. If the rate-limit numbers are wrong, anyone with twenty seconds and a shell loop can check.

Verify any claim above

Live ground truth, not this post:

swap.paladinfi.com/health — health endpoint with version, source counters, selector enforcement state.
github.com/paladinfi/paladin-swap-mcp — open client + API spec; MIT-licensed. CHANGELOG.md for the public-API-affecting change log.
/swap/ and /trust-check/ — product docs with curl-able examples and full integration paths.

The 2026-05-12 ship (v0.11.74) added tool annotations to the MCP server and bumped the preview-endpoint trust-block version to 1.1 to match the v0.11.73 paid-endpoint contract — full notes in the CHANGELOG. The /health endpoint, the GitHub org, and the swap/trust-check product pages are the surfaces that should agree with this post. If any of them drift, the post is wrong, not them.