swapper-integration

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
2. Link to official API documentation (main docs)
3. Link to Swagger/OpenAPI specification (separate link, if available)
4. API base URL
5. Authentication method (API key? signature? none?)
6. If API key needed: Obtain production API key to add to .env.base
7. Rate limiting details

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

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

1. Brand Assets
2. Official swapper name (exact capitalization)
3. Logo/icon file or link (PNG preferred, 128x128 or larger)
4. Brand colors (optional)

1. Reference Materials (helpful but optional)
2. Example integrations on GitHub
3. Sample curl requests + responses from their dApp
4. Known quirks or gotchas
5. 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)
2. How does the API work?
3. What endpoints are available?
4. What's the request/response format?
5. Any special requirements or quirks?

1. Study the Swagger/OpenAPI spec (if available)
2. Exact request parameters
3. Response schema
4. Error formats
5. Example requests/responses

1. Key things to verify:
2. How is slippage formatted in requests?
3. Are addresses checksummed in examples?
4. How are native tokens represented?
5. What does a successful quote response look like?
6. 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: 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:

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

Add to SwapperSpecificMetadata type (for swap storage):

export type SwapperSpecificMetadata = {
  chainflipSwapId: number | undefined
  nearIntentsSpecific?: {
    depositAddress: string
    depositMemo?: string
    timeEstimate: number
    deadline: strin