@kupogg/sdk

Official TypeScript SDK for the Kupo trading API. Type-safe wrappers around every /v1/* endpoint with built-in retries, rate-limit handling and idiomatic async patterns.

Zero runtime dependencies. Works in Node 18+, Bun, Deno, the browser, and edge runtimes.

Install

pnpm add @kupogg/sdk
# or: npm install @kupogg/sdk
# or: bun add @kupogg/sdk

Quickstart

import { Kupo } from "@kupogg/sdk";

const kupo = new Kupo({ apiKey: process.env.KUPO_API_KEY! });

// 1) sanity check — verify the key + load your account
const me = await kupo.me();
console.log("Cashback tier:", me.cashback?.tierName);
console.log("Total staked:", me.staking.totalStaked);

// 2) get a route preview before trading
const quote = await kupo.quote({
  tokenAddress: "0xb2ece11a988a54a79675d4b827fc9ac419fb4ba3",
  amountEth: "0.01",
});
console.log("Spot price:", quote.priceUsd);
console.log("Safety gates pass:", quote.gates.minTvl.passes);

// 3) execute a trade
const swap = await kupo.swap({
  tokenAddress: "0xb2ece11a988a54a79675d4b827fc9ac419fb4ba3",
  fromAddress: me.wallets[0].address,
  amountEth: "0.01",
  slippageBps: 100, // 1%
});
console.log("Tx hash:", swap.hash);

Authentication

API keys ship in the Authorization: Bearer kupo_live_… header. Get a key at kupo.gg/developer or via the /api command in @kupo_ggbot.

The SDK enforces the format at construction:

new Kupo({ apiKey: "invalid" }); // throws

Error handling

Every method throws KupoApiError on non-2xx. The error carries the HTTP status, the structured { error, code } body Kupo returns, and the original Response.

import { Kupo, KupoApiError } from "@kupogg/sdk";

try {
  await kupo.swap({ ... });
} catch (err) {
  if (err instanceof KupoApiError) {
    if (err.code === "buys-paused") {
      console.log("Trading is paused for maintenance.");
    } else if (err.code === "pool-tvl-too-low") {
      console.log("Liquidity is too low — refusing the trade.");
    } else if (err.status === 429) {
      console.log("Rate limited. Retry-After:", err.response.headers.get("Retry-After"));
    } else {
      throw err;
    }
  }
}

The SDK already retries on 429 (honouring Retry-After) and transient 5xx with exponential backoff. Set maxRetries: 0 to disable.

Endpoints

| SDK method | HTTP route | |---|---| | kupo.me() | GET /v1/me | | kupo.staking() | GET /v1/staking | | kupo.token(addr, opts) | GET /v1/tokens/:address | | kupo.balances(wallet) | GET /v1/balances/:wallet | | kupo.ethPrice() | GET /v1/eth-price | | kupo.quote(opts) | GET /v1/quote | | kupo.swap(opts) | POST /v1/swap | | kupo.sell(opts) | POST /v1/sell | | kupo.launches(opts) | GET /v1/launches | | kupo.trending(chain, period) | GET /v1/trending/:chain/:period | | kupo.listOrders(opts) | GET /v1/orders | | kupo.placeOrder(body) | POST /v1/orders | | kupo.cancelOrder(id) | DELETE /v1/orders/:id |

Why route through Kupo

• Same fee router as the web + bot. Routes via the deepest pool across Uniswap V4 / V3 / V2 + Aerodrome.
• Cashback + staking discount stack. Volume through your API key counts toward your cashback tier. Stake $KUPO for up to 40% off the platform fee — both apply on every trade.
• Built-in safety gates. Min-TVL ($500), max-trade-fraction (30%), mcap-vs-TVL ratio (200×), and an approval-propagation guard all run server-side. A bad pool can't fill your trade.
• No wallet infra. Uses your existing Kupo custodial wallets — same identity as the bot.

Rate limits

Per-key token bucket. Defaults:

| Tier | req/min | Unlock | |---|---|---| | Free | 60 | Default | | Pro | 180 | Gold staking (10M $KUPO) | | Platinum | 300 | Platinum staking (100M $KUPO) | | Diamond | 600 | Diamond staking (500M $KUPO) |

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. 429 includes Retry-After.

Custom fetch / runtime

The SDK uses globalThis.fetch by default. To inject a polyfill or wrap with telemetry:

import { Kupo } from "@kupogg/sdk";
import fetch from "node-fetch";

const kupo = new Kupo({
  apiKey: process.env.KUPO_API_KEY!,
  fetch: fetch as unknown as typeof globalThis.fetch,
  timeoutMs: 60_000,
  userAgent: "my-sniper-bot/1.2.0",
});

License

MIT