swapper-integration

Swapper Integration Skill

You are an expert at integrating DEX aggregators, swappers, and bridge protocols into ShapeShift Web. This skill guides you through the complete process from API research to production-ready implementation.

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"
• "Integrate [new swapper]"

Overview

ShapeShift Web is a decentralized crypto exchange aggregator that supports multiple swap providers through a unified interface. Each swapper implements standardized TypeScript interfaces (Swapper and SwapperApi) but has variations based on blockchain type (EVM, UTXO, Solana, Sui, Tron) and swapper model (direct transaction, deposit-to-address, gasless order-based).

Core Architecture:

• Location: packages/swapper/src/swappers/
• Interfaces: Swapper (execution) + SwapperApi (quotes/rates/status)
• Types: Strongly typed with chain-specific adaptations
• Feature Flags: All swappers behind runtime flags for gradual rollout

Your Role: Research → Implement → Test → Document, following battle-tested patterns from 13+ existing swapper integrations.

---

Workflow

Phase 0: Pre-Research (Use WebFetch / WebSearch)

BEFORE asking the user for anything, proactively research the swapper online:

1. Search for official documentation:

   Search: "[SwapperName] API documentation"
   Search: "[SwapperName] developer docs"
   Search: "[SwapperName] swagger api"
   

2. Find their website and look for:

   • API docs link
   • Developer portal
   • GitHub repos with examples
   • Public API endpoints
   • Known integrations

3. Fetch their API docs using WebFetch:

   • Main documentation page
   • Swagger/OpenAPI spec (if available)
   • Example requests/responses

4. Research chain support:

   Search: "[SwapperName] supported chains"
   Search: "[SwapperName] which blockchains"
   

5. Find existing integrations:

   Search: "github [SwapperName] integration example"
   Search: "[SwapperName] typescript sdk"
   

Then, compile what you found and ask the user ONLY for what you couldn't find or need confirmation on.

---

Phase 1: Information Gathering

Use the AskUserQuestion tool to gather missing information with structured prompts.

Based on your Phase 0 research, ask the user for:

1. API Access (if needed):

   • API key for production (or staging)
   • Any authentication requirements you found
   • Confirmation of API endpoints you discovered

2. Chain Support Confirmation:

   • Verify the chains you found are correct
   • Ask about any limitations or special requirements per chain
   • Confirm chain naming convention (ethereum vs 1 vs mainnet)

3. Critical API Behaviors (if not clear from docs):

   • Slippage format: percentage (1=1%), decimal (0.01=1%), or basis points (100=1%)?
   • Address format: checksummed required?
   • Native token handling: marker address? which one?
   • Min/max trade amounts?
   • Quote expiration time?

4. Brand Assets:

   • Confirm official name and capitalization
   • Request logo/icon (128x128+ PNG preferred)

5. Known Issues:

   • Any quirks they're aware of?
   • Previous integration attempts or examples?

Example Multi-Question Prompt:

AskUserQuestion({
  questions: [
    {
      question: "Do we have an API key for [Swapper]?",
      header: "API Key",
      multiSelect: false,
      options: [
        { label: "Yes, I have it", description: "I'll provide the API key" },
        { label: "No, but we can get one", description: "I'll obtain an API key" },
        { label: "No API key needed", description: "API is public/unauthenticated" }
      ]
    },
    {
      question: "Which chains should we support initially?",
      header: "Chain Support",
      multiSelect: true,
      options: [
        { label: "Ethereum", description: "Ethereum mainnet" },
        { label: "Polygon", description: "Polygon PoS" },
        { label: "Arbitrum", description: "Arbitrum One" },
        { label: "All supported chains", description: "Enable all chains the API supports" }
      ]
    }
  ]
})

---

Phase 2: Deep Research & Pattern Analysis

IMPORTANT: Study existing swappers BEFORE writing any code. This prevents reimplementing solved problems.

Step 1: Identify Swapper Category

Based on API research, determine the swapper type:

EVM Direct Transaction (Most Common):

• Characteristics: Single EVM chain, returns transaction data, user signs & broadcasts
• Examples: Bebop, 0x, Portals
• Key Files: bebopTransactionMetadata, zrxTransactionMetadata, portalsTransactionMetadata
• Choose this if: API returns {to, data, value, gas} transaction object

Deposit-to-Address (Cross-Chain/Async):

• Characteristics: User sends to deposit address, swapper handles execution asynchronously
• Examples: Chainflip, NEAR Intents, THORChain
• Key Files: Uses [swapper]Specific metadata with depositAddress
• Choose this if: API returns deposit address and swap ID for tracking

Gasless Order-Based:

• Characteristics: Sign message not transaction, relayer executes, no gas
• Examples: CowSwap
• Key Files: Uses cowswapQuoteResponse, custom executeEvmMessage
• Choose this if: Uses EIP-712 message signing + order submission

