Paladin Swap

io.github.paladinfiPublished by GitHub account paladinfiv0.1.0Updated Oct 25, 2026

Multi-aggregator swap router for AI agents on Base. 10 bps fee. MCP-native, non-custodial.

The publisher's own server: Trust Check Mcp

VerifiedStreamable HTTPWeb executableFinanceDeveloper Tools

Overview

AI-generated overview

A remote MCP server that gives an AI agent a swap quote with ready-to-execute calldata for token swaps on Base, plus a sample trust preview and a health check.

What you can do
Get a competitive swap quote across two upstream aggregators, returning router address, calldata, minimum buy amount and an injected 10 bps fee for the agent's wallet to sign and submit on Base (chain 8453). Inspect a sample-fixture token trust preview that always returns non-real markers and a sample-prefixed recommendation. Check service health, fee configuration, per-source counters and canary state.
When to use it
Useful when an agent needs to prepare on-chain ERC20 swaps on Base without writing aggregator, slippage or fee logic itself, and when the user's own wallet will sign and broadcast the transaction. Not a substitute for production trust screening, since the preview tool returns fixtures only.
Requirements
A remote Streamable-HTTP endpoint; no package install, API key or environment variable is declared. The client must support Streamable-HTTP transport. A wallet that can sign and submit transactions on Base is needed to actually execute a swap. Rate limits apply (10 r/s plus burst on the MCP endpoint, 5 concurrent connections per IP).
Before you install
The quote tool returns transaction calldata that the user's wallet must sign and broadcast; a 10 bps fee on the buy token is already embedded and goes to the operator's treasury. The trust preview is sample-fixture only and must not gate real swaps or signing. The paid trust-check endpoint costs $0.001 USDC per call via x402. The hosted backend is proprietary, and request logs retain the queried address and source IP.

Installation

In SourceWeft

  1. Open Paladin Swap in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.paladinfi%2Fpaladin-swap/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "paladin-swap": {
      "type": "http",
      "url": "https://swap.paladinfi.com/mcp"
    }
  }
}

README

paladin-swap-mcp

Open client and API spec for PaladinFi Swap — a competitive multi-aggregator swap router 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 at swap.paladinfi.com is proprietary.

Routing scope. PaladinFi Swap queries integrated upstream aggregators (currently 0x and Velora) in parallel and returns whichever delivers the higher post-fee buy amount. We do not represent any returned route as the best available, lowest-cost, or optimal across the broader DeFi market. Phrases like "best execution" are reserved-meaning terms in U.S. securities law and are deliberately not used here.

[Status] [Chain] [Backend] [Fee] [MCP] [CI] [License] [paladinfi/paladin-swap-mcp MCP server]

What is PaladinFi Swap?

A swap router built for AI agents that need to execute on-chain swaps. Your agent calls a single tool; the service returns ready-to-execute calldata your wallet signs and submits:

  • Router address to send the transaction to
  • Calldata with all routing pre-baked
  • Min buy amount (slippage protection enforced on-chain)
  • Affiliate fee already injected — no separate accounting on your side

Agents skip writing aggregator glue, slippage handling, and fee logic. One call, ready bytes.

The Service is non-custodial: PaladinFi never holds, signs, or moves user funds. Every transaction is signed and submitted by the user's own wallet (or their agent acting on their behalf).

Install (MCP)

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

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

Restart your client. Three tools become available:

  • swap_quote(sellToken, buyToken, sellAmount, taker, chainId?, slippageBps?) — competitive route across 0x and Velora (highest post-fee buy amount); returns ready-to-execute calldata.
  • trust_check_preview(address, chainId?) — sample-fixture preview of the trust gate. Returns _real: false, every factor is real: false, and the recommendation is prefixed sample- (e.g., sample-allow). Do not use the preview verdict to gate real swaps, signing, or any production agent decision. For production trust evaluation, POST to /v1/trust-check (paid, $0.001 USDC/call via x402) or use the npm plugins @paladinfi/eliza-plugin-trust / @paladinfi/agentkit-actions.
  • swap_health() — liveness, fee config, per-source counters, decimals-cache state, last Velora startup-canary verdict, selector-enforcement state.

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

MCP standards compliance

