npm package: @pioneer-platform/swapkit-client
Description: API-only integration with SwapKit for cross-chain swaps and DEX aggregation, explicitly excluding THORChain and MayaChain providers.
Latest version: 1.0.0

# SwapKit Integration

API-only integration with SwapKit for cross-chain swaps and DEX aggregation, explicitly excluding THORChain and MayaChain providers.

## Overview

This module integrates with the SwapKit API (https://api.swapkit.dev) to provide:
- Cross-chain swaps via Chainflip and NEAR protocols
- DEX aggregation via 1inch, Jupiter, and other providers
- Multi-chain support for 14+ EVM and non-EVM chains

**Note**: THORChain and MayaChain providers are explicitly excluded from this integration.

## Supported Networks

- **Ethereum Mainnet** (eip155:1)
- **Arbitrum** (eip155:42161)
- **Base** (eip155:8453)
- **Optimism** (eip155:10)
- **Polygon** (eip155:137)
- **Avalanche C-Chain** (eip155:43114)
- **BSC** (eip155:56)
- **Gnosis** (eip155:100)
- **Berachain** (eip155:80094)
- **Monad** (eip155:143)
- **Hyperliquid** (eip155:2868)
- **Sonic** (eip155:146)
- **Unichain** (eip155:130)
- **Aurora** (eip155:1313161554)

## SwapKit Capabilities

### ✅ What SwapKit Supports:

1. **Cross-Chain Swaps** (via Chainflip, NEAR):
   - ETH → BTC, SOL, etc.
   - Cross-chain token swaps between major chains

2. **Single-Chain DEX Aggregation**:
   - Best rates across multiple DEXs on same chain
   - Supports 1inch (ETH, AVAX, ARB, BSC), Jupiter (SOL)

3. **Cross-Chain DEX Aggregation** (Swap Ins):
   - Any token on source chain → major tokens on destination chain
   - Currently: 1inch + Chainflip on ETH, AVAX, BSC

### ❌ What SwapKit Does NOT Support:

1. **Native L2 Bridges**:
   - ETH mainnet → BASE/ARB/OP (use native bridges)
   - L2 → L2 direct bridging (use dedicated bridge protocols)

2. **THORChain/MayaChain Routes** (excluded by design in this integration)

3. **Stablecoin Bridges**:
   - Cross-chain USDC/USDT transfers may have limited or no routes
   - Native token bridges (Circle CCTP, etc.) are not aggregated

## Usage

```typescript
import swapkit from '@pioneer-platform/pioneer-swapkit'

// Initialize
await swapkit.init({})

// Get quote for cross-chain swap (ETH → BTC via Chainflip)
const quote = await swapkit.getQuote({
    sellAsset: 'eip155:1/slip44:60',        // ETH mainnet native
    buyAsset: 'bip122:000000000019d6689c085ae165831e93/slip44:0',  // BTC
    sellAmount: '1000000000000000',         // 0.001 ETH in wei
    senderAddress: '0x...',
    recipientAddress: 'bc1...',
    slippage: 3                             // 3% slippage
})

// Get quote for same-chain swap (ETH USDC → ETH via 1inch)
const sameChainQuote = await swapkit.getQuote({
    sellAsset: 'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',  // USDC
    buyAsset: 'eip155:1/slip44:60',        // ETH
    sellAmount: '1000000',                  // 1 USDC (6 decimals)
    senderAddress: '0x...',
    recipientAddress: '0x...',
    slippage: 3
})
```

## CAIP to SwapKit Asset Conversion

The integration converts CAIP identifiers to SwapKit format:

### Native Assets:
- `eip155:1/slip44:60` → `ETH.ETH` (Ethereum mainnet)
- `eip155:8453/slip44:60` → `BASE.ETH` (Base - native ETH)
- `eip155:42161/slip44:60` → `ARB.ETH` (Arbitrum - native ETH)
- `eip155:10/slip44:60` → `OP.ETH` (Optimism - native ETH)
- `eip155:43114/slip44:9000` → `AVAX.AVAX` (Avalanche)
- `eip155:137/slip44:966` → `MATIC.MATIC` (Polygon)

### ERC20 Tokens:
- `eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` → `ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`

## API Configuration

Set your SwapKit API key in environment variables:

```bash
SWAPKIT_API_KEY=your_api_key_here
```

Get your API key from: https://partners.swapkit.dev/

## Testing

```bash
bun run test
```

Test suite includes:
- Native ETH cross-chain swaps
- ERC20 token bridges
- L2 ↔ L2 operations
- Error handling and validation

## Response Format

Successful quote response:
```typescript
[{
    provider: 'CHAINFLIP',
    sellAsset: 'ETH.ETH',
    buyAsset: 'BTC.BTC',
    amountOut: '0.00123',
    fees: [...],
    estimatedTime: 600,
    // ... additional fields
}]
```

## Known Limitations

1. **No Native L2 Bridges**: For ETH → BASE/ARB/OP, use dedicated bridge services
2. **Limited Stablecoin Routes**: Cross-chain USDC may not have routes via SwapKit
3. **THORChain Excluded**: By design - use THORChain SDK directly if needed
4. **Provider Availability**: Some routes may not be available depending on liquidity and provider status

## Documentation

- SwapKit API Docs: https://docs.swapkit.dev/
- API Swagger: https://api.swapkit.dev/docs/
- Track Swaps: https://track.swapkit.dev/

## Integration Notes

This integration is designed to work with the Pioneer Router. It:
- Focuses on cross-chain swaps via Chainflip/NEAR
- Aggregates best DEX rates for single-chain swaps
- Excludes THORChain/MayaChain to avoid duplication with other integrations
- Returns standardized quote format compatible with Pioneer SDK