Solana-Only:

• Characteristics: Solana transaction with instructions and ALTs
• Examples: Jupiter
• Key Files: jupiterQuoteResponse, solanaTransactionMetadata
• Choose this if: Solana ecosystem only

Chain-Specific (Sui/Tron/etc.):

• Characteristics: Custom transaction format for specific blockchain
• Examples: Cetus (Sui)
• Key Files: Chain-specific adapters and transaction metadata
• Choose this if: Non-EVM, non-Solana blockchain with custom SDK

Step 2: Study 2-3 Similar Swappers IN DEPTH

Read these files for your chosen swapper type:

# For EVM Direct Transaction (e.g., Bebop):
packages/swapper/src/swappers/BebopSwapper/
├── BebopSwapper.ts                # Swapper interface (usually just executeEvmTransaction)
├── endpoints.ts                   # SwapperApi implementation
├── types.ts                       # API request/response types
├── getBebopTradeQuote/
│   └── getBebopTradeQuote.ts     # Quote logic (WITH fee estimation)
├── getBebopTradeRate/
│   └── getBebopTradeRate.ts      # Rate logic (withOUT wallet, may use dummy address)
└── utils/
    ├── constants.ts               # Supported chains, native marker, defaults
    ├── bebopService.ts            # HTTP client with cache + API key injection
    ├── fetchFromBebop.ts          # API wrappers (fetchQuote, fetchPrice)
    └── helpers/
        └── helpers.ts             # Validation, rate calc, address helpers

Read these files for deposit-to-address (e.g., NEAR Intents):

packages/swapper/src/swappers/NearIntentsSwapper/
├── endpoints.ts                   # checkTradeStatus uses depositAddress from metadata
├── swapperApi/
│   ├── getTradeQuote.ts          # Stores depositAddress in nearIntentsSpecific
│   └── getTradeRate.ts
└── utils/
    ├── oneClickService.ts         # OneClick SDK initialization
    └── helpers/
        └── helpers.ts             # Asset mapping, status translation

Critical things to note while reading:

1. How do they call the API? (HTTP service pattern? SDK? Direct axios?)
2. How do they handle errors? (Monadic Result<T, SwapErrorRight> pattern)
3. How do they calculate rates? (getInputOutputRate util vs custom)
4. What metadata do they store in TradeQuoteStep?
5. How do they validate inputs? (Supported chains? Asset compatibility?)
6. How do they handle native tokens? (Marker address vs special field)
7. How do they convert API responses to our types?

Step 3: Review Common Patterns

Key Pattern: Monadic Error Handling

import { Err, Ok } from '@sniptt/monads'
import { makeSwapErrorRight } from '../../../utils'

// ALWAYS return Result<T, SwapErrorRight>, NEVER throw
const result = await someOperation()
if (result.isErr()) {
  return Err(makeSwapErrorRight({
    message: 'What went wrong',
    code: TradeQuoteError.QueryFailed,
    details: { context: 'here' }
  }))
}
return Ok(result.unwrap())

Key Pattern: HTTP Service with Caching

import { createCache, makeSwapperAxiosServiceMonadic } from '../../../utils'

const maxAge = 5 * 1000 // 5 seconds
const cachedUrls = ['/quote', '/price'] // which endpoints to cache

const serviceBase = createCache(maxAge, cachedUrls, {
  timeout: 10000,
  headers: {
    'Accept': 'application/json',
    'x-api-key': config.VITE_XYZ_API_KEY
  }
})

export const xyzService = makeSwapperAxiosServiceMonadic(serviceBase)

Key Pattern: Rate Limiting and Throttling

For chain adapters and swappers that directly interact with RPC endpoints or APIs:

import PQueue from 'p-queue'

// In constructor or module scope:
private requestQueue: PQueue = new PQueue({
  intervalCap: 1,    // 1 request per interval
  interval: 50,      // 50ms between requests
  concurrency: 1,    // 1 concurrent request at a time
})

// Wrap all external API/RPC calls:
const quote = await this.requestQueue.add(() =>
  swapperService.get('/quote', { params })
)

// For provider calls in chain adapters:
const balance = await this.requestQueue.add(() =>
  this.provider.getBalance(address)
)

When to use: Any swapper or chain adapter making direct RPC/API calls (especially public endpoints) Example implementations: MonadChainAdapter, PlasmaChainAdapter

Key Pattern: Rate Calculation

import { getInputOutputRate } from '../../../utils'

const rate = getInputOutputRate({
  sellAmountCryptoBaseUnit,
  buyAmountCryptoBaseUnit,
  sellAsset,
  buyAsset
})

---

Phase 3: Im

---

Content truncated.