鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

swapper-integration

实现去中心化交易所聚合器或桥接协议的集成能力,支持将新的交易服务添加到 ShapeShift Web 平台,涵盖研究、开发与测试全流程,确保遵循现有架构模式完成兼容性对接。

区块链
访问 GitHub
文档Skills.MD
name
swapper-integration
description
Integrate new DEX aggregators, swappers, or bridge protocols (like Bebop, Portals, Jupiter, 0x, 1inch, etc.) into ShapeShift Web. Activates when user wants to add, integrate, or implement support for a new swapper. Guides through research, implementation, and testing following established patterns.
allowed-tools
Read, Write, Edit, Grep, Glob, Bash(yarn test:*), Bash(yarn lint:*), Bash(yarn type-check), Bash(yarn build:*)

Swapper Integration Skill

You are helping integrate a new DEX aggregator, swapper, or bridge into ShapeShift Web. This skill guides you through the complete process from research to testing.

When This Skill Activates

Use this skill when the user wants to:

  • "Integrate [SwapperName] swapper"
  • "Add support for [Protocol]"
  • "Implement [DEX] integration"
  • "Add [Aggregator] as a swapper"

Overview

ShapeShift Web supports multiple swap aggregators through a unified swapper interface located in packages/swapper/src/swappers/. Each swapper follows consistent patterns, but has variations based on its type (EVM, Solana, cross-chain, gasless, etc.).

Your task: Research existing swappers to understand patterns, then adapt them for the new integration.

Workflow

Phase 1: Information Gathering

Before starting implementation, collect ALL required information from the user.

Use the AskUserQuestion tool to interactively gather this information with structured prompts.

Ask the user for:

  1. API Documentation

    • Link to official API documentation (main docs)
    • Link to Swagger/OpenAPI specification (separate link, if available)
    • API base URL
    • Authentication method (API key? signature? none?)
    • If API key needed: Obtain production API key to add to .env.base
    • Rate limiting details
  2. Supported Networks

    • Which blockchains (Ethereum, Polygon, Arbitrum, Solana, etc.)?
    • Any network-specific limitations?
    • Chain naming convention (e.g., "ethereum" vs "1" vs "mainnet")
  3. API Behavior

    • CRITICAL: How does slippage work? (percentage like 1=1%? decimal like 0.01=1%? basis points like 100=1%?)
    • Does it require checksummed addresses?
    • How are native tokens handled? (special marker address? omit field?)
    • Minimum/maximum trade amounts?
    • Quote expiration time?
  4. Brand Assets

    • Official swapper name (exact capitalization)
    • Logo/icon file or link (PNG preferred, 128x128 or larger)
    • Brand colors (optional)
  5. Reference Materials (helpful but optional)

    • Example integrations on GitHub
    • Sample curl requests + responses from their dApp
    • Known quirks or gotchas
    • Community/support contact

Action: Stop and gather this information before proceeding. Missing details cause bugs later.


Phase 2: Research & Understanding

IMPORTANT: Don't guess at implementation details. Research thoroughly before coding.

Step 0: Study the API Documentation

Before looking at code, understand the swapper's API:

  1. Read the official docs (link from Phase 1)

    • How does the API work?
    • What endpoints are available?
    • What's the request/response format?
    • Any special requirements or quirks?
  2. Study the Swagger/OpenAPI spec (if available)

    • Exact request parameters
    • Response schema
    • Error formats
    • Example requests/responses
  3. Key things to verify:

    • How is slippage formatted in requests?
    • Are addresses checksummed in examples?
    • How are native tokens represented?
    • What does a successful quote response look like?
    • What error responses can occur?

Try making a test curl request if possible to see real responses.

Step 1: Explore Existing Swappers

Now that you understand the API, see how existing swappers work:

Step 1: Explore the swappers directory

▼
bash
复制代码
# List all existing swappers ls packages/swapper/src/swappers/

You'll see swappers like:

  • BebopSwapper
  • ZrxSwapper
  • CowSwapper
  • PortalsSwapper
  • JupiterSwapper
  • ThorchainSwapper
  • And others...

Step 2: Identify similar swappers

Based on what you gathered in Phase 1, determine which swapper type yours is:

EVM Single-Hop (most common):

  • Same-chain swaps only
  • Standard transaction signing
  • Examples: BebopSwapper, ZrxSwapper, PortalsSwapper

Gasless / Order-Based:

  • Sign message instead of transaction
  • No gas fees
  • Examples: CowSwapper

Solana-Only:

  • Solana ecosystem
  • Different execution model
  • Examples: JupiterSwapper

Cross-Chain / Multi-Hop:

  • Bridge or cross-chain swaps
  • May have multiple steps
  • Examples: ThorchainSwapper, ChainflipSwapper

