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.

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:

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

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.

// Tool call
{
  "tool": "trust_check_preview",
  "arguments": {
    "address": "0x4200000000000000000000000000000000000006",
    "chainId": 8453
  }
}

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

// Tool call
{
  "tool": "swap_quote",
  "arguments": {
    "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "buyToken":  "0x4200000000000000000000000000000000000006",
    "sellAmount": "100000000",
    "taker":      "0xUserAgentWallet",
    "chainId":    8453,
    "slippageBps": 50
  }
}

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