@solsdk/xswap_sdk/README.md

Universal cross-chain swaps SDK

# @solsdk/xswap_sdk – Universal Cross-Chain Swap SDK

@solsdk/xswap_sdk is a robust TypeScript SDK designed to simplify and accelerate cross-chain token swaps across leading blockchain ecosystems. With a modular, extensible architecture and strict type safety, it empowers developers to integrate seamless cross-chain transfers and swaps into their applications with confidence.

## Installation

```bash
npm install @solsdk/xswap_sdk
pnpm install @solsdk/xswap_sdk
yarn add @solsdk/xswap_sdk
```

## Why @solsdk/xswap_sdk?

- **Universal**: Supports major EVM chains (Arbitrum, Optimism, Base, Hyperliquid), Solana, and Sui out of the box.
- **Secure**: Built with strict TypeScript types and best security practices.
- **Modular**: Easily extend or customize for new chains and protocols.
- **Developer-Friendly**: Clean, intuitive API and clear error handling.
- **Production-Ready**: Designed for reliability and scalability in real-world applications.

## Architecture

@solsdk/xswap_sdk uses a modular approach with chain-specific SDKs:

- `EVMSDK` – For Ethereum-compatible chains (Arbitrum, Optimism, Base, Hyperliquid)
- `SolanaSDK` – For Solana blockchain
- `SuiSDK` – For Sui blockchain

## Quick Start

### Import and Initialize

```typescript
import { ChainID, EVMSDK, SolanaSDK, SuiSDK } from "@solsdk/xswap_sdk";

// EVM Example (Arbitrum)
const arbitrumSdk = new EVMSDK({
  chainId: ChainID.Arbitrum,
  privateKey: "0x...", // Your private key
  rpcProviderUrl: "https://arbitrum-mainnet.public.blastapi.io", // Optional
});

// EVM Example (Hyperliquid)
const hyperliquidSdk = new EVMSDK({
  chainId: ChainID.Hyperliquid,
  privateKey: "0x...", // Your private key
  rpcProviderUrl: "https://hyperliquid-rpc.public.blastapi.io", // Optional
});

// Solana Example
const solanaSdk = new SolanaSDK({
  privateKey: "...", // Your private key
  commitment: "finalized", // Or 'confirmed'
  rpcProviderUrl: "https://api.mainnet-beta.solana.com", // Optional
});

// Sui Example
const suiSdk = new SuiSDK({
  privateKey: "...", // Your private key
});
```

### Creating and Submitting Cross-Chain Orders

```typescript
// Prepare a cross-chain order from Arbitrum to Solana
const preparedOrder = await arbitrumSdk.createOrder({
  sourceChainId: ChainID.Arbitrum,
  sourceTokenAddress: "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
  sourceTokenAmount: BigInt(12000),
  destinationChainId: ChainID.Solana,
  destinationTokenAddress: "So11111111111111111111111111111111111111112",
  destinationTokenMinAmount: BigInt(10000),
  destinationAddress: "3Kiz4oBXpR9YuPNsVfvE5XnNzgwjrM9m2CbRzyyEVkpQ",
  minStablecoinAmount: BigInt(11000),
  deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
});

// Or create and send the order in one step
const response = await arbitrumSdk.createAndSendOrder({
  sourceChainId: ChainID.Arbitrum,
  sourceTokenAddress: "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
  sourceTokenAmount: BigInt(12000),
  destinationChainId: ChainID.Solana,
  destinationTokenAddress: "So11111111111111111111111111111111111111112",
  destinationTokenMinAmount: BigInt(10000),
  destinationAddress: "3Kiz4oBXpR9YuPNsVfvE5XnNzgwjrM9m2CbRzyyEVkpQ",
  minStablecoinAmount: BigInt(11000),
  deadline: Math.floor(Date.now() / 1000) + 3600,
});

// Create and send a cross-chain order from Hyperliquid to Optimism
const hyperliquidResponse = await hyperliquidSdk.createAndSendOrder({
  sourceChainId: ChainID.Hyperliquid,
  sourceTokenAddress: "0x4300000000000000000000000000000000000003", // USDC on Hyperliquid
  sourceTokenAmount: BigInt(10_000_000), // 10 USDC (6 decimals)
  destinationChainId: ChainID.Optimism,
  destinationTokenAddress: "0x7F5c764cBc14f9669B88837ca1490cCa17c31607", // USDC on Optimism
  destinationTokenMinAmount: BigInt(9_500_000), // 9.5 USDC minimum
  destinationAddress: "0xYourOptimismAddress", // Optimism address
  minStablecoinAmount: BigInt(9_800_000), // Protocol minimum
  deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
});
```