RequirementStatus
Tool title + annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint)✓ since v0.11.74; verify via the MCP tools/list method
Tool name ≤64 chars✓ longest is trust_check_preview (19 chars)
Streamable HTTP transport✓ at https://swap.paladinfi.com/mcp
Public OpenAPI 3.0 schema✓ at /openapi.yaml
Documented rate limits✓ at paladinfi.com/swap (5 r/s + burst 30 on /v1/quote; 10 r/s + burst 30 on /mcp; 5 concurrent connections per IP)
x402 paid-tool challenge✓ on the /v1/trust-check paid endpoint. The MCP trust_check_preview tool is gated to sample-fixture output with explicit misuse banners (_real: false, _HUMAN_DO_NOT_USE_AS_REAL_VERDICT, sample- recommendation prefix) — preview by design, never a real verdict
Tool descriptions narrow + accurate✓ see mcp-tools.json for exact schemas
Browser-origin clients (CORS)✓ since v0.11.75 on /v1/quote; allowlist is paladinfi.com + www.paladinfi.com only — other origins blocked at preflight
Free real-data on-ramp endpoint✓ since v0.11.77 — POST /v1/trust-check/ofac runs the OFAC SDN wallet-screen leg only (anonymous, 1 r/s rate-limit + burst 3, daily Treasury XML refresh). Response includes _paid_endpoint_info upgrade hint to the full multi-source composition at /v1/trust-check. Wallet-OFAC scope (token-contract sanctions list planned for future versions).
MCP Registry listing✓ this package is listed as io.github.paladinfi/paladin-swap. The §4.A-clean trust-check-only variant (no payment surface, no calldata, no transaction execution) ships separately as com.paladinfi/trust-check-mcp — Streamable HTTP at trust.paladinfi.com/mcp. Use the trust-check variant when payment-surface adjacency would be a deployment blocker.

Per MCP ToolAnnotations:

  • swap_quote — title "Get Swap Quote"; readOnlyHint: true (returns calldata, never mutates server state), openWorldHint: true (calls upstream aggregators 0x AllowanceHolder + Velora Augustus v6.2 on Base)
  • trust_check_preview — title "Token Trust Check (Preview)"; readOnlyHint: true, idempotentHint: true (deterministic sample fixture per address), openWorldHint: true (paid-mode upstream factor sources cross the process boundary; defensive contract-violation handlers exist for shape drift)
  • swap_health — title "Swap Service Health"; readOnlyHint: true, openWorldHint: false (introspection of our own service state only)

Agent usage walkthrough

A representative call chain when an MCP-aware agent (e.g., Claude Code) handles a swap intent. Specific tool-call formatting varies by client; the key point is that the swap router returns ready-to-execute calldata so the agent never composes routing logic itself.

User: "Swap 100 USDC for WETH on Base."

1. Optional pre-trade trust check (free, sample-fixture only). Before composing the swap, the agent may call trust_check_preview to inspect the buy-token contract's risk shape.

json
// Tool call{  "tool": "trust_check_preview",  "arguments": {    "address": "0x4200000000000000000000000000000000000006",    "chainId": 8453  }}
json
// Response (truncated){  "_real": false,  "_HUMAN_DO_NOT_USE_AS_REAL_VERDICT": "Preview-only fixture. See README.",  "trust": {    "recommendation": "sample-allow",    "_preview": true,    "factors": [      { "real": false, "source": "ofac",      "signal": "clear" },      { "real": false, "source": "goplus",    "signal": "clear" },      { "real": false, "source": "etherscan", "signal": "verified-contract" }    ]  }}

The preview is sample-fixture only — agents must check _real === true before consuming a verdict. For production gating, call /v1/trust-check (paid, $0.001 USDC/call via x402) or use the npm plugins @paladinfi/eliza-plugin-trust / @paladinfi/agentkit-actions.

2. Competitive quote with calldata. The agent calls swap_quote to get the route + ready-to-execute transaction.

json
// Tool call{  "tool": "swap_quote",  "arguments": {    "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",    "buyToken":  "0x4200000000000000000000000000000000000006",    "sellAmount": "100000000",    "taker":      "0xUserAgentWallet",    "chainId":    8453,    "slippageBps": 50  }}
json
// Response (illustrative; values depend on live pool state){  "source":           "velora",  "chainId":          8453,  "router":           "0x6a000f20005980200259b80c5102003040001068",  "calldata":         "0xe3ead59e000000000000000000000000...",  "buyAmount":        "43200000000000000",  "minBuyAmount":     "42984000000000000",  "sellAmount":       "100000000",  "gas":              "318707",  "ourFeeBps":        10,  "ourFeeRecipient":  "0xeA8C33d018760D034384e92D1B2a7cf0338834b4"}

source indicates whichever upstream aggregator (0x or Velora) delivered the higher post-fee buy amount for this pair. The 10 bps fee is already injected into the calldata; the buyAmount you see is the user's net (post-fee, pre-slippage). minBuyAmount reflects the requested 50 bps slippage tolerance.

