npm package: @kaiachain/bridge-aggregator-sdk
Description: TypeScript SDK for the Kaia Bridge Aggregator API – discover chains/tokens, get quotes, commit swaps, and build ready-to-sign transactions.
Latest version: 0.1.1

# Kaia Bridge Aggregator SDK

[![npm version](https://img.shields.io/npm/v/@kaiachain/bridge-aggregator-sdk.svg)](https://www.npmjs.com/package/@kaiachain/bridge-aggregator-sdk)
[![Node.js](https://img.shields.io/node/v/@kaiachain/bridge-aggregator-sdk.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

**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](./docs/README.md)** | Index of all guides |
| [Getting started](./docs/getting-started.md) | Install, client setup, bridge & swap flows |
| [Architecture & flows](./docs/architecture-and-flows.md) | SDK ↔ API mapping, bridge vs swap |
| [API reference](./docs/api-reference.md) | Methods and parameters |
| [Errors](./docs/errors.md) | Typed errors and handling |
| [Development](./docs/development.md) | OpenAPI pipeline, build, tests |
| [Examples](./docs/examples.md) | Runnable samples and E2E scripts |

## Install

```bash
npm install @kaiachain/bridge-aggregator-sdk
```

```bash
pnpm add @kaiachain/bridge-aggregator-sdk
```

## Quick example

```ts
import { KaiaBridgeSDK } from "@kaiachain/bridge-aggregator-sdk";

const sdk = new KaiaBridgeSDK({
  apiKey: process.env.KAIA_BRIDGE_API_KEY!,
  baseUrl: "https://bridge-aggregator-api.kaia.io",
});

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

if (result.kind === "bridge") {
  const commit = await sdk.commitQuote(result.bridge!.quote);
  const tx = sdk.getEVMTransaction(commit, 1);
  // Sign & send with your wallet (ethers, viem, MetaMask, …)
}
```

Same-chain swaps use `result.kind === "swap"` and the quote’s transaction directly — no `commitQuote`. See **[Getting started](./docs/getting-started.md)** for full walkthroughs.

## 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 |
| **Execution** | `commitQuote`, `getEVMTransaction`, `getTONTransaction` |
| **Status** | `getSwapStatus`, `pollUntilComplete` |
| **Errors** | Structured hierarchy (`RateLimitedError`, `QuoteExpiredError`, …) |

## Requirements

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

## Examples in this repo

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

## License

MIT