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.

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

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/

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

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

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

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

ExecutionClient

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

StreamingClient

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:

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 file for details.