@wopr-network/platform-core 1.48.0 → 1.49.1

package/src/billing/crypto/key-server-webhook.ts

@@ -1,17 +1,23 @@
 /**
- * Key Server webhook handler — processes payment confirmations from the
+ * Key Server webhook handler — processes payment events from the
  * centralized crypto key server.
  *
+ * Called on EVERY status update (not just terminal):
+ *   - "partial" / "Processing" → update progress, no credit
+ *   - "confirmed" / "Settled" → update progress + credit ledger
+ *   - "expired" / "failed" → update progress, no credit
+ *
  * Payload shape (from watcher-service.ts):
  * {
  *   chargeId: "btc:bc1q...",
  *   chain: "bitcoin",
  *   address: "bc1q...",
- *   amountUsdCents: 5000,
+ *   amountReceivedCents: 5000,
  *   status: "confirmed",
  *   txHash: "abc123...",
  *   amountReceived: "50000 sats",
- *   confirmations: 6
+ *   confirmations: 6,
+ *   confirmationsRequired: 6
  * }
  *
  * Replaces handleCryptoWebhook() for products using the key server.
@@ -20,16 +26,20 @@ import { Credit } from "../../credits/credit.js";
 import type { ILedger } from "../../credits/ledger.js";
 import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
 import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { CryptoChargeStatus } from "./types.js";
 
 export interface KeyServerWebhookPayload {
   chargeId: string;
   chain: string;
   address: string;
-  amountUsdCents: number;
+  /** @deprecated Use amountReceivedCents instead. Kept for one release cycle. */
+  amountUsdCents?: number;
+  amountReceivedCents?: number;
   status: string;
   txHash?: string;
   amountReceived?: string;
   confirmations?: number;