## Supported Chains

| Chain       | Chain ID | Status       |
| ----------- | -------- | ------------ |
| Arbitrum    | 42161    | ✅ Supported |
| Optimism    | 10       | ✅ Supported |
| Base        | 8453     | ✅ Supported |
| Hyperliquid | 999      | ✅ Supported |
| Solana      | 7565164  | ✅ Supported |
| Sui         | 101      | ✅ Supported |

## Examples

### Cross-Chain Order from Arbitrum to Solana

```typescript
import { ChainID, EVMSDK, ValidationError } from "@solsdk/xswap_sdk";

async function createCrossChainOrder() {
  try {
    const sdk = new EVMSDK({
      chainId: ChainID.Arbitrum,
      privateKey: process.env.PRIVATE_KEY as `0x${string}`,
    });

    const response = await sdk.createAndSendOrder({
      sourceChainId: ChainID.Arbitrum,
      sourceTokenAddress: "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", // USDT on Arbitrum
      sourceTokenAmount: BigInt(10_000_000), // 10 USDT (6 decimals)
      destinationChainId: ChainID.Solana,
      destinationTokenAddress: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", // USDT on Solana
      destinationTokenMinAmount: BigInt(9_500_000), // 9.5 USDT minimum
      destinationAddress: "3Kiz4oBXpR9YuPNsVfvE5XnNzgwjrM9m2CbRzyyEVkpQ", // Solana address
      minStablecoinAmount: BigInt(9_800_000), // Protocol minimum
      deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
    });

    return response;
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error("Invalid order parameters:", error.message);
    } else {
      console.error("Failed to create and send order:", error);
    }
    throw error;
  }
}
```

### Cross-Chain Order from Hyperliquid to Optimism

```typescript
import { ChainID, EVMSDK, ValidationError } from "@solsdk/xswap_sdk";

async function createHyperliquidToOptimismOrder() {
  try {
    const sdk = new EVMSDK({
      chainId: ChainID.Hyperliquid,
      privateKey: process.env.PRIVATE_KEY as `0x${string}`,
    });

    const response = await sdk.createAndSendOrder({
      sourceChainId: ChainID.Hyperliquid,
      sourceTokenAddress: "0x4300000000000000000000000000000000000003", // USDC on Hyperliquid
      sourceTokenAmount: BigInt(10_000_000), // 10 USDC (6 decimals)
      destinationChainId: ChainID.Optimism,
      destinationTokenAddress: "0x7F5c764cBc14f9669B88837ca1490cCa17c31607", // USDC on Optimism
      destinationTokenMinAmount: BigInt(9_500_000), // 9.5 USDC minimum
      destinationAddress: "0xYourOptimismAddress", // Optimism address
      minStablecoinAmount: BigInt(9_800_000), // Protocol minimum
      deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
    });

    return response;
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error("Invalid order parameters:", error.message);
    } else {
      console.error("Failed to create and send order:", error);
    }
    throw error;
  }
}
```

## Contributing

We welcome contributions from the community! Please open issues or submit pull requests to help us improve @solsdk/xswap_sdk.

## License

MIT

---

**Ready to simplify cross-chain swaps? Install @solsdk/xswap_sdk and start building today!**