npm package: @metalayer/sdk
Description: TypeScript SDK for cross-chain interoperability powered by Caldera's Metalayer
Author: Constellation Labs
Latest version: 1.0.7

# Metalayer SDK

A TypeScript SDK for cross-chain interoperability, providing seamless access to anything-to-anything swaps with composable routes, powered by Caldera's Metalayer and [MetaRouter API](https://docs.caldera.xyz/reference/metarouter).

## Features

- 🔄 Cross-chain swaps and bridges
- 💰 Real-time price quotes and gas estimates
- 📊 WebSocket streaming for prices and transaction status
- 🔒 Type-safe with full TypeScript support
- 🛠 Middleware support for custom request/response handling
- 🌐 Support for multiple blockchain networks

## Installation

This SDK relies on packages released on a custom registry, we need to add the custom registry to this project
```bash
pnpm config set @buf:registry https://buf.build/gen/npm/v1/ --location=project
# or if you're into npm
npm config set @buf:registry https://buf.build/gen/npm/v1/ --location=project
# or even yarn if you're into that (not supported for yarn versions greater than 1.10.0 and lower than v2)
yarn config set npmScopes.buf.npmRegistryServer https://buf.build/gen/npm/v1/
```

```bash
pnpm add @metalayer/sdk
# or if you're into npm
npm install @metalayer/sdk
# or even yarn if you're into that
yarn add @metalayer/sdk
```

## Quick Start

```typescript
import { MetalayerClient } from '@metalayer/sdk';

// Initialize the SDK
const router = MetalayerClient.init({
  apiKey: 'your-api-key',
  environment: 'production',
  defaultOptions: {
    quotePreference: 'bestReturn'
  },
});

// Get a quote
const quote = await router.quote({
  source: {
    chain: 1, // Ethereum
    token: '0x...',
    amount: '1000000000000000000', // 1 ETH
  },
  destination: {
    chain: 56, // BSC
    token: '0x...',
  },
});

// Execute a swap
const result = await router.swap({
  quoteId: quote.id,
  userAddress: '0x...',
});

// Stream price updates
const subscription = router.streams.prices([
  {
    baseToken: '0x...',
    quoteToken: '0x...',
    chain: 1,
  },
]).subscribe({
  next: (update) => console.log('Price update:', update),
  error: (error) => console.error('Stream error:', error),
  complete: () => console.log('Stream completed'),
});
```

## API Reference

### MetalayerConfig

The main class for interacting with the SDK.

#### Configuration

```typescript
interface MetalayerConfig {
  apiKey: string;
  environment: 'production' | 'staging';
  defaultOptions?: {
    quotePreference: 'bestReturn'
  };
}
```

#### Methods

- `static init(config: Partial<MetalayerConfig>): MetalayerClient`
- `swap(params: ExecuteParams): Promise<ExecutionResult>`
- `bridge(params: ExecuteParams): Promise<ExecutionResult>`
- `quote(params: QuoteParams): Promise<RouteQuote>`

### Clients

The SDK provides three specialized clients for different functionalities:

#### RoutingClient

```typescript
router.routes.getQuote(params: QuoteParams): Promise<RouteQuote>
router.routes.analyzeRoute(routeId: string): Promise<RouteAnalysis>
router.routes.estimateGas(params: QuoteParams | Route): Promise<GasEstimate>
```

#### ExecutionClient

```typescript
router.execution.execute(params: ExecuteParams): Promise<ExecutionResult>
router.execution.getStatus(txHash: string): Promise<TransactionStatus>
router.execution.checkApproval(params: ApprovalCheckParams): Promise<ApprovalInfo>
```

#### StreamingClient

```typescript
router.streams.prices(pairs: PairOptions[]): Observable<Update<PairResponse>>
router.streams.transactions(txHash: string | string[]): Observable<Update<TransactionStatus>>
router.streams.streamEvents<T>(params: StreamParams<T>): Observable<Update<T>>
```

## Error Handling

The SDK uses typed errors for better error handling:

```typescript
try {
  const quote = await router.quote({...});
} catch (error) {
  if (error instanceof QuoteError) {
    console.error('Quote error:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  } else {
    console.error('Unknown error:', error);
  }
}
```

## License

See the [LICENSE](LICENSE) file for details.