@metalayer/sdk

MetaRouter SDK

A TypeScript SDK for cross-chain interoperability, providing seamless access to anything-to-anything swaps with composable routes, powered by Caldera's Metalayer.

Features

• 🔄 Cross-chain bridges
• 💰 Instant price quotes
• 🔒 Type-safe with full TypeScript support
• 🌐 Support for multiple blockchain networks
• ⚛️ React hooks for easy frontend integration

Installation

Install the npm package:

pnpm add @metalayer/sdk
# or
npm install @metalayer/sdk
# or
yarn add @metalayer/sdk

Quick Start

import { MetaRouterClient } from '@metalayer/sdk';

const router = MetaRouterClient.init({
  apiKey: 'your-api-key',
  environment: 'staging', // Use 'production' for mainnet
  defaultOptions: {
    quotePreference: 'bestReturn',
  },
});

// Get a quote
const quote = await router.quote({
  // ...quote params
});

⚠️ You must provide a valid API key to use the SDK. Requests without a valid key will fail.

Configuration

interface MetaRouterConfig {
  apiKey: string;
  environment: 'production' | 'staging';
  defaultOptions?: {
    quotePreference: 'bestReturn' | 'fastest';
  };
}

API Reference

Method Overview

• Get supported chains: await client.getSupportedChains(params) or useSupportedChains(params)
• Get token routes: await client.getTokenRoutes(params) or useTokenRoutes(params)
• Get a quote: await client.quote(params) or useQuote(params)
• Get an order: await client.getOrder(params) or useOrderPolling(params)
• Get orders: await client.getOrders(params) or useWalletOrders(address)

MetaRouterClient

Methods

• static init(config: MetaRouterConfig): MetaRouterClient
• getSupportedChains(params: SupportedChainsParams): Promise<SupportedChainsResponse>
• getTokenRoutes(params: TokenRoutesParams): Promise<TokenRoutesResponse>
• quote(params: QuotesParams): Promise<QuotesResponse>
• getOrder(params: OrderParams): Promise<OrderResponse>
• getOrders(params: OrdersParams): Promise<OrdersResponse>

React Hooks

The SDK provides React hooks for easy integration:

• useSupportedChains
• useTokenRoutes
• useQuote
• useOrderPolling
• useWalletOrders
• MetaRouterProvider (React context provider)

MetaRouterProvider

Wrap your application with the provider to enable hook usage:

import { MetaRouterProvider } from '@metalayer/sdk';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MetaRouterProvider
        config={{
          apiKey: 'your-api-key',
          environment: 'staging', // Use 'production' for mainnet
        }}
      >
        {/* Your components here */}
      </MetaRouterProvider>
    </QueryClientProvider>
  );
}

useSupportedChains

Get supported blockchain networks:

• Async: await client.getSupportedChains(params)
• React Hook: useSupportedChains(params)

import { useSupportedChains } from '@metalayer/sdk';

function Component() {
  const { data, isLoading, error } = useSupportedChains();

  if (isLoading) return <div>Loading chains...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {data?.chains.map(chain => (
        <li key={chain.id}>{chain.name}</li>
      ))}
    </ul>
  );
}

useTokenRoutes

Get available token routes:

• Async: await client.getTokenRoutes(params)
• React Hook: useTokenRoutes(params)

import { useTokenRoutes } from '@metalayer/sdk';

function Component() {
  // All available routes
  const { data: tokenRoutes, isLoading } = useTokenRoutes();

  // Available routes for specific Source chain & token
  const { data: tokenRoutesSource, isLoading: loadingSource } = useTokenRoutes({
    chainInId: 1,
    tokenInAddress: '0x0000000000000000000000000000000000000000'
  });

  // Available routes for specific Destination chain & token
  const { data: tokenRoutesDestination, isLoading: loadingDest } = useTokenRoutes({
    chainOutId: 1,
    tokenOutAddress: '0x0000000000000000000000000000000000000000'
  });
  
  if (loadingSource || loadingDest) return <div>Loading routes...</div>;

  return (
    <div>
      Available routes: {tokenRoutes?.routes.length}
      Available routes for specific source: {tokenRoutesSource?.routes.length}
      Available routes for specific destination: {tokenRoutesDestination?.routes.length}
    </div>
  );
}