+  confirmationsRequired?: number;
 }
 
 export interface KeyServerWebhookDeps {
@@ -45,13 +55,49 @@ export interface KeyServerWebhookResult {
   tenant?: string;
   creditedCents?: number;
   reactivatedBots?: string[];
+  status?: CryptoChargeStatus;
+  confirmations?: number;
+  confirmationsRequired?: number;
+}
+
+/**
+ * Map legacy/watcher status strings to canonical CryptoChargeStatus.
+ * Accepts both old BTCPay-style ("Settled", "Processing") and new canonical ("confirmed", "partial").
+ */
+export function normalizeStatus(raw: string): CryptoChargeStatus {
+  switch (raw) {
+    case "confirmed":
+    case "Settled":
+    case "InvoiceSettled":
+      return "confirmed";
+    case "partial":
+    case "Processing":
+    case "InvoiceProcessing":
+    case "InvoiceReceivedPayment":
+      return "partial";
+    case "expired":
+    case "Expired":
+    case "InvoiceExpired":
+      return "expired";
+    case "failed":
+    case "Invalid":
+    case "InvoiceInvalid":
+      return "failed";
+    case "pending":
+    case "New":
+    case "InvoiceCreated":
+      return "pending";
+    default:
+      return "pending";
+  }
 }
 
 /**
- * Process a payment confirmation from the crypto key server.
+ * Process a payment webhook from the crypto key server.
  *
- * Credits the ledger when status is "confirmed".
- * Idempotency: ledger referenceId + replay guard (same pattern as Stripe handler).
+ * Idempotency: deduplicate by chargeId + status + confirmations so that
+ * multiple progress updates (0→1→2→...→6 confirmations) each get through,
+ * but exact duplicates are rejected.
  */
 export async function handleKeyServerWebhook(
   deps: KeyServerWebhookDeps,
@@ -59,8 +105,15 @@ export async function handleKeyServerWebhook(
 ): Promise<KeyServerWebhookResult> {
   const { chargeStore, creditLedger } = deps;
 
-  // Replay guard: deduplicate by chargeId
-  const dedupeKey = `ks:${payload.chargeId}`;
+  const status = normalizeStatus(payload.status);
+  const confirmations = payload.confirmations ?? 0;
+  const confirmationsRequired = payload.confirmationsRequired ?? 1;
+  // Support deprecated amountUsdCents field as fallback
+  const amountReceivedCents = payload.amountReceivedCents ?? payload.amountUsdCents ?? 0;
+
+  // Replay guard: deduplicate by chargeId + status + confirmations
+  // This allows multiple progress updates for the same charge
+  const dedupeKey = `ks:${payload.chargeId}:${status}:${confirmations}`;
   if (await deps.replayGuard.isDuplicate(dedupeKey, "crypto")) {
     return { handled: true, duplicate: true };
   }
@@ -71,15 +124,36 @@ export async function handleKeyServerWebhook(
     return { handled: false };
   }
 
-  if (payload.status === "confirmed") {
-    // Only settle when payment is confirmed
-    await chargeStore.updateStatus(payload.chargeId, "Settled", charge.token ?? undefined, payload.amountReceived);
+  // Always update progress on every webhook
+  await chargeStore.updateProgress(payload.chargeId, {
+    status,
+    amountReceivedCents,
+    confirmations,
+    confirmationsRequired,
+    txHash: payload.txHash,
+  });
 
+  // Also call deprecated updateStatus for backward compat with downstream consumers
+  const legacyStatusMap: Record<CryptoChargeStatus, string> = {
+    pending: "New",
+    partial: "Processing",
+    confirmed: "Settled",
+    expired: "Expired",
+    failed: "Invalid",
+  };
+  await chargeStore.updateStatus(
+    payload.chargeId,
+    legacyStatusMap[status] as "Settled",
+    charge.token ?? undefined,
+    payload.amountReceived,
+  );
+
+  if (status === "confirmed") {
     // Idempotency: check ledger referenceId (atomic, same as BTCPay handler)
     const creditRef = `crypto:${payload.chargeId}`;
     if (await creditLedger.hasReferenceId(creditRef)) {
       await deps.replayGuard.markSeen(dedupeKey, "crypto");
-      return { handled: true, duplicate: true, tenant: charge.tenantId };
+      return { handled: true, duplicate: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
     }
 
     // Credit the original USD amount requested.
@@ -104,16 +178,13 @@ export async function handleKeyServerWebhook(
       tenant: charge.tenantId,
       creditedCents: charge.amountUsdCents,
       reactivatedBots,
+      status,
+      confirmations,
+      confirmationsRequired,
     };
   }
 
-  // Non-confirmed status — update status but don't settle or credit
-  await chargeStore.updateStatus(
-    payload.chargeId,
-    payload.status as "Processing",
-    charge.token ?? undefined,
-    payload.amountReceived,
-  );
+  // Non-confirmed status — progress already updated above, no credit
   await deps.replayGuard.markSeen(dedupeKey, "crypto");
-  return { handled: true, tenant: charge.tenantId };
+  return { handled: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
 }

package/src/billing/crypto/key-server.ts

@@ -16,6 +16,7 @@ import type { ICryptoChargeRepository } from "./charge-store.js";
 import { deriveDepositAddress } from "./evm/address-gen.js";
 import { centsToNative } from "./oracle/convert.js";
 import type { IPriceOracle } from "./oracle/types.js";
+import { AssetNotSupportedError } from "./oracle/types.js";
 import type { IPaymentMethodStore } from "./payment-method-store.js";
 
 export interface KeyServerDeps {
@@ -157,13 +158,22 @@ export function createKeyServerApp(deps: KeyServerDeps): Hono {
     // Compute expected crypto amount in native base units.
     // Price is locked NOW — this is what the user must send.
     let expectedAmount: bigint;
-    if (method.oracleAddress) {
-      // Volatile asset (BTC, ETH, DOGE) — oracle-priced
-      const { priceCents } = await deps.oracle.getPrice(token);
-      expectedAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
-    } else {
-      // Stablecoin (1:1 USD) — e.g. $50 USDC = 50_000_000 base units (6 decimals)
-      expectedAmount = (BigInt(amountUsdCents) * 10n ** BigInt(method.decimals)) / 100n;
+    const feedAddress = method.oracleAddress ? (method.oracleAddress as `0x${string}`) : undefined;
+    try {
+      // Try oracle pricing (Chainlink for BTC/ETH, CoinGecko for DOGE/LTC).
+      // feedAddress is a hint for Chainlink — undefined is fine, CompositeOracle
+      // falls through to CoinGecko or built-in feed maps.
+      const { priceMicros } = await deps.oracle.getPrice(token, feedAddress);
+      expectedAmount = centsToNative(amountUsdCents, priceMicros, method.decimals);
+    } catch (err) {
+      if (err instanceof AssetNotSupportedError) {
+        // No oracle knows this token (e.g. USDC, DAI) — stablecoin 1:1 USD.
+        expectedAmount = (BigInt(amountUsdCents) * 10n ** BigInt(method.decimals)) / 100n;
+      } else {
+        // Transient oracle failure (network, rate limit, stale feed).
+        // Reject the charge — silently pricing BTC at $1 would be catastrophic.
+        return c.json({ error: `Price oracle unavailable for ${token}: ${(err as Error).message}` }, 503);
+      }
     }
 
     const referenceId = `${token.toLowerCase()}:${address.toLowerCase()}`;

package/src/billing/crypto/oracle/__tests__/chainlink.test.ts

@@ -28,7 +28,7 @@ describe("ChainlinkOracle", () => {
 
     const result = await oracle.getPrice("ETH");
 
-    expect(result.priceCents).toBe(350_000); // $3,500.00
+    expect(result.priceMicros).toBe(3_500_000_000); // $3,500.00
     expect(result.updatedAt).toBeInstanceOf(Date);
     expect(rpc).toHaveBeenCalledWith("eth_call", [
       { to: "0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70", data: "0xfeaf968c" },
@@ -43,7 +43,7 @@ describe("ChainlinkOracle", () => {
 
     const result = await oracle.getPrice("BTC");
 
-    expect(result.priceCents).toBe(6_500_000); // $65,000.00
+    expect(result.priceMicros).toBe(65_000_000_000); // $65,000.00
   });
 
   it("handles fractional dollar prices correctly", async () => {
@@ -53,7 +53,7 @@ describe("ChainlinkOracle", () => {
 
     const result = await oracle.getPrice("ETH");
 
-    expect(result.priceCents).toBe(345_678); // $3,456.78
+    expect(result.priceMicros).toBe(3_456_780_000); // $3,456.78
   });
 
   it("rejects stale prices", async () => {
@@ -102,6 +102,6 @@ describe("ChainlinkOracle", () => {
     // 60-minute threshold → fresh
     const relaxed = new ChainlinkOracle({ rpcCall: rpc, maxStalenessMs: 60 * 60 * 1000 });
     const result = await relaxed.getPrice("ETH");
-    expect(result.priceCents).toBe(350_000);
+    expect(result.priceMicros).toBe(3_500_000_000);
   });
 });

package/src/billing/crypto/oracle/__tests__/coingecko.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from "vitest";
+import { CoinGeckoOracle } from "../coingecko.js";
+
+describe("CoinGeckoOracle", () => {
+  const mockFetch = (price: number) =>
+    vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ bitcoin: { usd: price } }),
+    });
+
+  it("returns price in microdollars from CoinGecko API", async () => {
+    const oracle = new CoinGeckoOracle({ fetchFn: mockFetch(84_532.17) as unknown as typeof fetch });
+    const result = await oracle.getPrice("BTC");
+    expect(result.priceMicros).toBe(84_532_170_000);
+    expect(result.updatedAt).toBeInstanceOf(Date);
+  });
+
+  it("caches prices within TTL", async () => {
+    const fn = mockFetch(84_532.17);
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch, cacheTtlMs: 60_000 });
+    await oracle.getPrice("BTC");
+    await oracle.getPrice("BTC");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-fetches after cache expires", async () => {
+    const fn = mockFetch(84_532.17);
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch, cacheTtlMs: 0 });
+    await oracle.getPrice("BTC");
+    await oracle.getPrice("BTC");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws for unknown asset", async () => {
+    const oracle = new CoinGeckoOracle({ fetchFn: mockFetch(100) as unknown as typeof fetch });
+    await expect(oracle.getPrice("UNKNOWN")).rejects.toThrow("No price oracle supports asset: UNKNOWN");
+  });
+
+  it("throws on API error", async () => {
+    const fn = vi.fn().mockResolvedValue({ ok: false, status: 429, statusText: "Too Many Requests" });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    await expect(oracle.getPrice("BTC")).rejects.toThrow("CoinGecko API error");
+  });
+
+  it("throws on zero price", async () => {
+    const fn = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ bitcoin: { usd: 0 } }),
+    });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    await expect(oracle.getPrice("BTC")).rejects.toThrow("Invalid CoinGecko price");
+  });
+
+  it("resolves DOGE via coingecko ID mapping", async () => {
+    const fn = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ dogecoin: { usd: 0.1742 } }),
+    });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    const result = await oracle.getPrice("DOGE");
+    expect(result.priceMicros).toBe(174_200);
+    expect(fn).toHaveBeenCalledWith(expect.stringContaining("ids=dogecoin"));
+  });
+
+  it("resolves LTC via coingecko ID mapping", async () => {
+    const fn = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ litecoin: { usd: 92.45 } }),
+    });
+    const oracle = new CoinGeckoOracle({ fetchFn: fn as unknown as typeof fetch });
+    const result = await oracle.getPrice("LTC");
+    expect(result.priceMicros).toBe(92_450_000);
+    expect(fn).toHaveBeenCalledWith(expect.stringContaining("ids=litecoin"));
+  });
+});