3. Sign + submit. The agent surfaces the transaction shape to the user's wallet for signing — to=router, data=calldata, value=0 (for ERC20 → ERC20). PaladinFi never sees the signature; the wallet broadcasts the transaction directly to Base.

4. Confirm. Slippage is enforced on-chain: the swap reverts if the actual fill would deliver less than minBuyAmount. The agent reports the transaction hash; the user's wallet shows the settled buy amount on Base. The 10 bps fee transfers to the published treasury address (/health) atomically as part of the same transaction — no second on-chain step.

Non-custodial end-to-end. At no point does PaladinFi hold, sign, or move funds. The MCP server returns metadata; the wallet executes. A compromised swap router could only return calldata; even malicious calldata is bounded by the v0.11.71 outer-router + selector + 0x Settler-target allowlist (see Roadmap below) and the user's own wallet-side approval limits.

Install (REST)

No MCP needed — hit the endpoint directly:

bash
curl -sS https://swap.paladinfi.com/v1/quote \  -H 'content-type: application/json' \  -d '{    "chainId": 8453,    "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",    "buyToken":  "0x4200000000000000000000000000000000000006",    "sellAmount": "5000000",    "taker": "0xYOUR_AGENT_WALLET"  }'

Full REST spec in openapi.yaml.

For free OFAC SDN wallet screening (no MCP, no key, no signup), see the drop-in cURL + React hook walkthrough at paladinfi.com/docs/screen-wallets/ — POST /v1/trust-check/ofac returns an allow or block verdict, anonymous, rate-limited at 1 r/s + burst 3.

Endpoints

MethodPathPurposePricing
GET/healthLiveness, fee config, per-source counters, decimals-cache state, last Velora canary verdict, selector-enforcement stateFree
POST/v1/quoteCompetitive route quote with calldata — highest post-fee buy amount across 0x and VeloraFree
POST/v1/trust-checkLive token-contract trust evaluation (OFAC SDN, GoPlus, Etherscan, anomaly heuristics)$0.001 USDC/call via x402
POST/v1/trust-check/previewSample-fixture preview of the trust-check response shape (no live data sources evaluated)Free
POST/mcpMCP Streamable-HTTP transport (3 tools — see mcp-tools.json)Free

Response shape (abridged)

json
{  "source": "velora",  "chainId": 8453,  "router": "0x6a000f20005980200259b80c5102003040001068",  "calldata": "0x...",  "buyAmount": "2160000000000000",  "minBuyAmount": "2138000000000000",  "sellAmount": "5000000",  "gas": "318707",  "ourFeeBps": 10,  "ourFeeRecipient": "0xeA8C33d018760D034384e92D1B2a7cf0338834b4",  "estimatedOurFeeAmount": "2160000000000",  "estimatedOurFeeToken": "0x4200000000000000000000000000000000000006"}

source is the upstream aggregator that won this quote ("0x" or "velora"). Submit the transaction as to=router, data=calldata, value=0 (for ERC20→ERC20) from taker.

Examples

Fees

A flat 10 basis points (0.1%) is taken on the buy token. The fee is calculated against the actual fill amount, not the quoted estimate, so you never pay more than expected even if the pool moves between quote and fill. PaladinFi's 10 bps is taken from the buy-token side via the upstream aggregator's integrator-fee mechanism (0x's swapFeeBps / Velora's partnerFeeBps), so the buyAmount you see in the response already reflects both any upstream protocol fee and our 10 bps — no additional deduction at fill time.

Fees route directly to the PaladinFi treasury — no on-chain receipt step on your side. The fee recipient address is published in /health so it's auditable on-chain. The /v1/quote endpoint stays free to query, with no per-call charges or spread on top. (/v1/trust-check is the only paid endpoint, at $0.001 USDC/call via x402.)

Supported assets

  • Chain: Base (8453). Ethereum mainnet, Arbitrum, Optimism, BNB are on the roadmap.
  • Tokens: Any ERC20 supported by either 0x or Velora on Base. Coverage is the union of both aggregators — canonical pairs (USDC, WETH, cbBTC, USDT, DAI, AERO) are routable on both; long-tail tokens often route on only one of the two.

Trust Check data sources

The paid /v1/trust-check endpoint evaluates a token contract against a defined set of public data sources and returns a single recommendation: "allow" | "warn" | "block" verdict alongside per-source breakdown. Sources currently consulted, with verifiability pointers:

