@parabolicfamily/mcp 0.2.1 → 0.2.2

package/src/venue-history.ts

@@ -0,0 +1,69 @@
+import { getAddress, isAddress } from "viem";
+import type { Fetch } from "./restapi.js";
+import { parseVenueRefInput } from "./venues.js";
+
+/**
+ * `parabolic.venue_history` (docs/52 §5 "API and MCP", P-F): another launchpad's coin as the Parabolic site reads it
+ * from the chain's logs, through `GET /api/v1/coins?view=venue-history|venue-holders|venue-claimable` and a wallet's
+ * positions through `view=venue-position`. Read-only: nothing here builds or sends a transaction, and nothing here is
+ * read from a chain by this server, so every figure is the site's, in the coin's own quote, with how far back it reaches.
+ *
+ * The site answers 404 for all four while its history of other launchpads' coins is closed (`VENUE_HISTORY_OPEN`), and
+ * this says so rather than an empty answer.
+ */
+export type VenueHistoryPart = "chart" | "holders" | "position" | "claimable";
+export const VENUE_HISTORY_PARTS: readonly VenueHistoryPart[] = ["chart", "holders", "position", "claimable"];
+const INTERVALS = [15, 60, 300, 900, 3600] as const;
+
+type Coverage = { from?: number; to?: number; launch: number; complete: boolean; fromTime?: number; toTime?: number; fills: number; transfers: number; cut: boolean };
+
+export async function venueHistory(apiUrl: string | undefined, chainId: number, args: { coin?: string; part: VenueHistoryPart; tf?: number; limit?: number; wallet?: string }, fetchImpl: Fetch = globalThis.fetch): Promise<Record<string, unknown>> {
+  if (!apiUrl) throw new Error("PARABOLIC_API_URL is empty, so there is no Parabolic site to ask. A venue coin's history is read from the site's /api/v1/coins views.");
+  const base = apiUrl.replace(/\/+$/, "");
+  const qs = new URLSearchParams({ chain: String(chainId) });
+  if (args.part === "position") {
+    if (typeof args.wallet !== "string" || !isAddress(args.wallet, { strict: false })) throw new Error(`wallet must be a 0x wallet address, got ${JSON.stringify(args.wallet)}`);
+    qs.set("view", "venue-position");
+    qs.set("wallet", getAddress(args.wallet));
+  } else {
+    const ref = parseVenueRefInput(String(args.coin ?? ""));
+    if (!ref) throw new Error("coin must be the site's reference of a coin made on another launchpad: `rhc:pons:0x…` (or `pons:0x…` on this server's chain).");
+    qs.set("view", args.part === "chart" ? "venue-history" : args.part === "holders" ? "venue-holders" : "venue-claimable");
+    qs.set("venue", ref.venue);
+    qs.set("coin", ref.address);
+    if (args.part === "chart") {
+      const tf = args.tf ?? 3600;
+      if (!(INTERVALS as readonly number[]).includes(tf)) throw new Error("tf must be one of 15, 60, 300, 900 or 3600 seconds.");
+      qs.set("tf", String(tf));
+      qs.set("limit", String(Math.min(500, Math.max(1, args.limit ?? 50))));
+    }
+    if (args.part === "holders") qs.set("limit", String(Math.min(1000, Math.max(1, args.limit ?? 50))));
+  }
+  const url = `${base}/coins?${qs}`;
+  const res = await fetchImpl(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  if (res.status === 404) throw new Error(`The site answered 404 for GET ${url}: ${String(body.error ?? "no such coin, or the history of other launchpads' coins is not open there")}.`);
+  if (!res.ok) throw new Error(`GET ${url} answered ${res.status}${body.error ? `: ${String(body.error)}` : ""}`);
+  const source = `Parabolic site: GET ${url}`;
+  const coverage = body.coverage as Coverage | undefined;
+  const reach = coverage ? (coverage.complete ? "Every fill and transfer since the coin's launch was read." : `Read back to block ${coverage.from ?? "?"} so far, not yet to the launch (block ${coverage.launch}); the site reads further on each ask.`) : undefined;
+  if (args.part === "chart") {
+    const candles = (body.candles as number[][] | undefined) ?? [];
+    return {
+      coin: body.coin, venue: body.venue, chain: body.chain, unit: body.unit, tf: body.tf, fills: body.fills, complete: body.complete, coverage,
+      candles: candles.slice(-200).map((c) => ({ t: c[0], open: c[1], high: c[2], low: c[3], close: c[4], volume: c[5], trades: c[6] })),
+      trades: body.trades, source,
+      notes: [reach, "Prices and volumes are in the coin's own quote (`unit`), from each trade's own amounts; nothing here prices a trade. Venue figures never count toward Parabolic's totals."].filter(Boolean),
+    };
+  }
+  if (args.part === "holders") {
+    return {
+      coin: body.coin, venue: body.venue, chain: body.chain, count: body.count, complete: body.complete, supply: body.supply, confirmedAt: body.confirmedAt, facts: body.facts, holders: body.holders, coverage, source,
+      notes: [reach, "Balances are each address's transfers folded since launch; the largest are confirmed with balanceOf at the chain's head (`confirmed`). `role` names the coin's own contracts (its curve, its pool), never counted as wallets."].filter(Boolean),
+    };
+  }
+  if (args.part === "claimable") {
+    return { ...body, source, notes: ["The fee recipient's whole balance on the launchpad's own escrow (every coin of theirs there), read-only: it is claimed on the launchpad, never through Parabolic."] };
+  }
+  return { ...body, source, notes: ["Positions in the launchpads the site indexes itself: balances across their listed coins, trades routed through Parabolic's router, and fills from a coin's history where it reaches the launch. A coin outside the listed set and never routed is not found here."] };
+}

package/src/venues.ts

@@ -91,3 +91,46 @@ export function venueSubgraphsFrom(env: Record<string, string | undefined>, chai
   }
   return out;
 }
