@sebastian.dev.55/piper-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.0 (Phase A — market read) | | Base URL | https://api.testsback.com/api/v1/partner | | Auth | x-piper-partner-key: ppk_… | | Docs | SPA /docs · /partner-public-api.md (docs-2.0) | | Agents | agent/AGENTS.md · agent/tools.json |

Install

npm install @sebastian.dev.55/piper-sdk
# monorepo:
npm install file:../piper-partner-sdk

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

Quick start (GMGN / terminals)

import { PiperClient, isDexTradable } from "@sebastian.dev.55/piper-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 from this list — do not hardcode factory/router.

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 any future trade UI:
  // 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()
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 "@sebastian.dev.55/piper-sdk";

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

Errors

import { PiperApiError } from "@sebastian.dev.55/piper-sdk";

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

Rate-limit headers are mirrored on the error when present (Retry-After, X-RateLimit-*, X-Partner-Daily-Remaining).

Agent tooling

import { PiperClient, createPiperTools } from "@sebastian.dev.55/piper-sdk";
// or: import { createPiperTools } from "@sebastian.dev.55/piper-sdk/agent";

const tools = createPiperTools(new PiperClient({ apiKey }));
// tools[i].name / .parameters / .execute(args)

Static JSON Schema catalog: agent/tools.json.

Freshness (server)

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

Not in v0.1

• Trade Kit (POST /quote, POST /build-tx) — backend next
• @sebastian.dev.55/piper-sdk/abis — Phase B
• React hooks / admin access flows

Build & test

npm run build
npm run typecheck
PIPER_PARTNER_KEY=ppk_… npm test   # smoke against live Partner API (skips if unset)

Package layout

See HOW_WE_BUILD.md for phase roadmap (A market → B ABIs → C trade).