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

# 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:

# 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:

[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: 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 transaction metadata type if needed
   • Add API config fields

4. CSP Headers (if swapper calls external API):

   • Add API domain to headers/csps/index.ts
   • Create headers/csps/defi/swappers/[SwapperName].ts with CSP rules

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:

     case SwapperName.[SwapperName]:
       return <Image src={[swapperName]Icon} />
     

   c. Add feature flag (REQUIRED):

   • File: src/state/slices/preferencesSlice/preferencesSlice.ts
   • Add to FeatureFlags type:

     export type FeatureFlags = {
       // ...
       [SwapperName]Swap: boolean
     }
     

   • Add to initial state:

     const initialState: Preferences = {
       featureFlags: {
         // ...
         [SwapperName]Swap: getConfig().VITE_FEATURE_[SWAPPER]_SWAP,
       }
     }
     

   d. Wire up feature flag:

   • File: src/state/helpers.ts
   • Add to isCrossAccountTradeSupported (if applicable)
   • Add to getEnabledSwappers:

     export const getEnabledSwappers = (
       { [SwapperName]Swap, ...otherFlags }: FeatureFlags,
       ...
     ): Record<SwapperName, boolean> => {
       return {
         // ...
         [SwapperName.[SwapperName]]:
           [SwapperName]Swap && (!isCrossAccountTrade || isCrossAccountTradeSupported(SwapperName.[SwapperName])),
       }
     }
     

   e. Update test mocks (if applicable):

   • File: src/test/mocks/store.ts
   • Add feature flag to mock state

6. Configuration:

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

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

   # Bebop
   VITE_BEBOP_API_KEY=
   VITE_FEATURE_BEBOP_SWAP=false
   

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

   # 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):

     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:

# 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