SourceWhat it screensVerifiability
OFAC SDN list (U.S. Department of the Treasury)Sanctioned addresses (the contract itself, deployer, and known associated wallets)List refreshed daily on the hosted backend from the Treasury Sanctions List Service feed at https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML. The address dataset extracted is the union of Feature[@FeatureTypeID="345"]/FeatureVersion/VersionDetail[@DetailTypeID="1432"] entries (FeatureTypeID 345 = ETH/EVM addresses; DetailTypeID 1432 = Digital Currency Address Detail). Loaded count as of last verification: 87 ETH addresses (2026-04-30). The underlying Treasury feed is publicly downloadable so any client can independently re-derive the dataset and verify a positive match.
GoPlus Token Security APIHoneypot patterns, mint authority, ownership renouncement, transfer pause, blacklist function, anti-whale, hidden owners, slippage modifiersQueried per-call via https://api.gopluslabs.io/api/v1/token_security/8453?contract_addresses=<address>. We normalize the GoPlus response into the factors array we surface; the full GoPlus response is publicly queryable so buyers can independently audit any signal.
Etherscan / BaseScan source verification (via the unified Etherscan v2 API)Verified-source presence and proxy-pattern detection (via Proxy / Implementation fields in the getSourceCode response)Queried per-call via https://api.etherscan.io/v2/api?chainid=8453&module=contract&action=getsourcecode&address=<address>. Public source code (when verified) is independently inspectable on basescan.org.
Anomaly heuristics (PaladinFi-internal)Contract age windows (under 1h / 24h / 7d), address-kind classification (contract vs. EOA via eth_getCode), and no-outbound transaction history (nonce=0 check)Heuristic logic runs in the hosted backend module address_anomaly.py; each emitted signal (contract_age_under_*, address_kind_*, no_outbound_history) is surfaced in the response so a buyer can reproduce or override the conclusion via direct RPC calls.

Preview vs paid distinction. /v1/trust-check/preview (free) returns a static fixture with _real: false markers — none of the live data sources above are queried. /v1/trust-check (paid, $0.001 USDC via x402) consults all four. The preview exists so integrators can validate request shape and inspect the response schema without paying; agents must check the top-level _real field is true before consuming a verdict.

Request logging. Per call, PaladinFi retains a request log entry containing timestamp, the queried address, source IP, and billing/rate-limit reference. This is used for revenue accounting, rate-limit enforcement, and abuse detection — not for analytics or resale. PaladinFi does not maintain a separate database of evaluated tokens or buyer query history.

Roadmap

  • 0x Settler routing on Base
  • Highest-of-two routing across 0x and Velora on Base (v0.11.66+, 2026-05-04)
  • MCP Streamable-HTTP transport with swap_quote, swap_health, and trust_check_preview tools
  • /v1/trust-check paid endpoint via x402 ($0.001 USDC/call)
  • Per-source 4-byte calldata selector + Settler-target allowlist (v0.11.71 — defense in depth against router-substitution / dispatcher-hijack attacks)
  • Ethereum mainnet, Arbitrum, BNB, Optimism — planned
  • Permit2-native flow (skip the approve tx) — planned

Status

Production. The endpoint is live, monitored, and verified end-to-end with on-chain test transactions on Base. See /health for current fee config, version, and per-source counters.

What's in this repository

File / folderPurpose
README.mdThis file
LICENSEMIT — covers everything in this repo
SECURITY.mdVulnerability disclosure path + scope
openapi.yamlOpenAPI 3.0 spec for the public REST API
mcp-tools.jsonMCP tool schemas
examples/Working code examples (Python, TypeScript)
.github/workflows/ci.ymlCI: YAML/JSON syntax + OpenAPI 3.0 schema validation on push/PR

Not in this repository: the hosted backend (proprietary). This repo is the public client surface — install instructions, schemas, and integration code samples.

Contact

Legal

Operated by Malcontent Games LLC, doing business as PaladinFi, a Michigan limited liability company. The Service routes quotes through third-party aggregators (currently 0x and Velora). You retain custody — your agent signs every transaction. PaladinFi never holds user funds.

Use of the hosted Service is subject to the PaladinFi Terms of Service and Privacy Policy.

License

The contents of this repository are released under the MIT License. The hosted backend is proprietary and not covered.

Source: README.md at commit a19d62b

Tools

0
SourceWeft has not read this server's tools yet.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declaredRequired10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Paladinfi integrations

Trust Check Mcp

com.paladinfiOfficial publisher

A free, anonymous remote MCP server that lets an assistant screen a wallet address against the US Treasury OFAC SDN list and get an allow or block verdict.

Streamable HTTPWeb executable
FinanceNot indexed yetOct 24, 2026