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)
• Rate/quote split: rates are display-only best effort; quotes are executable artifacts carrying transactionData (a TxBuildData variant) built at quote time. Execution and the public api consume the quote payload as-is — static data is set at quote time, only dynamic data (gas price, solana priority fee, nonce, blockhash) is fetched at execution.
• Canonical shape: every swapper follows the context split — pure helpers.ts, shared getXTradeContext.ts, discriminated getXStepData.ts, thin getTradeQuote/getTradeRate arm wrappers. AcrossSwapper is the spec in code form; the authoritative conventions rubric lives in .claude/skills/swapper-rate-quote-review/SKILL.md — read it alongside this skill.
• Feature Flags: All swappers behind runtime flags for gradual rollout

Your Role: Research → Implement → Test → Document, following battle-tested patterns from 18 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. Every category produces the same canonical structure — the category only changes what the quote's transactionData variant is and how the context/step data derive it.

EVM Direct Transaction (Most Common):

• Characteristics: EVM chain(s), API returns transaction data, user signs & broadcasts
• Canonical examples: ZrxSwapper, PortalsSwapper, BebopSwapper (EVM arm), DebridgeSwapper, AcrossSwapper
• Quote carries: transactionData: { type: 'evm', chainId, to, data, value, gasLimit } — the gasLimit is ALWAYS set (provider-supplied, or estimated-and-set by getEvmNetworkFeeCryptoBaseUnit)
• Choose this if: API returns {to, data, value, gas} transaction object

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

• Characteristics: user sends a plain transfer to a provider deposit address; provider executes asynchronously; status tracked by a provider-side id
• Canonical examples: BobGatewaySwapper (order resolved once up front), ChainflipSwapper (deposit channel opened quote-side), NearIntentsSwapper
• Quote carries: a normal chain-namespace transactionData (the transfer we build) PLUS a swapperMetadata union member holding the tracking id / deposit address
• Choose this if: API returns a deposit address and an id for tracking

Gasless Order-Based:

• Characteristics: sign an EIP-712 message (not a tx); order submitted to the provider; no broadcast
• Canonical example: CowSwapper — transactionData: { type: 'cowswap', chainId, orderToSign }, getUnsignedEvmMessage is a thin reader, executeEvmMessage signs + POSTs the order
• Choose this if: uses EIP-712 message signing + order submission

Solana:

• Instruction-based routes: transactionData: { type: 'solana_instructions', instructions, addressLookupTableAddresses } with the static compute unit limit set at quote time via withComputeUnitLimit (measured simulation × per-swapper margin); execution fetches only the dynamic priority fee. Canonical: the solana arms of AcrossSwapper/ButterSwap/RelaySwapper.
• Sealed RFQ txs (maker pre-signed, blockhash pinned): transactionData: { type: 'solana_serialized_tx', serializedTx } — co-sign as-is, never rebuild. Canonical: BebopSwapper solana arm.

Multi-Chain:

• One swapper spanning namespaces: a single switch (chainNamespace) in step data with BOTH arms inline per case. Canonical: ButterSwap (evm/utxo/solana/tron), RelaySwapper, NearIntentsSwapper.

Chain-Specific (Sui/Tron/Starknet/TON):

• Un-migrated namespaces: quotes are fee-only (no transactionData); execution re-derives from swapperMetadata or provider re-fetch. Canonical: CetusSwapper (sui), SunioSwapper (tron — the one migrated tron example), AvnuSwapper (starknet), StonfiSwapper (ton). New chain-specific swappers still get the full context split (Cetus/Stonfi prove it applies without an executable payload).

Step 2: Study the Canonical Architecture IN DEPTH

Read the conventions rubric first: .claude/skills/swapper-rate-quote-review/SKILL.md — it is the authoritative spec for the structure below and its edge cases.

Then read Across — the reference implementation:

packages/swapper/src/swappers/AcrossSwapper/
├── index.ts                        # Barrel: exports { acrossApi, acrossSwapper } at minimum
├── AcrossSwapper.ts                # Swapper interface (shared executors)
├── endpoints.ts                    # SwapperApi: scoped input casts + shared chain exec utils
├── getTradeQuote/
│   └── getTradeQuote.ts            # Quote arm wrapper: assertQuoteAddresses → context → step data → Trade[]
├── getTradeRate/
│   └── getTradeRate.ts             # Rate arm wrapper: owns ?? default-address fallbacks → Trade[]
└── utils/
    ├── types.ts                    # API types + scoped AcrossTrade{Quote,Rate}Input aliases
    ├── helpers.ts                  # PURE helpers: assertValidTrade, address mappers, fee fallbacks
    ├── acrossService.ts            # HTTP client with cache + API key injection
    ├── fetchAcrossTrade.ts         # API wrappers
    ├── getAcrossTradeContext.ts    # Shared core: fetch + derivations, ZERO quoteOrRate checks
    └── getAcrossStepData.ts        # Discriminated rate/quote step data (StepDataArgs, overloaded)

Then read 1-2 swappers of your category (see canonical examples above).

Critical things to note while reading:

1. How the context splits from the arm wrappers (what is shared vs arm-specific)
2. The StepDataArgs<Base, RateExtra, QuoteExtra> generic and the overloaded step data returns
3. How errors flow: no throws in step data/context — scoped try/catch mapping to makeNetworkFeeEstimationFailedErr / makeTradeStepBuildFailedErr / `makeSwa

---

Content truncated.