@piper-partner/sdk — Piper Partner SDK

TypeScript ESM client for the Piper Partner Market API. Built for terminals (e.g. GMGN) and AI agents.

| | | |--|--| | Version | 0.1.2 (market read + crossSwapRouter on chains) | | Base URL | https://api.testsback.com/api/v1/partner | | Auth | x-piper-partner-key: piper_… / ppk_… | | Docs | SPA /docs · /partner-public-api.md (docs-2.2) | | Agents | agent/AGENTS.md · agent/tools.json | | Trade | Separate package @piper-partner/trade (quote / unsigned build) |

Install

npm install @piper-partner/sdk
# with trade + webhooks:
npm install @piper-partner/sdk @piper-partner/trade @piper-partner/events

Zero runtime dependencies. Requires Node ≥ 18 (native fetch).

Quick start (GMGN / terminals)

import { PiperClient, isDexTradable, isInternalVenue } from "@piper-partner/sdk";

const piper = new PiperClient({
  apiKey: process.env.PIPER_PARTNER_KEY!,
  // baseUrl: "https://api.testsback.com/api/v1/partner",
});

await piper.health();

const chains = await piper.chains.list();
// Prefer chainId / factory / router / crossSwapRouter from this list — never hardcode.

const { items, nextCursor } = await piper.tokens.list({ chainId: 9009, limit: 50 });

for (const item of items) {
  const detail = await piper.tokens.get(item.chainId, item.address);
  const trades = await piper.market.trades(item.chainId, item.address, { limit: 50 });
  const ohlcv = await piper.market.ohlcv(item.chainId, item.address, {
    interval: "1m",
    limit: 100,
  });

  console.log(detail.symbol, detail.tip.spotNative, detail.lifecycle, trades.trades.length, ohlcv.candles.length);

  // Gate trade UI:
  // isInternalVenue(detail.lifecycle) → Piper routers (codes 1–3)
  // isDexTradable(detail.lifecycle) → EXTERNAL_LIVE only
}

// Optional live creates (SSE, scope: stream)
const ac = new AbortController();
for await (const batch of piper.stream.tokenCreates({ intervalMs: 5000, signal: ac.signal })) {
  if (batch.items.length) console.log("new", batch.items.map((t) => t.symbol));
}

API surface

piper.health()
piper.chains.list()  // includes crossSwapRouter: string | null
piper.tokens.list({ chainId?, cursor?, limit? })
piper.tokens.get(chainId, address)
piper.market.trades(chainId, address, { limit? })
piper.market.ohlcv(chainId, address, { interval?, limit? })
piper.stream.tokenCreates({ since?, intervalMs?, signal? })  // AsyncGenerator

Lifecycle helpers

import { isDexTradable, isInternalVenue, isPaused, LIFECYCLE } from "@piper-partner/sdk";

| Code | Label | Rule | | ---: | --- | --- | | 1 | INTERNAL_LIVE | Piper venue | | 2 | CURVE_LIVE | Bonding curve | | 3 | CURVE_CROSSED | Stay-on-Piper (peer transfers locked) | | 4 | EXTERNAL_LIVE | Graduated DEX | | 5 | PAUSED | Do not trade |

For quotes / unsigned txs use @piper-partner/trade + assertPiperTradable.

Errors

import { PiperApiError } from "@piper-partner/sdk";

try {
  await piper.tokens.get(9009, "0x…");
} catch (e) {
  if (e instanceof PiperApiError) {
    console.error(e.code, e.status, e.requestId, e.retryAfter);
  }
}

Agent tooling

import { PiperClient, createPiperTools } from "@piper-partner/sdk";

const tools = createPiperTools(new PiperClient({ apiKey }));

Static JSON Schema catalog: agent/tools.json.

Freshness (server)

• Tip / trades ≈ 1–3s (Redis)
• OHLCV ≈ 3–8s
• Registry lifecycle ≈ 45s

Related packages

| Package | Status | | --- | --- | | @piper-partner/trade | Live — quote / build / CrossSwap / agent tools | | @piper-partner/events | Live — webhook HMAC | | @piper-partner/trade-kit | Deprecated — use @piper-partner/trade |

Build & test

npm run build
npm run typecheck
PIPER_PARTNER_KEY=piper_… npm test

Package layout

See HOW_WE_BUILD.md.