feat(payments): /api/payment/history per-token credit-purchase audit log

Adds /api/payment/history (free with bearer token) returning the
purchase audit trail for the requesting token: tx hash, amount, credits
added, block number, confirmation timestamp. Pairs with the existing
/api/payment/usage (spend side) so a bearer can reconcile its full
token lifecycle.

- worker/src/payments.ts: new pay:purchases:{token} ring buffer
  (cap 100), appendTokenPurchase() helper called on both confirm
  paths (explicit confirm + x402 retry), getPaymentHistory() reader.
  Backwards-compat: tokens minted before this ledger return current
  balance with empty purchases array.
- worker/src/index.ts: route handler with the same Authorization:
  Bearer pattern as /api/payment/usage.
- /api/meta and llms.txt updated.
- src/lib/api-reference-directory.ts: full per-endpoint page entry
  at /api-reference/payment-history with FAQ, code samples, related
  links to payment-usage / payment-balance / payment-confirm.

Unblocks TerminalFeed cross-site bundle, which needed this endpoint
to surface deposit history alongside spend history.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: RipperMercs

CLAUDE.md

@@ -204,6 +204,7 @@ All mounted under `https://tensorfeed.ai/api/*` via the Worker.
 - `/api/payment/confirm` (POST): Verify USDC tx on-chain, mint a bearer token
 - `/api/payment/balance`: Read remaining credits for the current bearer token
 - `/api/payment/usage`: Per-token call history (last 100 calls aggregated by endpoint). Auth required, no credit cost. Powers the human /account dashboard.
+- `/api/payment/history`: Per-token credit-purchase audit log (which on-chain txs added how many credits and when). Auth required (`Authorization: Bearer <token>`), no credit cost. Pairs with `/api/payment/usage` (spend side) to give the bearer's full token lifecycle. Backed by `pay:purchases:{token}` ring buffer (cap 100); tokens minted before this ledger existed return an empty `purchases` array but still expose `current_balance` and `token_short`.
 - `/api/alerts/subscribe`: Outage alert email signup
 - `/api/refresh?key=production[&task=history]`: Manual data refresh / history capture trigger
 

public/llms.txt