package/src/billing/crypto/oracle/__tests__/composite.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from "vitest";
+import { CompositeOracle } from "../composite.js";
+import type { IPriceOracle } from "../types.js";
+
+function mockOracle(priceMicros: number): IPriceOracle {
+  return { getPrice: vi.fn().mockResolvedValue({ priceMicros, updatedAt: new Date() }) };
+}
+
+function failingOracle(msg = "no feed"): IPriceOracle {
+  return { getPrice: vi.fn().mockRejectedValue(new Error(msg)) };
+}
+
+describe("CompositeOracle", () => {
+  it("uses primary when feedAddress is provided and primary succeeds", async () => {
+    const primary = mockOracle(8_500_000);
+    const fallback = mockOracle(8_400_000);
+    const oracle = new CompositeOracle(primary, fallback);
+
+    const result = await oracle.getPrice("BTC", "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F");
+    expect(result.priceMicros).toBe(8_500_000);
+    expect(primary.getPrice).toHaveBeenCalledWith("BTC", "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F");
+    expect(fallback.getPrice).not.toHaveBeenCalled();
+  });
+
+  it("falls back when primary fails with feedAddress", async () => {
+    const primary = failingOracle("stale");
+    const fallback = mockOracle(8_400_000);
+    const oracle = new CompositeOracle(primary, fallback);
+
+    const result = await oracle.getPrice("BTC", "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F");
+    expect(result.priceMicros).toBe(8_400_000);
+  });
+
+  it("tries primary without feed, then falls back for unknown assets", async () => {
+    const primary = failingOracle("No price feed for asset: DOGE");
+    const fallback = mockOracle(17);
+    const oracle = new CompositeOracle(primary, fallback);
+
+    const result = await oracle.getPrice("DOGE");
+    expect(result.priceMicros).toBe(17);
+  });
+
+  it("uses primary built-in feeds for BTC/ETH without explicit feedAddress", async () => {
+    const primary = mockOracle(8_500_000);
+    const fallback = mockOracle(8_400_000);
+    const oracle = new CompositeOracle(primary, fallback);
+
+    const result = await oracle.getPrice("BTC");
+    expect(result.priceMicros).toBe(8_500_000);
+    expect(primary.getPrice).toHaveBeenCalledWith("BTC");
+    expect(fallback.getPrice).not.toHaveBeenCalled();
+  });
+
+  it("propagates fallback errors when both fail", async () => {
+    const primary = failingOracle("no chainlink");
+    const fallback = failingOracle("no coingecko");
+    const oracle = new CompositeOracle(primary, fallback);
+
+    await expect(oracle.getPrice("UNKNOWN")).rejects.toThrow("no coingecko");
+  });
+});