Combined useSupportedChains and useTokenRoutes

Fetch supported chains and token routes, using chain and token data to display route information with icons:

import { useSupportedChains, useTokenRoutes } from '@metalayer/sdk';

function Component() {
  const { data: chainsData, isLoading: chainsLoading } = useSupportedChains();
  const { data: tokenRoutes, isLoading: routesLoading } = useTokenRoutes();

  if (chainsLoading || routesLoading) return <div>Loading...</div>;

  const getChainInfo = (chainId: number) => {
    const chain = chainsData?.chains.find(c => c.id === chainId);
    return {
      name: chain?.name || `Chain ${chainId}`,
      icon: chain?.imageUrl,
    };
  };

  const getTokenInfo = (chainId: number, address: string) => {
    const key = `${chainId}_${address}`;
    const token = tokenRoutes?.tokens[key];
    return {
      symbol: token?.symbol || 'Unknown',
      icon: token?.imageUrl,
    };
  };

  return (
    <ul>
      {tokenRoutes?.routes.slice(0, 5).map((route, index) => {
        const sourceChain = getChainInfo(route.chainInId);
        const destChain = getChainInfo(route.chainOutId);
        const sourceToken = getTokenInfo(route.chainInId, route.tokenInAddress);
        const destToken = getTokenInfo(route.chainOutId, route.tokenOutAddress);

        return (
          <li key={index} style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
            {sourceToken.icon && <img src={sourceToken.icon} alt={sourceToken.symbol} width={20} />}
            {sourceToken.symbol}
            {sourceChain.icon && <img src={sourceChain.icon} alt={sourceChain.name} width={20} />}
            on {sourceChain.name} →
            {destToken.icon && <img src={destToken.icon} alt={destToken.symbol} width={20} />}
            {destToken.symbol}
            {destChain.icon && <img src={destChain.icon} alt={destChain.name} width={20} />}
            on {destChain.name}
          </li>
        );
      })}
    </ul>
  );
}

useQuote

Get quotes for a transfer:

• Async: await client.quote(params)
• React Hook: useQuote(params)

import { useQuote } from '@metalayer/sdk';

function Component() {
  const { quote: bestQuote, isLoading } = useQuote({
    chainInId: 1,
    tokenInAddress: '0x0000000000000000000000000000000000000000',
    chainOutId: 10,
    tokenOutAddress: '0x0000000000000000000000000000000000000000',
    amount: BigInt(1000000000000000000), // 1 ETH
    senderAddress: '0xYourWalletAddress',
  });

  if (isLoading) return <div>Loading quote...</div>;

  return (
    <div>
      Best amount out: {bestQuote?.amountOut.toString()}
    </div>
  );
}

useOrderPolling

Poll for order status:

• Async: await client.getOrder(params)
• React Hook: useOrderPolling(params, intervalMs)

import { useOrderPolling } from '@metalayer/sdk';

function Component() {
  // Recommended: Poll by source transaction & source chain id
  const { data: order, isLoading } = useOrderPolling({
    sourceTransactionHash: '0xYourTxHash',
    sourceChainId: 1,
    sourceTransactionStatus: 'success',
  }, 15000); // Poll every 15 seconds

  // For Relay Quote Provider: Must pass the quote object to poll by quote ID
  // const { data: relayOrder, isLoading: relayLoading } = useOrderPolling({
  //   quote: quote,
  //   sourceTransactionStatus: 'success',
  // }, 15000);

  if (isLoading) return <div>Loading order...</div>;

  return (
    <div>
      <div>Order Status: {order?.status}</div>
      {/* <div>Relay Order Status: {relayOrder?.status}</div> */}
    </div>
  );
}

useWalletOrders

Fetch orders for a wallet:

• Async: await client.getOrders(params)
• React Hook: useWalletOrders(address)

import { useWalletOrders } from '@metalayer/sdk';

function Component() {
  const { data: orders, isLoading } = useWalletOrders('0xYourWalletAddress');

  if (isLoading) return <div>Loading orders...</div>;

  return <div>Total orders: {orders?.length}</div>;
}

Examples

See the example/ directory for full React usage examples, including quotes, token routes, bridge status, and wallet history.

License

See the LICENSE file for details.