@@ -65,6 +65,7 @@ TensorFeed accepts USDC on Base as the sole payment method for premium endpoints
 - [Confirm Payment](https://tensorfeed.ai/api/payment/confirm): POST { tx_hash, nonce? } to verify a USDC tx and mint a bearer token
 - [Check Balance](https://tensorfeed.ai/api/payment/balance): GET with `Authorization: Bearer tf_live_...` to see remaining credits
 - [Token Usage History](https://tensorfeed.ai/api/payment/usage): GET with bearer token to see per-endpoint call counts and the most recent calls (last 100 entries, no credit cost). Powers the human-facing /account dashboard.
+- [Token Payment History](https://tensorfeed.ai/api/payment/history): GET with bearer token to see the credit-purchase audit log (which on-chain txs added how many credits and when, last 100 purchases, no credit cost). Pairs with /api/payment/usage to cover the full token lifecycle (purchases + spend).
 - [Premium Routing](https://tensorfeed.ai/api/premium/routing): Tier 2, 1 credit per call. Top 5 ranked models with full score breakdown, pricing, status, component-level detail. Same query params as the preview plus optional ?top_n=1-10, ?w_quality=, ?w_availability=, ?w_cost=, ?w_latency= for custom weights.
 - [Premium Pricing Series](https://tensorfeed.ai/api/premium/history/pricing/series): Tier 1, 1 credit per call. Daily input/output/blended price points for one model across a date range, with min/max/delta summary. Params: `?model=<id-or-name>&from=YYYY-MM-DD&to=YYYY-MM-DD`. Range capped at 90 days, default 30 days back.
 - [Premium Benchmark Series](https://tensorfeed.ai/api/premium/history/benchmarks/series): Tier 1, 1 credit per call. Score evolution for a single benchmark (e.g. swe_bench, mmlu_pro, gpqa_diamond, math, human_eval) on one model. Params: `?model=&benchmark=&from=&to=`. Range capped at 90 days.

src/lib/api-reference-directory.ts

@@ -576,7 +576,7 @@ const tf = new TensorFeed({ token: 'tf_live_...' });
 const usage = await tf.usage();
 console.log(\`\${usage.total_calls} calls, \${usage.total_credits_spent} credits\`);`,
     mcpTool: 'get_account_usage',
-    relatedSlugs: ['payment-balance', 'payment-info'],
+    relatedSlugs: ['payment-balance', 'payment-history', 'payment-info'],
     faqs: [
       {
         q: 'How far back does the usage history go?',
@@ -589,6 +589,69 @@ console.log(\`\${usage.total_calls} calls, \${usage.total_credits_spent} credits
     ],
   },
 
+  // ── Free with token: payment history ─────────────────────────────
+  {
+    slug: 'payment-history',
+    name: 'Token Payment History',
+    path: '/api/payment/history',
+    method: 'GET',
+    tier: 'free-with-token',
+    cost: 'Free with bearer token',
+    category: 'payment',
+    seoTitle: 'TensorFeed Payment History API: Per-Token Credit Purchase Audit Log',
+    seoDescription:
+      'TensorFeed /api/payment/history returns the bearer\'s credit-purchase audit log: which on-chain txs added how many credits and when. Free with bearer token.',
+    intro:
+      'The /api/payment/history endpoint returns your token\'s purchase audit trail: every USDC tx that funded credits on this bearer, with amount, credits added, block number, and confirmation timestamp. Pairs with /api/payment/usage (spend side) so an agent can reconcile its full token lifecycle.',
+    whenToUse:
+      'When an agent needs to audit how its credits were funded, reconcile on-chain spend against credit additions, or render a deposit history alongside spend history in an internal dashboard.',
+    params: [],
+    exampleResponse: `{
+  "ok": true,
+  "token_short": "tf_live_eb0d0155...",
+  "current_balance": 49,
+  "total_purchased_usd": 1.0,
+  "total_credits_added": 50,
+  "purchase_count": 1,
+  "purchases": [
+    {
+      "tx_hash": "0xabc...",
+      "amount_usd": 1.0,
+      "credits_added": 50,
+      "block_number": 12345678,
+      "confirmed_at": "2026-04-27T17:49:32.918Z"
+    }
+  ]
+}`,
+    pythonExample: `from tensorfeed import TensorFeed
+
+tf = TensorFeed(token="tf_live_...")
+history = tf.payment_history()
+for p in history["purchases"]:
+    print(f"+{p['credits_added']} credits via {p['tx_hash'][:12]}...")`,
+    typescriptExample: `import { TensorFeed } from 'tensorfeed';
+
+const tf = new TensorFeed({ token: 'tf_live_...' });
+const history = await tf.paymentHistory();
+console.log(\`\${history.purchase_count} purchases totaling $\${history.total_purchased_usd}\`);`,
+    mcpTool: null,
+    relatedSlugs: ['payment-usage', 'payment-balance', 'payment-confirm'],
+    faqs: [
+      {
+        q: 'How far back does the purchase history go?',
+        a: 'The ring buffer holds the last 100 purchases per token. At one purchase per token in typical agent usage, that is effectively unbounded; only an agent that repeatedly tops up the same bearer rather than minting fresh tokens would ever roll off the buffer.',
+      },
+      {
+        q: 'What about tokens minted before this ledger existed?',
+        a: 'Older tokens still authenticate cleanly and return current_balance, but the purchases array will be empty until a new top-up is recorded. The replay-protection ledger at pay:tx:{txHash} is the authoritative cross-reference if you need to audit a pre-ledger purchase.',
+      },
+      {
+        q: 'Does this cost a credit?',
+        a: 'No. /api/payment/history is free for the holder of the bearer token, same as /api/payment/balance and /api/payment/usage.',
+      },
+    ],
+  },
+
   // ── Premium: routing ─────────────────────────────────────────────
   {
     slug: 'premium-routing',

worker/src/index.ts

@@ -47,6 +47,7 @@ import {
   getRollup,
   listRollupDates,
   getTokenUsage,
+  getPaymentHistory,
   validateAndCharge,
 } from './payments';
 import { recordPollRun, checkNewsStaleness, alertStaleNews, sendDailySummary, getAlertsStatus } from './alerts';
@@ -523,6 +524,7 @@ export default {
           paymentConfirm: '/api/payment/confirm',
           paymentBalance: '/api/payment/balance',
           paymentUsage: '/api/payment/usage',
+          paymentHistory: '/api/payment/history',
         },
         admin: {
           usage: '/api/admin/usage?date=YYYY-MM-DD&key=<env>',
@@ -721,6 +723,29 @@ export default {
       return jsonResponse(result, 200, 0);
     }
 
+    // Per-token payment history. Audit log of credit purchases scoped
+    // to the requesting bearer: which on-chain txs added how many
+    // credits and when. Free, no credit cost. Backwards-compatible
+    // with tokens minted before this ledger existed (returns empty
+    // purchases array). Paired with /api/payment/usage which logs the
+    // spend side; together they cover the full token lifecycle.
+
+    if (path === '/api/payment/history') {
+      const authHeader = request.headers.get('Authorization');
+      const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+      if (!token) {
+        return jsonResponse(
+          { ok: false, error: 'token_required', message: 'Send the bearer token via Authorization: Bearer <token>' },
+          401,
+        );
+      }
+      const result = await getPaymentHistory(env, token);
+      if (!result) {
+        return jsonResponse({ ok: false, error: 'token_not_found' }, 404);
+      }
+      return jsonResponse(result, 200, 0);
+    }
+
     // === PAID PREMIUM ENDPOINT: ROUTING (Tier 2, requires credits) ===
 
     if (path === '/api/premium/routing') {

worker/src/payments.ts

@@ -387,6 +387,111 @@ export interface TokenUsageSummary {
   recent: TokenUsageEntry[];
 }
 
+// ── Per-token payment history (purchases) ───────────────────────────
+//
+// pay:purchases:{token} holds an append-only list of credit purchases
+// scoped to one bearer token. Used by /api/payment/history so an
+// agent can audit how its credits were funded (which on-chain txs
+// added how many credits and when), independent of /api/payment/usage
+// which logs how those credits were *spent*.
+//
+// Backward compat: tokens that confirmed before this field was added
+// will read an empty list. Existing pay:tx:{txHash} records remain the
+// authoritative replay-protection ledger; this is purely a per-token
+// view layered on top.
+
+interface PurchaseEntry {
+  tx_hash: string;
+  amount_usd: number;
+  credits_added: number;
+  block_number?: number;
+  confirmed_at: string;
+}
+
+interface PurchaseRecord {
+  entries: PurchaseEntry[];
+}
+
+const PURCHASES_CAP = 100;
+
+export async function appendTokenPurchase(
+  env: Env,
+  token: string,
+  purchase: PurchaseEntry,
+): Promise<void> {
+  try {
+    const existing = (await env.TENSORFEED_CACHE.get(
+      `pay:purchases:${token}`,
+      'json',
+    )) as PurchaseRecord | null;
+    const entries = existing?.entries ?? [];
+    entries.push(purchase);
+    if (entries.length > PURCHASES_CAP) {
+      entries.splice(0, entries.length - PURCHASES_CAP);
+    }
+    await env.TENSORFEED_CACHE.put(
+      `pay:purchases:${token}`,
+      JSON.stringify({ entries }),
+    );
+  } catch (e) {
+    console.error('appendTokenPurchase failed:', e);
+  }
+}
+
+export interface PaymentHistorySummary {
+  ok: true;
+  token_short: string;
+  current_balance: number;
+  total_purchased_usd: number;
+  total_credits_added: number;
+  purchase_count: number;
+  purchases: PurchaseEntry[];
+}
+
+/**
+ * Read the per-token purchase ledger. Auth-bound: caller must already
+ * have validated the bearer token. Returns null if the token is not
+ * recognized so the route handler can return 404 without leaking
+ * existence to a wrong-secret guess.
+ */
+export async function getPaymentHistory(
+  env: Env,
+  token: string,
+): Promise<PaymentHistorySummary | null> {
+  if (!token.startsWith('tf_live_')) return null;
+  const credits = (await env.TENSORFEED_CACHE.get(
+    `pay:credits:${token}`,
+    'json',
+  )) as CreditsRecord | null;
+  if (!credits) return null;
+
+  const ledger = (await env.TENSORFEED_CACHE.get(
+    `pay:purchases:${token}`,
+    'json',
+  )) as PurchaseRecord | null;
+  const entries = ledger?.entries ?? [];
+
+  let totalUsd = 0;
+  let totalCredits = 0;
+  for (const e of entries) {
+    totalUsd += e.amount_usd;
+    totalCredits += e.credits_added;
+  }
+
+  // Newest first for caller convenience.
+  const sorted = entries.slice().sort((a, b) => (a.confirmed_at < b.confirmed_at ? 1 : -1));
+
+  return {
+    ok: true,
+    token_short: token.slice(0, 16) + '...',
+    current_balance: credits.balance,
+    total_purchased_usd: Number(totalUsd.toFixed(6)),
+    total_credits_added: totalCredits,
+    purchase_count: entries.length,
+    purchases: sorted,
+  };
+}
+
 /**
  * Read the per-token usage ring buffer and aggregate it for the dashboard.
  * Returns null if the token isn't recognized.
@@ -601,6 +706,13 @@ export async function confirmPayment(
     env.TENSORFEED_CACHE.put(`pay:tx:${txHash}`, JSON.stringify(txRec)),
     nonce ? env.TENSORFEED_CACHE.delete(`pay:quote:${nonce}`) : Promise.resolve(),
     logRevenue(env, verified.amountUsd, request.headers.get('User-Agent') || 'unknown'),
+    appendTokenPurchase(env, token, {
+      tx_hash: txHash,
+      amount_usd: verified.amountUsd,
+      credits_added: credits,
+      block_number: verified.blockNumber,
+      confirmed_at: now,
+    }),
   ]);
 
   return {
@@ -836,6 +948,13 @@ export async function requirePayment(
       env.TENSORFEED_CACHE.put(`pay:credits:${token}`, JSON.stringify(tokenRecord)),
       env.TENSORFEED_CACHE.put(`pay:tx:${txHash}`, JSON.stringify(txRec)),
       logRevenue(env, verified.amountUsd, request.headers.get('User-Agent') || 'unknown'),
+      appendTokenPurchase(env, token, {
+        tx_hash: txHash,
+        amount_usd: verified.amountUsd,
+        credits_added: credits,
+        block_number: verified.blockNumber,
+        confirmed_at: now,
+      }),
     ]);
 
     return {