@swapkit/api-sdk-typescript 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SwapKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @swapkit/api-sdk-typescript
+
+Type-safe TypeScript SDK for the [SwapKit API](https://docs.swapkit.dev). Auto-generated from OpenAPI specs with named domain types and full request/response typing.
+
+## Installation
+
+```bash
+npm install @swapkit/api-sdk-typescript
+# or
+bun add @swapkit/api-sdk-typescript
+```
+
+## Quick Start
+
+```typescript
+import { configureSwapKit, SwapKitService } from "@swapkit/api-sdk-typescript";
+
+// Configure once at startup
+configureSwapKit({ apiKey: "your-api-key" });
+
+// Use named service methods — fully typed
+const { data: providers } = await SwapKitService.getProviders();
+
+const { data: quote, error } = await SwapKitService.getQuote({
+  body: {
+    sellAsset: "ETH.ETH",
+    buyAsset: "BTC.BTC",
+    sellAmount: "1",
+    sourceAddress: "0x...",
+    destinationAddress: "bc1...",
+  },
+});
+
+if (error) {
+  console.error("Quote failed:", error);
+} else {
+  console.log(`Got ${quote.routes.length} routes for quote ${quote.quoteId}`);
+}
+```
+
+## Configuration
+
+### `configureSwapKit(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | **(required)** | Your SwapKit API key |
+| `baseUrl` | `string` | `https://api.swapkit.dev` | API base URL override |
+
+```typescript
+// Production (default)
+configureSwapKit({ apiKey: "sk_live_..." });
+
+// Staging
+configureSwapKit({
+  apiKey: "sk_test_...",
+  baseUrl: "https://dev-api.swapkit.dev",
+});
+```
+
+## SwapKitService
+
+All API methods are available as static methods on the `SwapKitService` class:
+
+| Method | HTTP | Endpoint |
+|--------|------|----------|
+| `getProviders()` | GET | `/providers` |
+| `getTokens({ query? })` | GET | `/tokens` |
+| `getSwapTo({ query })` | GET | `/swapTo` |
+| `getSwapFrom({ query })` | GET | `/swapFrom` |
+| `getQuote({ body })` | POST | `/v3/quote` |
+| `getSwap({ body })` | POST | `/v3/swap` |
+| `trackTransaction({ body })` | POST | `/track` |
+| `screenAddress({ body })` | POST | `/screen` |
+| `getGasPrices()` | GET | `/gas` |
+| `getGasHistory({ query? })` | GET | `/gas/history` |
+| `getCachedPrice({ body })` | POST | `/price/cached-price` |
+| `createBrokerChannel({ body })` | POST | `/chainflip/broker/channel` |
+
+### Examples
+
+```typescript
+// Get available providers
+const { data: providers } = await SwapKitService.getProviders();
+
+// Get tokens for a provider
+const { data: tokens } = await SwapKitService.getTokens({
+  query: { provider: "THORCHAIN" },
+});
+
+// Get available buy assets for a sell asset
+const { data: buyAssets } = await SwapKitService.getSwapTo({
+  query: { sellAsset: "ETH.ETH" },
+});
+
+// Get a quote
+const { data, error } = await SwapKitService.getQuote({
+  body: {
+    sellAsset: "ETH.ETH",
+    buyAsset: "BTC.BTC",
+    sellAmount: "1",
+    slippage: 3,
+    providers: ["THORCHAIN"],
+  },
+});
+
+// Execute a swap
+const { data: swap } = await SwapKitService.getSwap({
+  body: {
+    routeId: route.routeId,
+    sourceAddress: "0xabc...",
+    destinationAddress: "bc1xyz...",
+  },
+});
+
+// Track a transaction
+const { data: status } = await SwapKitService.trackTransaction({
+  body: { hash: "0xabc...", chainId: "1" },
+});
+
+// Screen an address
+const { data: screen } = await SwapKitService.screenAddress({
+  body: { addresses: ["0xabc..."], chains: ["ETH"] },
+});
+
+// Get gas prices
+const { data: gas } = await SwapKitService.getGasPrices();
+
+// Get cached token prices
+const { data: prices } = await SwapKitService.getCachedPrice({
+  body: { tokens: [{ identifier: "ETH.ETH" }], metadata: true },
+});
+```
+
+## Full Example: Quote-to-Swap Flow
+
+```typescript
+import { configureSwapKit, SwapKitService } from "@swapkit/api-sdk-typescript";
+
+configureSwapKit({ apiKey: "your-api-key" });
+
+// 1. Get a quote
+const { data: quote } = await SwapKitService.getQuote({
+  body: {
+    sellAsset: "ETH.ETH",
+    buyAsset: "BTC.BTC",
+    sellAmount: "1",
+    sourceAddress: "0xYourAddress...",
+    destinationAddress: "bc1YourBtcAddress...",
+  },
+});
+
+if (!quote) throw new Error("Quote failed");
+
+// 2. Pick the best route
+const route = quote.routes.find((r) => r.meta.tags.includes("RECOMMENDED")) ?? quote.routes[0];
+
+// 3. Execute the swap
+const { data: swap } = await SwapKitService.getSwap({
+  body: {
+    routeId: route.routeId,
+    sourceAddress: "0xYourAddress...",
+    destinationAddress: "bc1YourBtcAddress...",
+  },
+});
+
+// 4. Track the transaction
+const { data: status } = await SwapKitService.trackTransaction({
+  body: { hash: "0xBroadcastedTxHash...", chainId: "1" },
+});
+
+console.log(`Status: ${status?.status}`);
+```
+
+## Direct Function Access
+
+You can also import SDK functions directly instead of using the service class:
+
+```typescript
+import { postV3Quote, postV3Swap, postTrack } from "@swapkit/api-sdk-typescript";
+```
+
+## Development
+
+### Regenerate types
+
+```bash
+bun run extract:sdk
+LOCAL_SPECS_DIR=/tmp/swapkit-specs bun run generate:sdk
+```
+
+### Run tests
+
+```bash
+bun run test:sdk
+```
+
+### Build for publishing
+
+```bash
+bun run build:sdk
+```