+
+// ---- reading another launchpad's coin through the Parabolic site (docs/52 P-D) ----------------------------------
+
+/**
+ * A coin made on another launchpad, as the site writes its reference: `<chain>:<venue>:0x…` (`rhc:pons:0x…`,
+ * `arc:solonpad:0x…`), or `<venue>:0x…` on this server's chain. Undefined for anything else, so a plain address or a
+ * Parabolic ref (`rhc:0x…`) keeps the path it has always taken. The venue is any lowercase word the site might know
+ * (it knows more launchpads than this package routes); the site answers a 400 for one it does not read there.
+ */
+export type VenueRefInput = { chainPart?: string; venue: string; address: Address };
+export function parseVenueRefInput(input: string): VenueRefInput | undefined {
+  const parts = String(input ?? "").trim().split(":");
+  if (parts.length < 2 || parts.length > 3) return undefined;
+  const address = parts[parts.length - 1];
+  const venue = parts[parts.length - 2].toLowerCase();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(address) || !/^[a-z]{2,24}$/.test(venue) || venue === "parabolic") return undefined;
+  // `rhc:0x…` is a chain prefix, not a venue: a two-part ref whose first part names a chain is Parabolic's.
+  if (parts.length === 2 && ["arc", "rhc", "base", "eth", "bnb", "sol", "arct", "anvil"].includes(venue)) return undefined;
+  return { ...(parts.length === 3 ? { chainPart: parts[0].toLowerCase() } : {}), venue, address: address as Address };
+}
+
+/** The coin as the site's public API answers it (web/lib/api/coins.ts `serializeCoin`), the fields this package reads. */
+export type SiteVenueCoin = {
+  chain?: string; venue?: string; address: string; curve?: string | null; name: string; ticker: string; creator: string | null; logo?: string | null; description?: string | null;
+  pair: string; pairToken?: string | null; quoteDecimals?: number | null; quoteDollar?: boolean | null;
+  status: "climbing" | "graduated"; price: number; marketCap: number; raised: number; threshold: number; progressPct: number;
+  holders?: number | null; volume24h?: number | null; change24h?: number | null; tradeCount?: number | null;
+  createdAt?: number | null; lastTradeAt?: number | null; graduatedAt?: number | null; poolId?: string | null; url?: string;
+};
+
+/**
+ * One venue coin from the site (GET <api>/coins/{address}?chain=<key>&venue=<id>), which reads the launchpad's index or
+ * subgraph and, for a coin neither holds, the launchpad's own factory at the head. Undefined on a 404 (no such coin on
+ * that launchpad); any other failure throws a sentence naming the site's answer, never the URL's query.
+ */
+export async function fetchSiteVenueCoin(apiUrl: string, chainKey: string, venue: string, address: Address, fetchImpl: typeof fetch = fetch): Promise<SiteVenueCoin | undefined> {
+  const base = apiUrl.replace(/\/+$/, "");
+  const res = await fetchImpl(`${base}/coins/${address}?chain=${encodeURIComponent(chainKey)}&venue=${encodeURIComponent(venue)}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+  if (res.status === 404) return undefined;
+  const body = (await res.json().catch(() => ({}))) as { coin?: SiteVenueCoin; error?: string };
+  if (!res.ok || !body.coin) throw new Error(`The Parabolic site could not read that coin (HTTP ${res.status}${body.error ? `: ${body.error}` : ""}).`);
+  return body.coin;
+}