paladin-swap-mcp

PaladinFi Swap을 위한 오픈 클라이언트 및 API 사양 — Base 기반 AI 에이전트를 위한 경쟁력 있는 다중 애그리게이터 스왑 라우터입니다. 이 저장소에는 공개 REST 및 MCP API 사양, 작동하는 코드 예제, 그리고 씬 클라이언트 래퍼가 포함되어 있습니다. swap.paladinfi.com에서 호스팅되는 백엔드는 독점 기술입니다.

라우팅 범위. PaladinFi Swap은 통합된 업스트림 애그리게이터(현재 0x 및 Velora; 1inch 및 Odos 계획 중)의 제한된 세트를 병렬로 쿼리하여 수수료 차감 후 더 높은 구매 금액을 제공하는 경로를 반환합니다. 당사는 반환된 경로가 더 넓은 DeFi 시장에서 이용 가능한 최상의 경로, 최저 비용 또는 최적의 경로라고 보장하지 않습니다. "최상의 실행(best execution)"과 같은 문구는 미국 증권법에서 예약된 의미를 가지며, 여기서는 의도적으로 사용하지 않습니다.

PaladinFi Swap이란 무엇인가요?

온체인 스왑을 실행해야 하는 AI 에이전트를 위해 구축된 스왑 라우터입니다. 에이전트가 단일 도구를 호출하면, 서비스는 지갑이 서명하고 제출할 수 있는 실행 준비된 calldata를 반환합니다:

• 트랜잭션을 보낼 라우터 주소

• 모든 라우팅이 사전 설정된 Calldata

• 최소 구매 금액 (온체인에서 슬리피지 보호 적용)

• 제휴 수수료가 이미 포함됨 — 별도의 회계 처리가 필요 없음

에이전트는 애그리게이터 연동, 슬리피지 처리, 수수료 로직을 직접 작성할 필요가 없습니다. 한 번의 호출로 즉시 사용 가능한 바이트를 얻을 수 있습니다.

이 서비스는 **비수탁형(non-custodial)**입니다: PaladinFi는 사용자의 자금을 보유, 서명 또는 이동하지 않습니다. 모든 트랜잭션은 사용자의 지갑(또는 사용자를 대신하는 에이전트)에 의해 직접 서명되고 제출됩니다.

설치 (MCP)

Claude Code 또는 Streamable-HTTP 전송을 지원하는 MCP 호환 클라이언트의 경우:

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

클라이언트를 재시작하세요. 세 가지 도구를 사용할 수 있게 됩니다:

• swap_quote(sellToken, buyToken, sellAmount, taker, chainId?, slippageBps?) — 0x + Velora 전반의 최적(best-of-N) 견적; 실행 준비된 calldata를 반환합니다.

• trust_check_preview(address, chainId?) — 토큰 계약 신뢰도 평가의 샘플 프리뷰입니다. 무료/비유료; 프리뷰임을 명확히 하기 위해 _real: false를 반환합니다. 실제 평가는 @paladinfi/eliza-plugin-trust 또는 @paladinfi/agentkit-actions를 통해 이용 가능합니다 (x402를 통해 유료, 호출당 $0.001).

• swap_health() — 라우팅 서비스의 활성 상태 및 소스별 카운터.

전체 도구 스키마는 mcp-tools.json을 참조하세요.

설치 (REST)

MCP가 필요하지 않은 경우 엔드포인트를 직접 호출하세요:

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

전체 REST 사양은 openapi.yaml에 있습니다.

엔드포인트

응답 형태 (요약)

{
  "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는 이 견적을 낙찰받은 업스트림 애그리게이터("0x" 또는 "velora")입니다. taker로부터 to=router, data=calldata, value=0 (ERC20→ERC20의 경우)으로 트랜잭션을 제출하세요.

예제

• examples/python/quote_and_swap.py — web3.py를 사용한 Python 예제

• examples/typescript/quote_and_swap.ts — viem을 사용한 TypeScript 예제

수수료

구매 토큰에 대해 **10 베이시스 포인트(0.1%)**의 고정 수수료가 부과됩니다. 수수료는 견적 추정치가 아닌 실제 체결 금액을 기준으로 계산되므로, 견적과 체결 사이에 풀이 변동되더라도 예상보다 더 많은 비용을 지불하지 않습니다.

수수료는 PaladinFi 재무부로 직접 전달되며, 사용자가 별도로 온체인 영수증을 처리할 필요가 없습니다. 수수료 수취인 주소는 /health에 게시되어 온체인에서 감사 가능합니다. 서비스 쿼리는 무료로 유지되며, 호출당 추가 비용이나 스프레드는 없습니다.

지원 자산

• 체인: Base (8453). 이더리움 메인넷, Arbitrum, Optimism, BNB는 로드맵에 포함되어 있습니다.

• 토큰: Base에서 0x 또는 Velora가 지원하는 모든 ERC20 토큰. 커버리지는 두 애그리게이터의 합집합입니다. 표준 페어(USDC, WETH, cbBTC, USDT, DAI, AERO)는 양쪽 모두에서 라우팅 가능하며, 롱테일 토큰은 종종 둘 중 하나에서만 라우팅됩니다.

로드맵

• [x] Base에서의 0x Settler 라우팅

• [x] Base에서의 0x 및 Velora 전반의 최적(Best-of-N) 라우팅 (v0.11.66+, 2026-05-04)

• [x] MCP Streamable-HTTP 전송

• [x] trust_check_preview MCP 도구 (v0.11.65)

• [ ] 1inch + Odos 추가 라우팅 소스 — 계획 중

• [ ] 이더리움 메인넷, Arbitrum, BNB, Optimism — 계획 중

• [ ] Permit2 네이티브 흐름 (승인 트랜잭션 생략) — 계획 중

상태

운영 중. 엔드포인트는 라이브 상태이며 모니터링되고 있고, Base에서의 온체인 테스트 트랜잭션을 통해 엔드투엔드로 검증되었습니다. 현재 수수료 설정, 버전 및 소스별 카운터는 /health를 참조하세요.

이 저장소의 구성

이 저장소에 포함되지 않은 것: 호스팅된 백엔드(독점). 이 저장소는 공개 클라이언트 인터페이스(설치 지침, 스키마, 통합 코드 샘플)입니다.

연락처

• 이메일: dev@paladinfi.com

• 마케팅: paladinfi.com

• API: swap.paladinfi.com/health

• 랜딩 페이지: paladinfi.com/swap/

법적 고지

미시간주 유한책임회사인 PaladinFi라는 이름으로 영업하는 Malcontent Games LLC가 운영합니다. 이 서비스는 제3자 애그리게이터(현재 0x 및 Velora)를 통해 견적을 라우팅합니다. 사용자는 자산에 대한 통제권을 유지하며, 에이전트가 모든 트랜잭션에 서명합니다. PaladinFi는 사용자 자금을 보유하지 않습니다.

호스팅된 서비스의 사용은 PaladinFi 서비스 약관 및 개인정보 처리방침의 적용을 받습니다.

라이선스

이 저장소의 내용은 MIT 라이선스에 따라 공개됩니다. 호스팅된 백엔드는 독점 기술이며 라이선스 범위에 포함되지 않습니다.