@pioneer-platform/swapkit-client 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @pioneer-platform/swapkit-client
+
+## 0.0.2
+
+### Patch Changes
+
+- chore: chore: chore: chore: fix: move @types/pdfkit to dependencies for Docker --production build
+- Updated dependencies
+  - @pioneer-platform/pioneer-caip@9.10.9
+  - @pioneer-platform/pioneer-coins@9.11.9

package/README.md

@@ -0,0 +1,159 @@
+# 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