Bridge-Specific:

  • Focus on bridging, not swapping
  • Examples: ArbitrumBridgeSwapper, RelaySwapper

Step 3: Study similar swappers

Pick 2-3 similar swappers and read their implementations:

▼
text
复制代码
# Example: If building an EVM aggregator, study these: @packages/swapper/src/swappers/BebopSwapper/BebopSwapper.ts @packages/swapper/src/swappers/BebopSwapper/endpoints.ts @packages/swapper/src/swappers/BebopSwapper/types.ts @packages/swapper/src/swappers/BebopSwapper/INTEGRATION.md @packages/swapper/src/swappers/ZrxSwapper/ZrxSwapper.ts @packages/swapper/src/swappers/PortalsSwapper/PortalsSwapper.ts

Pay attention to:

  • File structure
  • How they call their APIs
  • How they handle errors
  • How they calculate rates and fees
  • Special handling (checksumming, hex conversion, etc.)

Step 4: Read supporting documentation

Consult the skill's reference materials:

  • @reference.md - General swapper architecture and patterns
  • @common-gotchas.md - Critical bugs to avoid
  • @examples.md - Code templates

Phase 3: Implementation

Follow the pattern established by similar swappers. Don't reinvent the wheel.

Step 1: Create directory structure

Create packages/swapper/src/swappers/[SwapperName]Swapper/

For most EVM swappers, create:

▼
text
复制代码
[SwapperName]Swapper/ ├── index.ts ├── [SwapperName]Swapper.ts ├── endpoints.ts ├── types.ts ├── get[SwapperName]TradeQuote/ │ └── get[SwapperName]TradeQuote.ts ├── get[SwapperName]TradeRate/ │ └── get[SwapperName]TradeRate.ts └── utils/ ├── constants.ts ├── [swapperName]Service.ts ├── fetchFrom[SwapperName].ts └── helpers/ └── helpers.ts

Check @examples.md for structure templates.

Step 2: Implement core files

Order (follow this sequence):

  1. types.ts: Define TypeScript interfaces based on API responses
  2. utils/constants.ts: Supported chains, default slippage, native token markers
  3. utils/helpers/helpers.ts: Helper functions (validation, rate calculation)
  4. utils/[swapperName]Service.ts: HTTP service wrapper
  5. utils/fetchFrom[SwapperName].ts: API fetch functions
  6. get[SwapperName]TradeQuote.ts: Quote logic
  7. get[SwapperName]TradeRate.ts: Rate logic
  8. endpoints.ts: Wire up SwapperApi interface
  9. [SwapperName]Swapper.ts: Main swapper class
  10. index.ts: Exports

Refer to @examples.md for code templates. Copy patterns from similar existing swappers.

Step 3: Add Swapper-Specific Metadata (ONLY if needed)

When is metadata needed?

  • Deposit-to-address swappers (Chainflip, NEAR Intents) - need deposit address, swap ID for status polling
  • Order-based swappers (CowSwap) - need order ID for status tracking
  • Any swapper that requires tracking state between quote → execution → status polling

When is metadata NOT needed?

  • Direct transaction swappers (Bebop, 0x, Portals) - transaction is built from quote, no async tracking needed
  • Same-chain aggregators where transaction hash is sufficient for status tracking
  • Most EVM-only swappers that return transaction data directly

If your swapper doesn't need async status polling or deposit addresses, skip this step!

Three places to add metadata:

a. Define types (packages/swapper/src/types.ts):

Add to TradeQuoteStep type:

▼
typescript
复制代码
export type TradeQuoteStep = { // ... existing fields [swapperName]Specific?: { depositAddress: string swapId: number // ... other swapper-specific fields } }

Add to SwapperSpecificMetadata type (for swap storage):

▼
typescript
复制代码
export type SwapperSpecificMetadata = { chainflipSwapId: number | undefined nearIntentsSpecific?: { depositAddress: string depositMemo?: string timeEstimate: number deadline: string } // Add your swapper's metadata here [swapperName]Specific?: { // ... fields needed for status polling } // ... other fields }

b. Populate in quote (packages/swapper/src/swappers/[Swapper]/swapperApi/getTradeQuote.ts):

Store metadata in the TradeQuoteStep:

▼
typescript
复制代码
const tradeQuote: TradeQuote = { // ... other fields steps: [{ // ... step fields [swapperName]Specific: { depositAddress: response.depositAddress, swapId: response.id, // ... other data needed later } }] }

c. Extract into swap (TWO places required!):

Place 1: src/components/MultiHopTrade/components/TradeConfirm/hooks/useTradeButtonProps.tsx

Add to metadata object around line 114-126:

▼
typescript
复制代码
metadata: { chainflipSwapId: firstStep?.chainflipSpecific?.chainflipSwapId, nearIntentsSpecific: firstStep?.nearIntentsSpecific, // Add your swapper's metadata extraction here: [swapperName]Specific: firstStep?.[swapperName]Specific, relayTransactionMetadata: firstStep?.relayTransactionMetadata, stepIndex: currentHopIndex, quoteId: activeQuote.id, streamingSwapMetadata: { ... } }

Place 2: src/lib/tradeExecution.ts (CRITICAL - often forgotten!)

Add to metadata object around line 156-161:

▼
typescript
复制代码
metadata: { ...swap.metadata, chainflipSwapId: tradeQuote.steps[0]?.chainflipSpecific?.chainflipSwapId, nearIntentsSpecific: tradeQuote.steps[0]?.nearIntentsSpecific, // Add your swapper's metadata extraction here: [swapperName]Specific: tradeQuote.steps[0]?.[swapperName]Specific, relayTransactionMetadata: tradeQuote.steps[0]?.relayTransactionMetadata, stepIndex, }

Why both places?

  • useTradeButtonProps creates the initial swap (before wallet signature)
  • tradeExecution updates the swap during execution (after wallet signature, with actual tradeQuote)
  • If you only add to one place, metadata will be missing!

d. Access in status check (packages/swapper/src/swappers/[Swapper]/endpoints.ts):

▼
typescript
复制代码
checkTradeStatus: async ({ config, swap }) => { const { [swapperName]Specific } = swap?.metadata ?? {} if (![swapperName]Specific?.swapId) { throw new Error('swapId is required for status check') } // Use metadata to poll API const status = await api.getStatus([swapperName]Specific.swapId) // ... }

Example: NEAR Intents metadata flow

▼
text
复制代码
1. Quote: Store in step.nearIntentsSpecific.depositAddress 2. Swap creation: Extract to swap.metadata.nearIntentsSpecific 3. Status check: Read from swap.metadata.nearIntentsSpecific.depositAddress

Step 4: Register the swapper

Update these files to register your new swapper:

  1. packages/swapper/src/constants.ts

    • Add to SwapperName enum
    • Add to swappers record
    • Add default slippage
  2. packages/swapper/src/index.ts

    • Export new swapper
  3. packages/swapper/src/types.ts

    • Add API config fields (if not already done in metadata step)
  4. CSP Headers (if swapper calls external API):

    • Create headers/csps/defi/swappers/[SwapperName].ts:
      ▼
      typescript
      复制代码
      import type { Csp } from '../../../types' export const csp: Csp = { 'connect-src': ['https://api.[swapper].com'], }
    • Register in headers/csps/index.ts:
      ▼
      typescript
      复制代码
      import { csp as [swapperName] } from './defi/swappers/[SwapperName]' export const csps = [ // ... other csps [swapperName], ]
  5. UI Integration (src/):

    a. Add swapper icon:

    • Place icon file at: src/components/MultiHopTrade/components/TradeInput/components/SwapperIcon/[swapper]-icon.png
    • Recommended: 128x128 PNG with transparent background

    b. Update SwapperIcon component:

    • File: src/components/MultiHopTrade/components/TradeInput/components/SwapperIcon/SwapperIcon.tsx
    • Import icon: import [swapperName]Icon from './[swapper]-icon.png'
    • Add case to switch statement:
      ▼
      typescript
      复制代码
      case SwapperName.[SwapperName]: return <Image src={[swapperName]Icon} />

    c. Add feature flag (REQUIRED):

    • File: src/state/slices/preferencesSlice/preferencesSlice.ts
    • Add to FeatureFlags type:
      ▼
      typescript
      复制代码
      export type FeatureFlags = { // ... [SwapperName]Swap: boolean }
    • Add to initial state:
      ▼
      typescript
      复制代码
      const initialState: Preferences = { featureFlags: { // ... [SwapperName]Swap: getConfig().VITE_FEATURE_[SWAPPER]_SWAP, } }

    d. Wire up feature flag:

    • File: src/state/helpers.ts
    • Add to isCrossAccountTradeSupported function parameter and switch statement (if swapper supports cross-account)
    • Add to getEnabledSwappers function:
      ▼
      typescript
      复制代码
      export const getEnabledSwappers = ( { [SwapperName]Swap, // Add to destructured parameters ...otherFlags }: FeatureFlags, ... ): Record<SwapperName, boolean> => { return { // ... [SwapperName.[SwapperName]]: [SwapperName]Swap && (!isCrossAccountTrade || isCrossAccountTradeSupported(SwapperName.[SwapperName])), } }

    e. Update test mocks (REQUIRED):

    • File: src/test/mocks/store.ts
    • Add feature flag to mock featureFlags object:
      ▼
      typescript
      复制代码
      featureFlags: { // ... other flags [SwapperName]Swap: false, }
  6. Configuration:

    Environment variables - Follow naming conventions (e.g., Bebop):

    .env (base/production - both API key and feature flag OFF):

    ▼
    bash
    复制代码
    # Bebop VITE_BEBOP_API_KEY= VITE_FEATURE_BEBOP_SWAP=false

    .env.development (development - feature flag ON):

    ▼
    bash
    复制代码
    # Bebop VITE_BEBOP_API_KEY=your-dev-api-key-here VITE_FEATURE_BEBOP_SWAP=true

    Naming pattern:

    • API key: VITE_[SWAPPER]_API_KEY (in both .env and .env.development)
    • Feature flag: VITE_FEATURE_[SWAPPER]_SWAP (.env = false, .env.development = true)
    • Other config: VITE_[SWAPPER]_BASE_URL (if needed, both files)
    • Config file (src/config.ts):
      ▼
      typescript
      复制代码
      export const getConfig = (): Config => ({ // ... VITE_[SWAPPER]_API_KEY: import.meta.env.VITE_[SWAPPER]_API_KEY || '', VITE_[SWAPPER]_BASE_URL: import.meta.env.VITE_[SWAPPER]_BASE_URL || '', VITE_FEATURE_[SWAPPER]_SWAP: parseBoolean(import.meta.env.VITE_FEATURE_[SWAPPER]_SWAP), })

Step 4: Check common gotchas

Before testing, review @common-gotchas.md to avoid known bugs:

  • Slippage format issues
  • Address checksumming
  • Hex value conversion
  • Response parsing errors
  • Rate vs quote affiliate fee deltas

Fix these proactively!


Phase 4: Testing & Validation

Run validation commands:

▼
bash
复制代码
# Type checking yarn type-check # Linting yarn lint # Build yarn build:swapper

All must pass before manual testing.

Manual testing checklist:

  • Can fetch quotes successfully
  • Rates display correctly
  • Approval flow works (if needed)
  • Transaction execution completes
  • Error handling works (bad chain, insufficient liquidity, etc.)
  • UI shows swapper correctly
  • Feature flag toggles swapper on/off

See @reference.md for detailed testing strategies.


Phase 5: Documentation

Create packages/swapper/src/swappers/[SwapperName]Swapper/INTEGRATION.md

Document:

  1. API overview (URLs, auth, chains)
  2. Key implementation details
  3. Critical quirks or gotchas
  4. Sample requests/responses
  5. Testing notes

Use BebopSwapper's INTEGRATION.md as a template.


Key Principles

  1. Research, don't guess: Study existing swappers before coding
  2. Copy patterns: Don't reinvent - adapt what works
  3. Read gotchas: Avoid bugs others already fixed
  4. Test thoroughly: Type check, lint, build, manual test
  5. Document quirks: Help future maintainers

Success Criteria

Integration is complete when:

✅ All validation commands pass (type-check, lint, build) ✅ Swapper appears in UI when feature flag is enabled ✅ Can successfully fetch quotes and execute trades ✅ Error cases handled gracefully ✅ Integration documentation written ✅ Code follows patterns from similar swappers

Reference Files

  • @reference.md - Swapper architecture and patterns
  • @examples.md - Code templates
  • @common-gotchas.md - Critical bugs to avoid

Need Help?

If stuck:

  1. Read similar swapper implementations
  2. Check @common-gotchas.md for your specific issue
  3. Grep for similar patterns in existing swappers
  4. Ask user for clarification on API behavior
区块链

快捷安装

复制到终端去安装 Skill

npxskillsaddMicrock/ordinary-claude-skills--skill"swapper-integration"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
property-based-testing
通过生成随机输入验证代码在各类边界条件下的行为一致性,适用于序列化、解析、归一化及纯函数等场景,能有效发现隐含缺陷并提升测试覆盖率,尤其适合需要高可靠性的算法与智能合约验证。
compliance-checker
能够对基础设施配置进行合规性评估,检查是否符合 SOC2、HIPAA 和 PCI DSS 等行业标准,识别潜在的安全风险与违规项,并生成改进建议报告,适用于安全审计与合规审查场景。
orchestration
作为系统的核心协调中枢,负责将用户复杂需求拆解为并行任务流,动态调度不同能力的智能体协同工作,自动管理任务依赖与执行状态,并在后台静默完成多线程探索、分析与实现,最终整合结果交付完整解决方案。
skill-adapter
对基础设施配置进行多标准合规性评估,覆盖 SOC2、HIPAA 和 PCI DSS 等主流框架,自动识别配置偏差与安全风险,并生成可操作的整改建议报告,支撑持续合规治理与审计准备。
contract-test-creator
自动生成符合行业规范的契约测试代码与配置,提供从框架搭建到单元测试、集成测试及模拟对象编写的全流程支持,适用于需要实现高质量自动化测试验证的开发场景。