@wopr-network/platform-core 1.49.0 → 1.49.2

package/dist/billing/crypto/__tests__/key-server.test.js

@@ -101,7 +101,7 @@ function mockDeps() {
         db: createMockDb(),
         chargeStore: chargeStore,
         methodStore: methodStore,
-        oracle: { getPrice: vi.fn().mockResolvedValue({ priceCents: 6_500_000, updatedAt: new Date() }) },
+        oracle: { getPrice: vi.fn().mockResolvedValue({ priceMicros: 65_000_000_000, updatedAt: new Date() }) },
     };
 }
 describe("key-server routes", () => {

package/dist/billing/crypto/btc/__tests__/watcher.test.js

@@ -21,7 +21,7 @@ function makeCursorStore() {
     };
 }
 function makeOracle() {
-    return { getPrice: vi.fn().mockResolvedValue({ priceCents: 6_500_000 }) };
+    return { getPrice: vi.fn().mockResolvedValue({ priceMicros: 65_000_000_000 }) };
 }
 describe("BtcWatcher — intermediate confirmations", () => {
     it("fires onPayment at 0 confirmations when tx first detected", async () => {

package/dist/billing/crypto/btc/watcher.js

@@ -1,3 +1,4 @@
+import { nativeToCents } from "../oracle/convert.js";
 export class BtcWatcher {
     rpc;
     addresses;
@@ -55,7 +56,7 @@ export class BtcWatcher {
             false, // include_empty
             true, // include_watchonly
         ]));
-        const { priceCents } = await this.oracle.getPrice("BTC");
+        const { priceMicros } = await this.oracle.getPrice("BTC");
         for (const entry of received) {
             if (!this.addresses.has(entry.address))
                 continue;
@@ -73,7 +74,8 @@ export class BtcWatcher {
                 if (lastSeen !== null && tx.confirmations <= lastSeen)
                     continue; // No change
                 const amountSats = Math.round(detail.amount * 100_000_000);
-                const amountUsdCents = Math.round((amountSats * priceCents) / 100_000_000);
+                // priceMicros is microdollars per 1 BTC. Convert sats→USD cents via nativeToCents.
+                const amountUsdCents = nativeToCents(BigInt(amountSats), priceMicros, 8);
                 const event = {
                     address: entry.address,
                     txid,

package/dist/billing/crypto/client.d.ts

@@ -27,7 +27,7 @@ export interface CreateChargeResult {
     derivationIndex: number;
     expiresAt: string;
     displayAmount?: string;
-    priceCents?: number;
+    priceMicros?: number;
 }
 export interface ChargeStatus {
     chargeId: string;

package/dist/billing/crypto/evm/__tests__/eth-checkout.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { createEthCheckout, MIN_ETH_USD } from "../eth-checkout.js";
-const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceMicros: 3_500_000_000, updatedAt: new Date() }) };
 function makeDeps(derivationIndex = 0) {
     return {
         chargeStore: {
@@ -16,9 +16,9 @@ describe("createEthCheckout", () => {
         const deps = makeDeps();
         const result = await createEthCheckout(deps, { tenant: "t1", amountUsd: 50, chain: "base" });
         expect(result.amountUsd).toBe(50);
-        expect(result.priceCents).toBe(350_000);
+        expect(result.priceMicros).toBe(3_500_000_000);
         expect(result.chain).toBe("base");
-        // $50 = 5000 cents. 5000 × 10^18 / 350000 = 14285714285714285n
+        // $50 = 5000 cents × 10000 micros/cent × 10^18 / 3_500_000_000 micros = 14285714285714285n
         expect(result.expectedWei).toBe("14285714285714285");
         expect(result.depositAddress).toMatch(/^0x/);
         expect(result.referenceId).toMatch(/^eth:base:0x/);

package/dist/billing/crypto/evm/__tests__/eth-watcher.test.js

@@ -3,7 +3,7 @@ import { EthWatcher } from "../eth-watcher.js";
 function makeRpc(responses) {
     return vi.fn(async (method) => responses[method]);
 }
-const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceMicros: 3_500_000_000, updatedAt: new Date() }) };
 describe("EthWatcher", () => {
     it("detects native ETH transfer to watched address", async () => {
         const onPayment = vi.fn();
@@ -35,7 +35,7 @@ describe("EthWatcher", () => {
         const event = onPayment.mock.calls[0][0];
         expect(event.to).toBe("0xdeposit");
         expect(event.valueWei).toBe("1000000000000000000");
-        expect(event.amountUsdCents).toBe(350_000); // 1 ETH × $3,500
+        expect(event.amountUsdCents).toBe(350_000); // 1 ETH × $3,500 = $3,500 = 350,000 cents
         expect(event.txHash).toBe("0xabc");
         expect(event.confirmations).toBe(0);
         expect(event.confirmationsRequired).toBe(1);

package/dist/billing/crypto/evm/eth-checkout.d.ts

@@ -17,8 +17,8 @@ export interface EthCheckoutResult {
     amountUsd: number;
     /** Expected ETH amount in wei (BigInt as string). */
     expectedWei: string;
-    /** ETH price in USD cents at checkout time. */
-    priceCents: number;
+    /** ETH price in microdollars at checkout time (10^-6 USD). */
+    priceMicros: number;
     chain: EvmChain;
     referenceId: string;
 }

package/dist/billing/crypto/evm/eth-checkout.js

@@ -16,8 +16,8 @@ export async function createEthCheckout(deps, opts) {
         throw new Error(`Minimum payment amount is $${MIN_ETH_USD}`);
     }
     const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
-    const { priceCents } = await deps.oracle.getPrice("ETH");
-    const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
+    const { priceMicros } = await deps.oracle.getPrice("ETH");
+    const expectedWei = centsToNative(amountUsdCents, priceMicros, 18);
     const maxRetries = 3;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
@@ -37,7 +37,7 @@ export async function createEthCheckout(deps, opts) {
                 depositAddress,
                 amountUsd: opts.amountUsd,
                 expectedWei: expectedWei.toString(),
-                priceCents,
+                priceMicros,
                 chain: opts.chain,
                 referenceId,
             };

package/dist/billing/crypto/evm/eth-watcher.js

@@ -60,7 +60,7 @@ export class EthWatcher {
         const confirmed = latest - this.confirmations;
         if (latest < this._cursor)
             return;
-        const { priceCents } = await this.oracle.getPrice("ETH");
+        const { priceMicros } = await this.oracle.getPrice("ETH");
         // Scan up to latest (not just confirmed) to detect pending txs
         for (let blockNum = this._cursor; blockNum <= latest; blockNum++) {
             const block = (await this.rpc("eth_getBlockByNumber", [`0x${blockNum.toString(16)}`, true]));
@@ -82,7 +82,7 @@ export class EthWatcher {
                     if (lastConf !== null && confs <= lastConf)
                         continue;
                 }
-                const amountUsdCents = nativeToCents(valueWei, priceCents, 18);
+                const amountUsdCents = nativeToCents(valueWei, priceMicros, 18);
                 const event = {
                     chain: this.chain,
                     from: tx.from.toLowerCase(),

package/dist/billing/crypto/key-server-entry.js

@@ -17,6 +17,8 @@ import { DrizzleWatcherCursorStore } from "./cursor-store.js";
 import { createRpcCaller } from "./evm/watcher.js";
 import { createKeyServerApp } from "./key-server.js";
 import { ChainlinkOracle } from "./oracle/chainlink.js";
+import { CoinGeckoOracle } from "./oracle/coingecko.js";
+import { CompositeOracle } from "./oracle/composite.js";
 import { FixedPriceOracle } from "./oracle/fixed.js";
 import { DrizzlePaymentMethodStore } from "./payment-method-store.js";
 import { startWatchers } from "./watcher-service.js";
@@ -41,10 +43,13 @@ async function main() {
     const db = drizzle(pool, { schema });
     const chargeStore = new DrizzleCryptoChargeRepository(db);
     const methodStore = new DrizzlePaymentMethodStore(db);
-    // Chainlink on-chain oracle for volatile assets (BTC, ETH).
-    const oracle = BASE_RPC_URL
+    // Composite oracle: Chainlink on-chain (BTC, ETH on Base) + CoinGecko fallback (DOGE, LTC, etc.)
+    // Every volatile asset needs reliable USD pricing — the ledger credits nanodollars.
+    const chainlink = BASE_RPC_URL
         ? new ChainlinkOracle({ rpcCall: createRpcCaller(BASE_RPC_URL) })
         : new FixedPriceOracle();
+    const coingecko = new CoinGeckoOracle();
+    const oracle = new CompositeOracle(chainlink, coingecko);
     const app = createKeyServerApp({
         db,
         chargeStore,

package/dist/billing/crypto/key-server.js

@@ -13,6 +13,7 @@ import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/sche
 import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
 import { deriveDepositAddress } from "./evm/address-gen.js";
 import { centsToNative } from "./oracle/convert.js";
+import { AssetNotSupportedError } from "./oracle/types.js";
 /**
  * Derive the next unused address for a chain.
  * Atomically increments next_index and records address in a single transaction.
@@ -120,14 +121,24 @@ export function createKeyServerApp(deps) {
         // Compute expected crypto amount in native base units.
         // Price is locked NOW — this is what the user must send.
         let expectedAmount;
-        if (method.oracleAddress) {
-            // Volatile asset (BTC, ETH, DOGE) — oracle-priced
-            const { priceCents } = await deps.oracle.getPrice(token);
-            expectedAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
+        const feedAddress = method.oracleAddress ? method.oracleAddress : 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);
         }
-        else {
-            // Stablecoin (1:1 USD) — e.g. $50 USDC = 50_000_000 base units (6 decimals)
-            expectedAmount = (BigInt(amountUsdCents) * 10n ** BigInt(method.decimals)) / 100n;
+        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.message}` }, 503);
+            }
         }
         const referenceId = `${token.toLowerCase()}:${address.toLowerCase()}`;
         await deps.chargeStore.createStablecoinCharge({

package/dist/billing/crypto/oracle/__tests__/chainlink.test.js

@@ -22,7 +22,7 @@ describe("ChainlinkOracle", () => {
         const rpc = vi.fn().mockResolvedValue(encodeRoundData(350000000000n, nowSec));
         const oracle = new ChainlinkOracle({ rpcCall: rpc });
         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" },
@@ -34,14 +34,14 @@ describe("ChainlinkOracle", () => {
         const rpc = vi.fn().mockResolvedValue(encodeRoundData(6500000000000n, nowSec));
         const oracle = new ChainlinkOracle({ rpcCall: rpc });
         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 () => {
         // ETH at $3,456.78 → answer = 345_678_000_000
         const rpc = vi.fn().mockResolvedValue(encodeRoundData(345678000000n, nowSec));
         const oracle = new ChainlinkOracle({ rpcCall: rpc });
         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 () => {
         const staleTime = nowSec - 7200; // 2 hours ago
@@ -78,6 +78,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/dist/billing/crypto/oracle/__tests__/coingecko.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/billing/crypto/oracle/__tests__/coingecko.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+import { CoinGeckoOracle } from "../coingecko.js";
+describe("CoinGeckoOracle", () => {
+    const mockFetch = (price) => 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) });
+        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, 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, 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) });
+        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 });
+        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 });
+        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 });
+        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 });
+        const result = await oracle.getPrice("LTC");
+        expect(result.priceMicros).toBe(92_450_000);
+        expect(fn).toHaveBeenCalledWith(expect.stringContaining("ids=litecoin"));
+    });
+});

package/dist/billing/crypto/oracle/__tests__/composite.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/billing/crypto/oracle/__tests__/composite.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import { CompositeOracle } from "../composite.js";
+function mockOracle(priceMicros) {
+    return { getPrice: vi.fn().mockResolvedValue({ priceMicros, updatedAt: new Date() }) };
+}
+function failingOracle(msg = "no feed") {
+    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/dist/billing/crypto/oracle/__tests__/convert.test.js

@@ -2,50 +2,60 @@ import { describe, expect, it } from "vitest";
 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(14285714285714285n);
     });
     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(76923n);
     });
+    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(50000000000000000n);
     });
     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(14285714285714285n, 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(14285714285714285n, 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(76923n, 6_500_000, 8);
+        // 76923n × 65_000_000_000 / (10000 × 10^8) = 4999 cents
+        const cents = nativeToCents(76923n, 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(50000000000000000n, 200_000, 18);
+        const cents = nativeToCents(50000000000000000n, 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/dist/billing/crypto/oracle/__tests__/fixed.test.js

@@ -4,17 +4,17 @@ 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/dist/billing/crypto/oracle/chainlink.d.ts

@@ -14,13 +14,13 @@ 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 declare class ChainlinkOracle implements IPriceOracle {
     private readonly rpc;
     private readonly feeds;
     private readonly maxStalenessMs;
     constructor(opts: ChainlinkOracleOpts);
-    getPrice(asset: PriceAsset): Promise<PriceResult>;
+    getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult>;
 }
 export {};

package/dist/billing/crypto/oracle/chainlink.js

@@ -17,7 +17,7 @@ const DEFAULT_MAX_STALENESS_MS = 60 * 60 * 1000;
  * 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 {
     rpc;
@@ -28,11 +28,11 @@ export class ChainlinkOracle {
         this.feeds = new Map(Object.entries({ ...FEED_ADDRESSES, ...opts.feedAddresses }));
         this.maxStalenessMs = opts.maxStalenessMs ?? DEFAULT_MAX_STALENESS_MS;
     }
-    async getPrice(asset) {
-        const feedAddress = this.feeds.get(asset);
-        if (!feedAddress)
+    async getPrice(asset, feedAddress) {
+        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"]));
+        const result = (await this.rpc("eth_call", [{ to: resolvedFeed, data: LATEST_ROUND_DATA }, "latest"]));
         // ABI decode latestRoundData() return:
         //   [0]  roundId       (uint80)  — skip
         //   [1]  answer        (int256)  — price × 10^8
@@ -51,11 +51,12 @@ export class ChainlinkOracle {
         if (ageMs > this.maxStalenessMs) {
             throw new Error(`Price feed for ${asset} is stale (${Math.round(ageMs / 1000)}s old, max ${Math.round(this.maxStalenessMs / 1000)}s)`);
         }
-        // Chainlink USD feeds: 8 decimals. answer / 10^6 = cents (integer).
-        const priceCents = Number(answer / 1000000n);
-        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/dist/billing/crypto/oracle/coingecko.d.ts

@@ -0,0 +1,22 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+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 declare class CoinGeckoOracle implements IPriceOracle {
+    private readonly ids;
+    private readonly cacheTtlMs;
+    private readonly fetchFn;
+    private readonly cache;
+    constructor(opts?: CoinGeckoOracleOpts);
+    getPrice(asset: PriceAsset, _feedAddress?: `0x${string}`): Promise<PriceResult>;
+}

package/dist/billing/crypto/oracle/coingecko.js

@@ -0,0 +1,67 @@
+import { AssetNotSupportedError } from "./types.js";
+/**
+ * Token symbol → CoinGecko API ID mapping.
+ * CoinGecko uses lowercase slugs, not ticker symbols.
+ */
+const COINGECKO_IDS = {
+    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;
+/**
+ * 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 {
+    ids;
+    cacheTtlMs;
+    fetchFn;
+    cache = new Map();
+    constructor(opts = {}) {
+        this.ids = { ...COINGECKO_IDS, ...opts.tokenIds };
+        this.cacheTtlMs = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        this.fetchFn = opts.fetchFn ?? fetch;
+    }
+    async getPrice(asset, _feedAddress) {
+        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());
+            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;
+        }
+    }
+}

package/dist/billing/crypto/oracle/composite.d.ts

@@ -0,0 +1,14 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+/**
+ * Composite oracle — tries primary (Chainlink on-chain), falls back to secondary (CoinGecko).
+ *
+ * When a feedAddress is provided (from payment_methods.oracle_address), the primary
+ * oracle is used with that address. When no feed exists or the primary fails,
+ * the fallback oracle is consulted.
+ */
+export declare class CompositeOracle implements IPriceOracle {
+    private readonly primary;
+    private readonly fallback;
+    constructor(primary: IPriceOracle, fallback: IPriceOracle);
+    getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult>;
+}