paladin-swap-mcp

Offene Client- und API-Spezifikation für PaladinFi Swap — ein wettbewerbsfähiger Multi-Aggregator-Swap-Router für KI-Agenten auf Base. Dieses Repository enthält die öffentliche REST- und MCP-API-Spezifikation, funktionierende Code-Beispiele und Thin-Client-Wrapper. Das gehostete Backend unter swap.paladinfi.com ist proprietär.

Routing-Umfang. PaladinFi Swap fragt eine begrenzte Anzahl integrierter Upstream-Aggregatoren (derzeit 0x und Velora; 1inch und Odos sind geplant) parallel ab und gibt denjenigen zurück, der den höheren Kaufbetrag nach Gebühren liefert. Wir stellen keine zurückgegebene Route als die beste verfügbare, kostengünstigste oder optimale Lösung auf dem breiteren DeFi-Markt dar. Begriffe wie "best execution" sind im US-Wertpapierrecht reservierte Fachbegriffe und werden hier bewusst nicht verwendet.

Was ist PaladinFi Swap?

Ein Swap-Router, der für KI-Agenten entwickelt wurde, die On-Chain-Swaps ausführen müssen. Ihr Agent ruft ein einzelnes Tool auf; der Dienst gibt ausführungsbereite Calldata zurück, die Ihr Wallet signiert und übermittelt:

• Router-Adresse, an die die Transaktion gesendet werden soll

• Calldata mit allen vorab erstellten Routing-Informationen

• Minimaler Kaufbetrag (Slippage-Schutz, der On-Chain durchgesetzt wird)

• Affiliate-Gebühr bereits integriert — keine separate Buchhaltung auf Ihrer Seite

Agenten müssen sich nicht um Aggregator-Glue, Slippage-Handling und Gebührenlogik kümmern. Ein Aufruf, fertige Bytes.

Der Dienst ist non-custodial: PaladinFi hält, signiert oder bewegt niemals Benutzergelder. Jede Transaktion wird vom eigenen Wallet des Benutzers (oder dessen Agenten, der in seinem Namen handelt) signiert und übermittelt.

Installation (MCP)

Für Claude Code oder jeden MCP-kompatiblen Client, der Streamable-HTTP-Transport unterstützt:

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

Starten Sie Ihren Client neu. Drei Tools stehen zur Verfügung:

• swap_quote(sellToken, buyToken, sellAmount, taker, chainId?, slippageBps?) — Best-of-N-Angebot über 0x + Velora; gibt ausführungsbereite Calldata zurück.

• trust_check_preview(address, chainId?) — Beispiel-Vorschau der Vertrauensbewertung von Token-Verträgen. Kostenlos / nicht bezahlt; gibt _real: false zurück, um sie klar als Vorschau zu kennzeichnen. Echte Bewertungen sind über @paladinfi/eliza-plugin-trust oder @paladinfi/agentkit-actions verfügbar (bezahlt via x402, $0,001/Aufruf).

• swap_health() — Liveness + Zähler pro Quelle für den Routing-Dienst.

Siehe mcp-tools.json für die vollständigen Tool-Schemata.

Installation (REST)

Kein MCP erforderlich — rufen Sie den Endpunkt direkt auf:

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"
  }'

Vollständige REST-Spezifikation in openapi.yaml.

Endpunkte

Antwortformat (gekürzt)

{
  "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 ist der Upstream-Aggregator, der dieses Angebot gewonnen hat ("0x" oder "velora"). Übermitteln Sie die Transaktion als to=router, data=calldata, value=0 (für ERC20→ERC20) vom taker.

Beispiele

• examples/python/quote_and_swap.py — Python mit web3.py

• examples/typescript/quote_and_swap.ts — TypeScript mit viem

Gebühren

Eine pauschale Gebühr von 10 Basispunkten (0,1 %) wird auf den Kauf-Token erhoben. Die Gebühr wird auf Basis des tatsächlichen Ausführungsbetrags berechnet, nicht auf Basis der geschätzten Quote, sodass Sie nie mehr als erwartet zahlen, selbst wenn sich der Pool zwischen Angebot und Ausführung bewegt.

Die Gebühren fließen direkt an die PaladinFi-Treasury — kein On-Chain-Empfangsschritt auf Ihrer Seite erforderlich. Die Adresse des Gebührenempfängers wird unter /health veröffentlicht, sodass sie On-Chain überprüfbar ist. Der Dienst bleibt kostenlos abfragbar, ohne Gebühren pro Aufruf oder zusätzliche Spreads.

Unterstützte Assets

• Chain: Base (8453). Ethereum Mainnet, Arbitrum, Optimism, BNB stehen auf der Roadmap.

• Tokens: Jeder ERC20, der entweder von 0x oder Velora auf Base unterstützt wird. Die Abdeckung ist die Vereinigung beider Aggregatoren — kanonische Paare (USDC, WETH, cbBTC, USDT, DAI, AERO) sind auf beiden routbar; Long-Tail-Token werden oft nur über einen der beiden geroutet.

Roadmap

• [x] 0x Settler Routing auf Base

• [x] Best-of-N-Routing über 0x und Velora auf Base (v0.11.66+, 04.05.2026)

• [x] MCP Streamable-HTTP-Transport

• [x] trust_check_preview MCP-Tool (v0.11.65)

• [ ] 1inch + Odos als zusätzliche Routing-Quellen — geplant

• [ ] Ethereum Mainnet, Arbitrum, BNB, Optimism — geplant

• [ ] Permit2-nativer Ablauf (Überspringen der Approve-Transaktion) — geplant

Status

Produktion. Der Endpunkt ist live, überwacht und durch On-Chain-Testtransaktionen auf Base durchgängig verifiziert. Siehe /health für die aktuelle Gebührenkonfiguration, Version und Zähler pro Quelle.

Was ist in diesem Repository enthalten

Nicht in diesem Repository enthalten: das gehostete Backend (proprietär). Dieses Repo ist die öffentliche Client-Oberfläche — Installationsanweisungen, Schemata und Integrationscode-Beispiele.

Kontakt

• E-Mail: dev@paladinfi.com

• Marketing: paladinfi.com

• API: swap.paladinfi.com/health

• Landingpage: paladinfi.com/swap/

Rechtliches

Betrieben von Malcontent Games LLC, handelnd als PaladinFi, einer Gesellschaft mit beschränkter Haftung nach dem Recht von Michigan. Der Dienst leitet Angebote über Drittanbieter-Aggregatoren (derzeit 0x und Velora). Sie behalten die Verwahrung — Ihr Agent signiert jede Transaktion. PaladinFi hält niemals Benutzergelder.

Die Nutzung des gehosteten Dienstes unterliegt den PaladinFi Nutzungsbedingungen und der Datenschutzrichtlinie.

Lizenz

Die Inhalte dieses Repositorys werden unter der MIT-Lizenz veröffentlicht. Das gehostete Backend ist proprietär und nicht abgedeckt.