Track Bags Payout Events

const API_BASE = "https://public-api-v2.bags.fm/api/v1";
const API_KEY = process.env.BAGS_API_KEY!;

type PayoutMethod = "xmoney" | "cashapp" | "venmo";

interface PayoutEvent {
    paymentId: string;
    payoutId: string;
    tokenMint: string;
    cashoutMethod: PayoutMethod;
    username: string;
    displayHandle: string;
    amountUsd: number;
    fiatPaidCents: string;
    usdcAmount: string;
    usdcDecimals: number;
    discountBps: number;
    timestamp: number;
    isFirstPayment: boolean;
}

interface PayoutFeedEvent extends PayoutEvent {
    token: { name: string | null; symbol: string | null; image: string | null };
}

interface FeedPage {
    events: PayoutFeedEvent[];
    hasMore: boolean;
    nextCursor: string | null;
}

async function getJson<T>(path: string, params: Record<string, string | number | boolean | undefined>): Promise<T> {
    const url = new URL(`${API_BASE}${path}`);
    for (const [key, value] of Object.entries(params)) {
        if (value !== undefined) url.searchParams.set(key, String(value));
    }
    const res = await fetch(url, { headers: { "x-api-key": API_KEY } });
    const body = await res.json();
    if (!body.success) {
        // 400 for invalid parameters, 429 when rate limited, 500 on server errors
        throw new Error(`${path} failed (${res.status}): ${body.response}`);
    }
    return body.response as T;
}

/** Newest first, paged with `before`. */
async function* feedByTime(filters: { method?: PayoutMethod | "all"; onlyFirstPayments?: boolean } = {}) {
    let before: number | undefined;
    while (true) {
        const page = await getJson<FeedPage>("/bags-payout/feed", { ...filters, sort: "time", limit: 100, before });
        yield* page.events;
        if (!page.hasMore || page.events.length === 0) return;
        before = page.events[page.events.length - 1].timestamp;
    }
}

/** Largest first, paged with `cursor`. */
async function* feedByAmount(filters: { method?: PayoutMethod | "all"; minAmountCents?: number; maxAmountCents?: number } = {}) {
    let cursor: string | undefined;
    while (true) {
        const page = await getJson<FeedPage>("/bags-payout/feed", { ...filters, sort: "amount", limit: 100, cursor });
        yield* page.events;
        if (!page.hasMore || !page.nextCursor) return;
        cursor = page.nextCursor;
    }
}

// The ten largest X Money payments so far
let rank = 0;
for await (const event of feedByAmount()) {
    console.log(`${++rank}. $${event.amountUsd.toFixed(2)} to ${event.displayHandle} from $${event.token.symbol ?? event.tokenMint}`);
    if (rank === 10) break;
}

const seen = new Set<string>();

async function poll(post: (event: PayoutFeedEvent) => Promise<void>) {
    const page = await getJson<FeedPage>("/bags-payout/feed", { limit: 100 });
    // Oldest of the new ones first, so posts come out in order
    for (const event of [...page.events].reverse()) {
        if (seen.has(event.paymentId)) continue;
        seen.add(event.paymentId);
        await post(event);
    }
}

async function main() {
    // Mark what is already in the feed as seen so the bot does not replay history on start
    const first = await getJson<FeedPage>("/bags-payout/feed", { limit: 100 });
    for (const event of first.events) seen.add(event.paymentId);

    while (true) {
        try {
            await poll(async (event) => {
                const tag = event.isFirstPayment ? " (first payment)" : "";
                console.log(`${event.displayHandle} was paid $${event.amountUsd.toFixed(2)} from $${event.token.symbol ?? "?"}${tag}`);
            });
        } catch (error) {
            console.error(error); // back off on 429 and retry
        }
        await new Promise((resolve) => setTimeout(resolve, 30_000));
    }
}

main();

import { createChart, createSeriesMarkers, CandlestickSeries, type SeriesMarker, type UTCTimestamp } from "lightweight-charts";

interface TokenEventsPage {
    events: PayoutEvent[];
    hasMore: boolean;
}

/** Every event in [from, to], oldest first. Follows `hasMore` past the 1000-event cap. */
async function getTokenEventsInRange(tokenMint: string, from: number, to: number, method: PayoutMethod | "all" = "xmoney"): Promise<PayoutEvent[]> {
    const events: PayoutEvent[] = [];
    const ids = new Set<string>();
    while (from <= to) {
        const page = await getJson<TokenEventsPage>("/bags-payout/token/events", { tokenMint, mode: "time", from, to, method });
        for (const event of page.events) {
            if (ids.has(event.paymentId)) continue; // `from` is inclusive, so the boundary second repeats
            ids.add(event.paymentId);
            events.push(event);
        }
        if (!page.hasMore || page.events.length === 0) break;
        const last = page.events[page.events.length - 1].timestamp;
        if (last === from) break; // more than 1000 events in one second; stop instead of looping
        from = last;
    }
    return events;
}

/** One marker per candle: payments in the same candle are summed. */
function toMarkers(events: PayoutEvent[], candleSeconds: number): SeriesMarker<UTCTimestamp>[] {
    const buckets = new Map<number, { totalUsd: number; count: number; hasFirst: boolean }>();
    for (const event of events) {
        const time = Math.floor(event.timestamp / candleSeconds) * candleSeconds;
        const bucket = buckets.get(time) ?? { totalUsd: 0, count: 0, hasFirst: false };
        bucket.totalUsd += Number(event.fiatPaidCents) / 100;
        bucket.count += 1;
        bucket.hasFirst ||= event.isFirstPayment;
        buckets.set(time, bucket);
    }
    return [...buckets.entries()]
        .sort(([a], [b]) => a - b) // markers must be in ascending time order
        .map(([time, { totalUsd, count, hasFirst }]) => ({
            time: time as UTCTimestamp,
            position: "belowBar",
            shape: hasFirst ? "circle" : "arrowUp",
            color: hasFirst ? "#f5a524" : "#22c55e",
            text: count > 1 ? `$${totalUsd.toFixed(0)} paid (${count})` : `$${totalUsd.toFixed(0)} paid`,
        }));
}

// Usage: `candles` are your own OHLC bars for the token, with `time` in unix seconds.
async function drawPayoutChart(container: HTMLElement, tokenMint: string, candles: { time: UTCTimestamp; open: number; high: number; low: number; close: number }[]) {
    const candleSeconds = 15 * 60; // must match the candle interval of `candles`
    const chart = createChart(container, { timeScale: { timeVisible: true } });
    const series = chart.addSeries(CandlestickSeries);
    series.setData(candles);

    const from = candles[0].time;
    const to = candles[candles.length - 1].time + candleSeconds - 1;
    const events = await getTokenEventsInRange(tokenMint, from, to);
    createSeriesMarkers(series, toMarkers(events, candleSeconds));
}