package/src/billing/crypto/oracle/__tests__/convert.test.ts

@@ -3,60 +3,72 @@ import { centsToNative, nativeToCents } from "../convert.js";
 
 describe("centsToNative", () => {
   it("converts $50 to ETH wei at $3,500", () => {
-    // 5000 cents × 10^18 / 350000 cents = 14285714285714285n wei
-    const wei = centsToNative(5000, 350_000, 18);
+    // 5000 cents × 10000 × 10^18 / 3_500_000_000 micros = 14285714285714285n wei
+    const wei = centsToNative(5000, 3_500_000_000, 18);
     expect(wei).toBe(14_285_714_285_714_285n);
   });
 
   it("converts $50 to BTC sats at $65,000", () => {
-    // 5000 cents × 10^8 / 6500000 cents = 76923n sats
-    const sats = centsToNative(5000, 6_500_000, 8);
+    // 5000 cents × 10000 × 10^8 / 65_000_000_000 micros = 76923n sats
+    const sats = centsToNative(5000, 65_000_000_000, 8);
     expect(sats).toBe(76_923n);
   });
 
+  it("converts $50 to DOGE at $0.094147", () => {
+    // 5000 cents × 10000 × 10^8 / 94_147 micros = 53_107_898_982n base units (531.08 DOGE)
+    const dogeUnits = centsToNative(5000, 94_147, 8);
+    expect(Number(dogeUnits) / 1e8).toBeCloseTo(531.08, 0);
+  });
+
+  it("converts $50 to LTC at $55.79", () => {
+    // 5000 cents × 10000 × 10^8 / 55_790_000 micros = 89_622_512n base units (0.896 LTC)
+    const ltcUnits = centsToNative(5000, 55_790_000, 8);
+    expect(Number(ltcUnits) / 1e8).toBeCloseTo(0.896, 2);
+  });
+
   it("converts $100 to ETH wei at $2,000", () => {
-    // 10000 cents × 10^18 / 200000 cents = 50000000000000000n wei (0.05 ETH)
-    const wei = centsToNative(10_000, 200_000, 18);
+    // 10000 cents × 10000 × 10^18 / 2_000_000_000 micros = 50_000_000_000_000_000n (0.05 ETH)
+    const wei = centsToNative(10_000, 2_000_000_000, 18);
     expect(wei).toBe(50_000_000_000_000_000n);
   });
 
   it("rejects non-integer amountCents", () => {
-    expect(() => centsToNative(50.5, 350_000, 18)).toThrow("positive integer");
+    expect(() => centsToNative(50.5, 3_500_000_000, 18)).toThrow("positive integer");
   });
 
   it("rejects zero amountCents", () => {
-    expect(() => centsToNative(0, 350_000, 18)).toThrow("positive integer");
+    expect(() => centsToNative(0, 3_500_000_000, 18)).toThrow("positive integer");
   });
 
-  it("rejects zero priceCents", () => {
+  it("rejects zero priceMicros", () => {
     expect(() => centsToNative(5000, 0, 18)).toThrow("positive integer");
   });
 
   it("rejects negative decimals", () => {
-    expect(() => centsToNative(5000, 350_000, -1)).toThrow("non-negative integer");
+    expect(() => centsToNative(5000, 3_500_000_000, -1)).toThrow("non-negative integer");
   });
 });
 
 describe("nativeToCents", () => {
   it("converts ETH wei back to cents at $3,500", () => {
-    // 14285714285714285n wei × 350000 / 10^18 = 4999 cents (truncated)
-    const cents = nativeToCents(14_285_714_285_714_285n, 350_000, 18);
-    expect(cents).toBe(4999); // truncation from integer division
+    // 14285714285714285n × 3_500_000_000 / (10000 × 10^18) = 4999 cents (truncated)
+    const cents = nativeToCents(14_285_714_285_714_285n, 3_500_000_000, 18);
+    expect(cents).toBe(4999);
   });
 
   it("converts BTC sats back to cents at $65,000", () => {
-    // 76923n sats × 6500000 / 10^8 = 4999 cents (truncated)
-    const cents = nativeToCents(76_923n, 6_500_000, 8);
+    // 76923n × 65_000_000_000 / (10000 × 10^8) = 4999 cents
+    const cents = nativeToCents(76_923n, 65_000_000_000, 8);
     expect(cents).toBe(4999);
   });
 
   it("exact round-trip for clean division", () => {
     // 0.05 ETH at $2,000 = $100
-    const cents = nativeToCents(50_000_000_000_000_000n, 200_000, 18);
+    const cents = nativeToCents(50_000_000_000_000_000n, 2_000_000_000, 18);
     expect(cents).toBe(10_000); // $100.00
   });
 
   it("rejects negative rawAmount", () => {
-    expect(() => nativeToCents(-1n, 350_000, 18)).toThrow("non-negative");
+    expect(() => nativeToCents(-1n, 3_500_000_000, 18)).toThrow("non-negative");
   });
 });

package/src/billing/crypto/oracle/__tests__/fixed.test.ts

@@ -5,19 +5,19 @@ describe("FixedPriceOracle", () => {
   it("returns default ETH price", async () => {
     const oracle = new FixedPriceOracle();
     const result = await oracle.getPrice("ETH");
-    expect(result.priceCents).toBe(350_000); // $3,500
+    expect(result.priceMicros).toBe(3_500_000_000); // $3,500
     expect(result.updatedAt).toBeInstanceOf(Date);
   });
 
   it("returns default BTC price", async () => {
     const oracle = new FixedPriceOracle();
     const result = await oracle.getPrice("BTC");
-    expect(result.priceCents).toBe(6_500_000); // $65,000
+    expect(result.priceMicros).toBe(65_000_000_000); // $65,000
   });
 
   it("accepts custom prices", async () => {
-    const oracle = new FixedPriceOracle({ ETH: 200_000, BTC: 5_000_000 });
-    expect((await oracle.getPrice("ETH")).priceCents).toBe(200_000);
-    expect((await oracle.getPrice("BTC")).priceCents).toBe(5_000_000);
+    const oracle = new FixedPriceOracle({ ETH: 2_000_000_000, BTC: 50_000_000_000 });
+    expect((await oracle.getPrice("ETH")).priceMicros).toBe(2_000_000_000);
+    expect((await oracle.getPrice("BTC")).priceMicros).toBe(50_000_000_000);
   });
 });

package/src/billing/crypto/oracle/chainlink.ts

@@ -32,7 +32,7 @@ export interface ChainlinkOracleOpts {
  * No API key, no rate limits — just an RPC call to our own node.
  *
  * Chainlink USD feeds use 8 decimals. We convert to integer USD cents:
- *   priceCents = answer / 10^6  (i.e. answer / 10^8 * 100)
+ *   priceMicros = answer / 100  (i.e. answer / 10^8 * 10^6)
  */
 export class ChainlinkOracle implements IPriceOracle {
   private readonly rpc: RpcCall;
@@ -45,11 +45,11 @@ export class ChainlinkOracle implements IPriceOracle {
     this.maxStalenessMs = opts.maxStalenessMs ?? DEFAULT_MAX_STALENESS_MS;
   }
 
-  async getPrice(asset: PriceAsset): Promise<PriceResult> {
-    const feedAddress = this.feeds.get(asset);
-    if (!feedAddress) throw new Error(`No price feed for asset: ${asset}`);
+  async getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult> {
+    const resolvedFeed = feedAddress ?? this.feeds.get(asset);
+    if (!resolvedFeed) throw new Error(`No price feed for asset: ${asset}`);
 
-    const result = (await this.rpc("eth_call", [{ to: feedAddress, data: LATEST_ROUND_DATA }, "latest"])) as string;
+    const result = (await this.rpc("eth_call", [{ to: resolvedFeed, data: LATEST_ROUND_DATA }, "latest"])) as string;
 
     // ABI decode latestRoundData() return:
     //   [0]  roundId       (uint80)  — skip
@@ -74,12 +74,13 @@ export class ChainlinkOracle implements IPriceOracle {
       );
     }
 
-    // Chainlink USD feeds: 8 decimals. answer / 10^6 = cents (integer).
-    const priceCents = Number(answer / 1_000_000n);
-    if (priceCents <= 0) {
-      throw new Error(`Invalid price for ${asset}: ${priceCents} cents`);
+    // Chainlink USD feeds: 8 decimals. answer / 100 = microdollars (10^-6 USD).
+    // e.g. BTC at $70,315 → answer = 7_031_500_000_000 → 70_315_000_000 microdollars
+    const priceMicros = Number(answer / 100n);
+    if (priceMicros <= 0) {
+      throw new Error(`Invalid price for ${asset}: ${priceMicros} microdollars`);
     }
 
-    return { priceCents, updatedAt };
+    return { priceMicros, updatedAt };
   }
 }

package/src/billing/crypto/oracle/coingecko.ts

@@ -0,0 +1,92 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+import { AssetNotSupportedError } from "./types.js";
+
+/**
+ * Token symbol → CoinGecko API ID mapping.
+ * CoinGecko uses lowercase slugs, not ticker symbols.
+ */
+const COINGECKO_IDS: Record<string, string> = {
+  BTC: "bitcoin",
+  ETH: "ethereum",
+  DOGE: "dogecoin",
+  LTC: "litecoin",
+  SOL: "solana",
+  LINK: "chainlink",
+  UNI: "uniswap",
+  AERO: "aerodrome-finance",
+};
+
+/** Default cache TTL: 60 seconds. CoinGecko free tier allows 10-30 req/min. */
+const DEFAULT_CACHE_TTL_MS = 60_000;
+
+interface CachedPrice {
+  priceMicros: number;
+  updatedAt: Date;
+  fetchedAt: number;
+}
+
+export interface CoinGeckoOracleOpts {
+  /** Override token→id mapping. */
+  tokenIds?: Record<string, string>;
+  /** Cache TTL in ms. Default: 60s. */
+  cacheTtlMs?: number;
+  /** Custom fetch function (for testing). */
+  fetchFn?: typeof fetch;
+}
+
+/**
+ * CoinGecko price oracle — free API, no key required.
+ * Used for assets without Chainlink on-chain feeds (DOGE, LTC).
+ * Caches prices to stay within rate limits.
+ */
+export class CoinGeckoOracle implements IPriceOracle {
+  private readonly ids: Record<string, string>;
+  private readonly cacheTtlMs: number;
+  private readonly fetchFn: typeof fetch;
+  private readonly cache = new Map<string, CachedPrice>();
+
+  constructor(opts: CoinGeckoOracleOpts = {}) {
+    this.ids = { ...COINGECKO_IDS, ...opts.tokenIds };
+    this.cacheTtlMs = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    this.fetchFn = opts.fetchFn ?? fetch;
+  }
+
+  async getPrice(asset: PriceAsset, _feedAddress?: `0x${string}`): Promise<PriceResult> {
+    const cached = this.cache.get(asset);
+    if (cached && Date.now() - cached.fetchedAt < this.cacheTtlMs) {
+      return { priceMicros: cached.priceMicros, updatedAt: cached.updatedAt };
+    }
+
+    const coinId = this.ids[asset];
+    if (!coinId) throw new AssetNotSupportedError(asset);
+
+    const url = `https://api.coingecko.com/api/v3/simple/price?ids=${coinId}&vs_currencies=usd`;
+    try {
+      const res = await this.fetchFn(url);
+      if (!res.ok) {
+        throw new Error(`CoinGecko API error for ${asset}: ${res.status} ${res.statusText}`);
+      }
+
+      const data = (await res.json()) as Record<string, { usd?: number }>;
+      const usdPrice = data[coinId]?.usd;
+      if (usdPrice === undefined || usdPrice <= 0) {
+        throw new Error(`Invalid CoinGecko price for ${asset}: ${usdPrice}`);
+      }
+
+      const priceMicros = Math.round(usdPrice * 1_000_000);
+      const updatedAt = new Date();
+
+      this.cache.set(asset, { priceMicros, updatedAt, fetchedAt: Date.now() });
+
+      return { priceMicros, updatedAt };
+    } catch (err) {
+      // Serve stale cache on transient failure (rate limit, network error).
+      // A slightly old price is better than rejecting the charge entirely.
+      const stale = this.cache.get(asset);
+      if (stale) {
+        return { priceMicros: stale.priceMicros, updatedAt: stale.updatedAt };
+      }
+      throw err;
+    }
+  }
+}