Kaia Bridge Aggregator SDK

TypeScript SDK for the Kaia Bridge Aggregator API — discover chains and tokens, request quotes (including streaming), commit bridge routes, build ready-to-sign EVM and TON transactions, and track swap status through one typed client.

• ESM-only — "type": "module"; use import in Node ≥ 18 or bundlers that resolve ESM.
• OpenAPI-aligned — generated types and contract tests keep the client in sync with the HTTP API.

Documentation

| Resource | Description | |----------|-------------| | Documentation hub | Index of all guides | | Getting started | Install, client setup, bridge & swap flows | | Architecture & flows | SDK ↔ API mapping, bridge vs swap | | API reference | Methods and parameters | | Errors | Typed errors and handling | | Development | OpenAPI pipeline, build, tests | | Examples | Runnable samples and E2E scripts |

Install

npm install @kaiachain/bridge-aggregator-sdk

pnpm add @kaiachain/bridge-aggregator-sdk

Quick example — end-to-end bridge

import { KaiaBridgeSDK, type EVMWalletAdapter } from "@kaiachain/bridge-aggregator-sdk";

const sdk = new KaiaBridgeSDK({
  apiKey: process.env.KAIA_BRIDGE_API_KEY!,
  baseUrl: "https://bridge-aggregator-api.kaia.io",
  // Optional observability
  logger: console,
  telemetry: (e) => metrics.record(e),
});

// Minimal wallet adapter – wrap any signer (ethers/viem/wagmi/…)
const wallet: EVMWalletAdapter = /* see docs */;

const result = await sdk.getQuote({
  fromChainId: 1,
  toChainId: 8217,
  fromToken: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  toToken: "0xd077a400968890eacc75cdc901f0356c943e4fdb",
  amount: "56114281",
});

if (result.kind === "bridge") {
  // One call runs: commit → approve (if needed) → send → poll to completion.
  const { finalStatus } = await sdk.executeBridge(result.bridge!.quote, wallet, {
    onApprovalRequired: () => toast("Approving token…"),
    onTxSent:           ({ hash }) => toast(`Sent: ${hash}`),
    signal:             abortController.signal,
  });
  console.log(finalStatus?.status); // "completed"
}

Prefer the lower-level path (commitQuote + getEVMTransaction + your own signing) when you need to customize any step. Same-chain swaps use result.kind === "swap" and sdk.executeSwap(...) (or the tx directly) — no commit. See Getting started.

Features at a glance

| Area | What the SDK provides | |------|------------------------| | Discovery | Chains and tokens with pagination and optional source-chain filters | | Quotes | getQuote plus streamQuotes for progressive adaptor results | | Commit & tx building | commitQuote, getEVMTransaction, getTONTransaction | | End-to-end execution | executeBridge / executeSwap — commit → approve → send → poll, for every adaptor | | Wallet adapters | Minimal EVMWalletAdapter / TONWalletAdapter seam; bring any wallet library | | Status | getSwapStatus, pollUntilComplete (CCIP-aware via messageId) | | Errors | Typed hierarchy: API (RateLimitedError, QuoteExpiredError, …) plus execution (ApprovalFailedError, WalletRejectedError, FeeFetchFailedError, ChainMismatchError, …) | | Observability | Optional Logger and TelemetryHook in KaiaBridgeSDKConfig | | Cancellation | AbortSignal threaded through executeBridge, approvals, gas estimation, and polling |

Stability

Every public export is tagged in src/index.ts:

• @stable — semver-covered. Breaking changes only on a major bump.
• @experimental — usable today, but the shape may move in a minor. Currently only ABI constants (CCIP_ROUTER_ABI, CCIP_MESSAGE_TOPICS, RHINOFI_BRIDGE_ABI, ERC20_ABI) and the ccipRouterVersion option on executeBridge.
• @internal — implementation details not re-exported from the package root. Importing from deep paths (e.g. @kaiachain/bridge-aggregator-sdk/dist/abort.js) is unsupported and may break between minor releases.

The "core surface" you can rely on indefinitely: KaiaBridgeSDK, executeBridge / executeSwap, EVMWalletAdapter / TONWalletAdapter, the typed error classes, Logger and TelemetryHook, and every type from src/types.ts.

Requirements

Node.js ≥ 18 — relies on native fetch and ReadableStream.

Examples in this repo

Runnable scripts live under examples/: cd examples && npm install, set KAIA_BRIDGE_API_KEY, then node <script>.mjs. Details: examples/README.md and docs/examples.md.

License

MIT