npm package: @sw4p/bridge
Description: Gasless cross-chain USDC transfer SDK
Author: sw4p
Latest version: 0.1.0

# @sw4p/bridge

The official TypeScript SDK for sw4p - gasless cross-chain transfers for stablecoins and native tokens across any blockchain.

## Features

- 🔄 **Cross-Chain Transfers** - Move tokens between any supported blockchain
- ⛽ **Gasless** - Users don't need native tokens for gas
- 🔐 **Non-Custodial** - SDK never handles private keys
- ⚡ **Fast** - Transfers complete in ~60 seconds
- 🛠️ **Simple API** - 3 core methods: `transfer()`, `estimateFee()`, `getStatus()`
- 🌐 **Extensible** - Designed to support every blockchain and token

## Installation

```bash
npm install @sw4p/bridge
# or
pnpm add @sw4p/bridge
```

## Quick Start

```typescript
import { Sw4pBridge } from '@sw4p/bridge'

const bridge = new Sw4pBridge({ apiKey: 'sk_...' })

// Estimate fees
const estimate = await bridge.estimateFee({
  from: 'BASE',
  to: 'SOLANA',
  amount: '100.00'
})
console.log(`Fee: $${estimate.fee.total}, Receive: $${estimate.netReceive}`)

// Execute transfer
const result = await bridge.transfer({
  from: 'BASE',
  to: 'SOLANA',
  amount: '100.00',
  recipient: '5abc...',
  permit: signedPermit
})

// Track status
const status = await bridge.getStatus(result.intentId)
// status.status: 'pending' | 'processing' | 'complete' | 'failed'
```

## Solana → EVM Transfers

Solana source transfers use a two-step signing flow:

```typescript
import { Sw4pBridge } from '@sw4p/bridge'
import { useWallet } from '@solana/wallet-adapter-react'

const bridge = new Sw4pBridge({ apiKey: 'sk_...' })
const { signTransaction } = useWallet()

// 1. Build transaction
const { transaction, intentId } = await bridge.createSolanaTransfer({
  to: 'BASE',
  amount: '100.00',
  fromWallet: publicKey.toBase58(),
  recipient: '0x...'
})

// 2. Sign with wallet
const tx = Transaction.from(Buffer.from(transaction, 'base64'))
const signed = await signTransaction(tx)

// 3. Submit
const result = await bridge.submitSolanaTransfer({
  intentId,
  signedTransaction: Buffer.from(signed.serialize()).toString('base64')
})
```

## EVM Permit Signing

Create gasless approvals using EIP-2612 permits:

```typescript
import { Sw4pBridge } from '@sw4p/bridge'
import { useSignTypedData } from 'wagmi'

const bridge = new Sw4pBridge({ apiKey: 'sk_...' })

// Create permit typed data
const permitData = bridge.createPermitTypedData({
  chain: 'BASE',
  owner: userAddress,
  spender: BRIDGE_SPENDER,
  value: parseUnits('100', 6),
  nonce: await getNonce()
})

// Sign with wallet
const signature = await signTypedData(permitData)

// Use in transfer
await bridge.transfer({ ...params, permit: parseSignature(signature) })
```

## API Reference

### Core Methods

| Method | Description |
|--------|-------------|
| `transfer(params)` | Execute cross-chain transfer |
| `estimateFee(params)` | Get fee estimate before transfer |
| `getStatus(intentId)` | Poll transfer status |

### Route Helpers

| Method | Description |
|--------|-------------|
| `supportsRoute(from, to)` | Check if route is supported |
| `getSupportedPairs()` | List all available routes |
| `getLimits()` | Get min/max transfer amounts |

### Signing Helpers

| Method | Description |
|--------|-------------|
| `createPermitTypedData(params)` | Generate EIP-712 permit data |
| `createSolanaTransfer(params)` | Build Solana transaction for signing |
| `submitSolanaTransfer(params)` | Submit signed Solana transaction |

## Supported Chains (MVP)

> **Note:** sw4p is designed to support every blockchain. Current MVP supports:

| Chain | Code | Type |
|-------|------|------|
| Ethereum | `ETH` | EVM |
| Base | `BASE` | EVM |
| Arbitrum | `ARB` | EVM |
| Polygon | `POLYGON` | EVM |
| Solana | `SOLANA` | Non-EVM |

**Tokens:** USDC (more tokens coming soon)

## Error Handling

```typescript
import { ApiError, AuthError, RateLimitError } from '@sw4p/bridge'

try {
  await bridge.transfer(params)
} catch (error) {
  if (error instanceof AuthError) {
    console.log('Invalid API key')
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry in ${error.retryAfterMs}ms`)
  } else if (error instanceof ApiError) {
    console.log(`API error: ${error.message}`)
  }
}
```

## Configuration

```typescript
const bridge = new Sw4pBridge({
  apiKey: 'sk_...',           // Required
  baseUrl: 'https://...',     // Optional: custom API endpoint
  debug: true,                // Optional: enable request logging
  retry: {
    maxAttempts: 3,           // Retry failed requests
    backoffMs: 1000           // Initial backoff delay
  }
})
```

## License

MIT