@agentwonderland/mcp 0.1.25 → 0.1.26

package/src/core/__tests__/formatters.test.ts

@@ -14,4 +14,16 @@ describe("formatRunResult", () => {
     expect(output).toContain("Covered by credit pack (pack-123)");
     expect(output).not.toContain("Paid:");
   });
+
+  it("formats string-valued settled amounts from job lookups", () => {
+    const output = formatRunResult({
+      agent_name: "Async Analyzer",
+      status: "completed",
+      settled_amount: "0.100000",
+      job_id: "job-123",
+    }, { paymentMethod: "card" });
+
+    expect(output).toContain("Paid: $0.10 via card");
+    expect(output).toContain("Job ID: job-123");
+  });
 });

package/src/core/__tests__/passes-api.test.ts

@@ -0,0 +1,33 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const state = vi.hoisted(() => ({
+  apiGet: vi.fn(),
+}));
+
+vi.mock("../api-client.js", () => ({
+  apiGet: (...args: unknown[]) => state.apiGet(...args),
+}));
+
+describe("getCreditPackInventory", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    state.apiGet.mockReset();
+  });
+
+  it("requests inventory for the selected payment method principal", async () => {
+    state.apiGet.mockResolvedValueOnce({
+      consumer_principal: "did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+      offers: [],
+      balances: [],
+    });
+
+    const { getCreditPackInventory } = await import("../passes.js");
+    const result = await getCreditPackInventory("agent-1", "solana");
+
+    expect(result?.consumer_principal).toContain("did:pkh:solana:");
+    expect(state.apiGet).toHaveBeenCalledWith("/agents/agent-1/credit-packs", {
+      ensureConsumerPrincipal: true,
+      principalMethod: "solana",
+    });
+  });
+});

package/src/core/__tests__/payments.test.ts

@@ -16,7 +16,7 @@ let currentResolvedMethod: { wallet: any; chain: string } | null = null;
 const createdFetches = [vi.fn(), vi.fn(), vi.fn(), vi.fn()];
 const mockMppxCreate = vi.fn();
 const mockStripe = vi.fn((opts: unknown) => opts);
-const mockTempo = vi.fn((..._args: unknown[]) => "tempo_method");
+const mockTempoChargeClient = vi.fn((..._args: unknown[]) => "tempo_method");
 const mockBaseChargeClient = vi.fn((..._args: unknown[]) => "base_method");
 
 vi.mock("../config.js", () => ({
@@ -33,7 +33,10 @@ vi.mock("mppx/client", () => ({
     create: (config: unknown) => mockMppxCreate(config),
   },
   stripe: (config: unknown) => mockStripe(config),
-  tempo: (config: unknown) => mockTempo(config),
+}));
+
+vi.mock("../tempo-charge.js", () => ({
+  tempoChargeClient: (config: unknown) => mockTempoChargeClient(config),
 }));
 
 vi.mock("../base-charge.js", () => ({
@@ -74,6 +77,14 @@ describe("payment method initialization", () => {
 
     expect(firstFetch).not.toBe(secondFetch);
     expect(mockMppxCreate).toHaveBeenCalledTimes(2);
+    expect(mockMppxCreate).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ polyfill: false }),
+    );
+    expect(mockMppxCreate).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ polyfill: false }),
+    );
   });
 
   it("initializes only the Base method when base is requested", async () => {
@@ -92,9 +103,9 @@ describe("payment method initialization", () => {
     await getPaymentFetch("base");
 
     expect(mockBaseChargeClient).toHaveBeenCalledTimes(1);
-    expect(mockTempo).not.toHaveBeenCalled();
+    expect(mockTempoChargeClient).not.toHaveBeenCalled();
     expect(mockMppxCreate).toHaveBeenCalledWith(
-      expect.objectContaining({ methods: ["base_method"] }),
+      expect.objectContaining({ methods: ["base_method"], polyfill: false }),
     );
   });
 
@@ -113,10 +124,10 @@ describe("payment method initialization", () => {
     const { getPaymentFetch } = await import("../payments.js");
     await getPaymentFetch("tempo");
 
-    expect(mockTempo).toHaveBeenCalledTimes(1);
+    expect(mockTempoChargeClient).toHaveBeenCalledTimes(1);
     expect(mockBaseChargeClient).not.toHaveBeenCalled();
     expect(mockMppxCreate).toHaveBeenCalledWith(
-      expect.objectContaining({ methods: ["tempo_method"] }),
+      expect.objectContaining({ methods: ["tempo_method"], polyfill: false }),
     );
   });
 });

package/src/core/__tests__/principal.test.ts

@@ -23,15 +23,26 @@ vi.mock("../config.js", () => ({
   },
   getDefaultWallet: () => state.wallets[0],
   getWallets: () => state.wallets,
+  resolveWalletAndChain: (method: string) => {
+    for (const wallet of state.wallets) {
+      if (wallet.id === method) {
+        return { wallet, chain: wallet.defaultChain ?? wallet.chains[0] };
+      }
+      if (wallet.chains.includes(method)) {
+        return { wallet, chain: method };
+      }
+    }
+    return null;
+  },
 }));
 
 vi.mock("../payments.js", () => ({
-  getWalletAddress: async (walletId: string) => {
-    if (walletId in state.addresses) {
-      return state.addresses[walletId] ?? null;
+  getWalletAddress: async (method?: string) => {
+    if (method && method in state.addresses) {
+      return state.addresses[method] ?? null;
     }
 
-    const wallet = state.wallets.find((entry) => entry.id === walletId);
+    const wallet = state.wallets.find((entry) => entry.id === method);
     if (wallet?.key) {
       const { privateKeyToAccount } = await import("viem/accounts");
       return privateKeyToAccount(wallet.key as `0x${string}`).address;
@@ -84,4 +95,38 @@ describe("consumer principal helpers", () => {
     expect(state.addedWallets).toHaveLength(1);
     expect(state.addedWallets[0]?.chains).toEqual(["tempo", "base"]);
   });
+
+  it("derives a Solana principal when the selected payment method is solana", async () => {
+    state.wallets = [
+      { id: "aw-main", keyType: "ows", owsWalletId: "ows-main", chains: ["tempo", "base", "solana"], defaultChain: "tempo" },
+    ];
+    state.addresses = {
+      solana: "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+      tempo: "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+      base: "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+    };
+
+    const { getConsumerPrincipalForMethod } = await import("../principal.js");
+    const principal = await getConsumerPrincipalForMethod("solana");
+
+    expect(principal).toBe(
+      "did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+    );
+  });
+
+  it("returns the Base rebate principal when an EVM wallet is available", async () => {
+    state.wallets = [
+      { id: "aw-main", keyType: "ows", owsWalletId: "ows-main", chains: ["tempo", "base", "solana"], defaultChain: "tempo" },
+    ];
+    state.addresses = {
+      solana: "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+      tempo: "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+      base: "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+    };
+
+    const { getBaseRebatePrincipal } = await import("../principal.js");
+    const principal = await getBaseRebatePrincipal();
+
+    expect(principal).toBe("did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
+  });
 });

package/src/core/__tests__/solana-charge.test.ts

@@ -0,0 +1,59 @@
+import { PublicKey } from "@solana/web3.js";
+import { TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync } from "@solana/spl-token";
+import { describe, expect, it, vi } from "vitest";
+import { SOLANA_USDC_MINT } from "../solana-charge.js";
+
+describe("resolveRecipientTokenAccount", () => {
+  it("uses the recipient directly when Stripe gives us a token account", async () => {
+    const { resolveRecipientTokenAccount } = await import("../solana-charge.js");
+    const connection = {
+      getParsedAccountInfo: vi.fn().mockResolvedValue({
+        value: { owner: TOKEN_PROGRAM_ID },
+      }),
+    } as any;
+    const mint = new PublicKey(SOLANA_USDC_MINT);
+    const recipient = new PublicKey("42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF");
+
+    const resolved = await resolveRecipientTokenAccount(connection, mint, recipient);
+
+    expect(resolved.tokenAccount.toBase58()).toBe(recipient.toBase58());
+    expect(resolved.needsCreateAssociatedAccount).toBe(false);
+    expect(connection.getParsedAccountInfo).toHaveBeenCalledTimes(1);
+  });
+
+  it("reuses the associated token account when it already exists", async () => {
+    const { resolveRecipientTokenAccount } = await import("../solana-charge.js");
+    const connection = {
+      getParsedAccountInfo: vi.fn()
+        .mockResolvedValueOnce({ value: null })
+        .mockResolvedValueOnce({ value: { owner: TOKEN_PROGRAM_ID } }),
+    } as any;
+    const mint = new PublicKey(SOLANA_USDC_MINT);
+    const recipient = new PublicKey("G7kW6ZPMAK9v11AaVkK9FHed2Gd4WYwvCbanXUmK9WtS");
+    const expectedAta = getAssociatedTokenAddressSync(mint, recipient, false, TOKEN_PROGRAM_ID);
+
+    const resolved = await resolveRecipientTokenAccount(connection, mint, recipient);
+
+    expect(resolved.tokenAccount.toBase58()).toBe(expectedAta.toBase58());
+    expect(resolved.needsCreateAssociatedAccount).toBe(false);
+    expect(connection.getParsedAccountInfo).toHaveBeenCalledTimes(2);
+  });
+
+  it("marks the associated token account for creation when neither account exists", async () => {
+    const { resolveRecipientTokenAccount } = await import("../solana-charge.js");
+    const connection = {
+      getParsedAccountInfo: vi.fn()
+        .mockResolvedValueOnce({ value: null })
+        .mockResolvedValueOnce({ value: null }),
+    } as any;
+    const mint = new PublicKey(SOLANA_USDC_MINT);
+    const recipient = new PublicKey("G7kW6ZPMAK9v11AaVkK9FHed2Gd4WYwvCbanXUmK9WtS");
+    const expectedAta = getAssociatedTokenAddressSync(mint, recipient, false, TOKEN_PROGRAM_ID);
+
+    const resolved = await resolveRecipientTokenAccount(connection, mint, recipient);
+
+    expect(resolved.tokenAccount.toBase58()).toBe(expectedAta.toBase58());
+    expect(resolved.needsCreateAssociatedAccount).toBe(true);
+    expect(connection.getParsedAccountInfo).toHaveBeenCalledTimes(2);
+  });
+});

package/src/core/api-client.ts

@@ -1,6 +1,12 @@
 import { getApiUrl, getApiKey } from "./config.js";
 import { getPaymentFetch } from "./payments.js";
-import { ensureConsumerPrincipal, getConsumerPrincipal } from "./principal.js";
+import {
+  getBaseRebatePrincipal,
+  ensureConsumerPrincipal,
+  ensureConsumerPrincipalForMethod,
+  getConsumerPrincipal,
+  getConsumerPrincipalForMethod,
+} from "./principal.js";
 
 // ── Error class ────────────────────────────────────────────────────
 
@@ -19,6 +25,7 @@ export class ApiError extends Error {
 
 interface RequestOptions {
   ensureConsumerPrincipal?: boolean;
+  principalMethod?: string;
   extraHeaders?: Record<string, string>;
 }
 
@@ -34,12 +41,17 @@ async function buildHeaders(options?: RequestOptions): Promise<Record<string, st
   }
 
   const principal = options?.ensureConsumerPrincipal
-    ? await ensureConsumerPrincipal()
-    : await getConsumerPrincipal();
+    ? await ensureConsumerPrincipalForMethod(options?.principalMethod)
+    : await getConsumerPrincipalForMethod(options?.principalMethod);
   if (principal) {
     headers["X-AW-Consumer-Principal"] = principal;
   }
 
+  const rebatePrincipal = await getBaseRebatePrincipal();
+  if (rebatePrincipal) {
+    headers["X-AW-Rebate-Principal"] = rebatePrincipal;
+  }
+
   if (options?.extraHeaders) {
     Object.assign(headers, options.extraHeaders);
   }
@@ -141,6 +153,7 @@ export async function apiPostWithPayment<T>(
     method: "POST",
     headers: await buildHeaders({
       ensureConsumerPrincipal: true,
+      principalMethod: payWith,
       ...options,
     }),
     body: JSON.stringify(body),

package/src/core/balances.ts

@@ -0,0 +1,63 @@
+import { getSettings, type ChainSettings } from "./settings.js";
+
+const ERC20_BALANCE_ABI = [
+  {
+    type: "function",
+    name: "balanceOf",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+] as const;
+
+async function fetchEvmUsdcBalance(
+  chain: ChainSettings,
+  address: string,
+): Promise<string | null> {
+  try {
+    const { createPublicClient, http, formatUnits } = await import("viem");
+    const client = createPublicClient({ transport: http(chain.rpcUrl) });
+    const raw = await client.readContract({
+      address: chain.usdc as `0x${string}`,
+      abi: ERC20_BALANCE_ABI,
+      functionName: "balanceOf",
+      args: [address as `0x${string}`],
+    });
+    return formatUnits(raw as bigint, 6);
+  } catch {
+    return null;
+  }
+}
+
+async function fetchSolanaUsdcBalance(
+  chain: ChainSettings,
+  address: string,
+): Promise<string | null> {
+  try {
+    const { Connection, PublicKey } = await import("@solana/web3.js");
+    const connection = new Connection(chain.rpcUrl, "confirmed");
+    const owner = new PublicKey(address);
+    const mint = new PublicKey(chain.usdc);
+    const accounts = await connection.getParsedTokenAccountsByOwner(owner, { mint });
+    let total = 0;
+    for (const { account } of accounts.value) {
+      const amount = (account.data as any)?.parsed?.info?.tokenAmount?.uiAmount;
+      if (typeof amount === "number") total += amount;
+    }
+    return total.toString();
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchUsdcBalance(
+  chain: "tempo" | "base" | "solana",
+  address: string,
+): Promise<string | null> {
+  const settings = await getSettings();
+  if (!settings) return null;
+  const chainConfig = settings.chains[chain];
+  if (!chainConfig) return null;
+  if (chain === "solana") return fetchSolanaUsdcBalance(chainConfig, address);
+  return fetchEvmUsdcBalance(chainConfig, address);
+}

package/src/core/base-charge.ts

@@ -10,7 +10,9 @@ import { toAtomicAmount } from "./amount-utils.js";
 
 // Base USDC (Circle native)
 const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const;
+const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e" as const;
 const BASE_CHAIN_ID = 8453;
+const BASE_SEPOLIA_CHAIN_ID = 84532;
 
 // Standard ERC-20 transfer function ABI
 const ERC20_ABI = [
@@ -66,22 +68,27 @@ export function baseChargeClient(config: BaseChargeClientConfig) {
       const { request } = challenge;
       const amount = toAtomicAmount(request.amount, request.decimals ?? 6);
       const recipient = request.recipient as `0x${string}`;
-      const currency = (request.currency ?? BASE_USDC) as `0x${string}`;
+      const chainId = request.chainId ?? BASE_CHAIN_ID;
+      const currency = (request.currency
+        ?? (chainId === BASE_SEPOLIA_CHAIN_ID ? BASE_SEPOLIA_USDC : BASE_USDC)) as `0x${string}`;
 
       // Dynamic imports to keep the module lightweight
       const { createWalletClient, createPublicClient, http } = await import("viem");
-      const { base } = await import("viem/chains");
+      const { base, baseSepolia } = await import("viem/chains");
 
-      const rpcUrl = config.rpcUrl ?? "https://mainnet.base.org";
+      const chain = chainId === BASE_SEPOLIA_CHAIN_ID ? baseSepolia : base;
+      const rpcUrl = config.rpcUrl ?? (chainId === BASE_SEPOLIA_CHAIN_ID
+        ? "https://sepolia.base.org"
+        : "https://mainnet.base.org");
 
       const walletClient = createWalletClient({
         account: config.account,
-        chain: base,
+        chain,
         transport: http(rpcUrl),
       });
 
       const publicClient = createPublicClient({
-        chain: base,
+        chain,
         transport: http(rpcUrl),
       });
 
@@ -99,7 +106,7 @@ export function baseChargeClient(config: BaseChargeClientConfig) {
       return Credential.serialize({
         challenge,
         payload: { hash, type: "hash" as const },
-        source: `did:pkh:eip155:${BASE_CHAIN_ID}:${config.account.address}`,
+        source: `did:pkh:eip155:${chainId}:${config.account.address}`,
       });
     },
   });

package/src/core/formatters.ts

@@ -112,14 +112,21 @@ interface RunResultLike {
   error_code?: string;
   latency_ms?: number;
   execution_latency_ms?: number;
-  cost?: number;
-  estimated_cost?: number;
+  cost?: number | string;
+  settled_amount?: number | string;
+  estimated_cost?: number | string;
   input_tokens?: number;
   tags?: string[];
   consumption_mode?: string;
   credit_pack_id?: string;
 }
 
+function toDisplayCost(value: number | string | null | undefined): number | null {
+  if (value == null) return null;
+  const numeric = typeof value === "number" ? value : Number.parseFloat(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
 export function formatRunResult(result: RunResultLike, opts?: { paymentMethod?: string }): string {
   const lines: string[] = [];
 
@@ -146,7 +153,7 @@ export function formatRunResult(result: RunResultLike, opts?: { paymentMethod?:
   }
 
   // Summary line
-  const cost = result.cost ?? result.estimated_cost;
+  const cost = toDisplayCost(result.cost ?? result.settled_amount ?? result.estimated_cost);
   const usedCreditPack = result.consumption_mode === "credit_pack";
   const status = result.status === "success" || result.status === "completed" ? "✓" : "✗";
   const agent = result.agent_name ?? result.agent_id ?? "";

package/src/core/passes.ts

@@ -45,9 +45,12 @@ export function getCreditPackProgram(agent: AgentRecord): CreditPackProgramInfo
   return creditPacks ?? null;
 }
 
-export async function getCreditPackInventory(agentId: string): Promise<CreditPackInventory | null> {
+export async function getCreditPackInventory(agentId: string, method?: string): Promise<CreditPackInventory | null> {
   try {
-    return await apiGet<CreditPackInventory>(`/agents/${agentId}/credit-packs`, { ensureConsumerPrincipal: true });
+    return await apiGet<CreditPackInventory>(`/agents/${agentId}/credit-packs`, {
+      ensureConsumerPrincipal: true,
+      principalMethod: method,
+    });
   } catch {
     return null;
   }

package/src/core/payments.ts

@@ -21,6 +21,15 @@ import {
 } from "./config.js";
 import type { AgentRecord } from "./types.js";
 
+// Feature flag: disable card payment for launch. Flip to true once Stripe
+// approves the live SPT issuer. Config/card state is still persisted so this
+// can be re-enabled without reconfiguring wallets.
+const ENABLE_CARD_PAYMENT = false;
+
+export function isCardPaymentEnabled(): boolean {
+  return ENABLE_CARD_PAYMENT;
+}
+
 // Cache per wallet+chain combo to avoid re-initializing
 const fetchCache = new Map<string, typeof fetch>();
 const REGISTRY_METHOD_MAP: Record<string, string> = {
@@ -68,7 +77,7 @@ async function initEvmMppForChain(
   chain: "tempo" | "base",
 ): Promise<typeof fetch | null> {
   try {
-    const { Mppx, tempo } = await import("mppx/client");
+    const { Mppx } = await import("mppx/client");
     let account;
 
     if (wallet.keyType === "ows" && wallet.owsWalletId) {
@@ -83,13 +92,14 @@ async function initEvmMppForChain(
 
     const methods = [];
     if (chain === "tempo") {
-      methods.push(tempo({ account }));
+      const { tempoChargeClient } = await import("./tempo-charge.js");
+      methods.push(tempoChargeClient({ account }));
     } else {
       const { baseChargeClient } = await import("./base-charge.js");
       methods.push(baseChargeClient({ account }));
     }
 
-    const mppx = Mppx.create({ methods: methods as any });
+    const mppx = Mppx.create({ methods: methods as any, polyfill: false });
     return mppx.fetch.bind(mppx) as typeof fetch;
   } catch {
     return null;
@@ -106,6 +116,7 @@ async function initSolanaMpp(wallet: WalletEntry): Promise<typeof fetch | null>
     const { solanaChargeClient } = await import("./solana-charge.js");
     const mppx = Mppx.create({
       methods: [solanaChargeClient({ wallet })] as any,
+      polyfill: false,
     });
     return mppx.fetch.bind(mppx) as typeof fetch;
   } catch {
@@ -146,6 +157,7 @@ async function initCard(): Promise<typeof fetch | null> {
           return spt;
         },
       })] as any,
+      polyfill: false,
     });
     return mppx.fetch.bind(mppx) as typeof fetch;
   } catch {
@@ -177,6 +189,9 @@ async function initForChain(wallet: WalletEntry, chain: string): Promise<typeof
 export async function getPaymentFetch(method?: string): Promise<typeof fetch> {
   // Card payment
   if (method === "card") {
+    if (!ENABLE_CARD_PAYMENT) {
+      throw new Error('Card payments are temporarily unavailable. Use a crypto wallet (tempo, base, or solana).');
+    }
     const ck = cardCacheKey();
     clearStaleCardCache(ck ?? undefined);
     if (!ck) {
@@ -286,14 +301,14 @@ export function getConfiguredMethods(): string[] {
     }
   }
 
-  // Add card if configured
-  if (getCardConfig()) {
+  // Add card if configured (gated for launch)
+  if (ENABLE_CARD_PAYMENT && getCardConfig()) {
     methods.push("card");
   }
 
-  // Respect defaultPaymentMethod — move it to front of list
+  // Respect defaultPaymentMethod — move it to front of list (ignore card when disabled)
   const defaultMethod = getConfig().defaultPaymentMethod;
-  if (defaultMethod) {
+  if (defaultMethod && (defaultMethod !== "card" || ENABLE_CARD_PAYMENT)) {
     const idx = methods.indexOf(defaultMethod);
     if (idx > 0) {
       methods.splice(idx, 1);

package/src/core/principal.ts

@@ -1,4 +1,10 @@
-import { addWallet, getDefaultWallet, getWallets, type WalletEntry } from "./config.js";
+import {
+  addWallet,
+  getDefaultWallet,
+  getWallets,
+  resolveWalletAndChain,
+  type WalletEntry,
+} from "./config.js";
 import { getWalletAddress } from "./payments.js";
 import {
   createOwsWallet,
@@ -39,6 +45,12 @@ async function walletPrincipal(wallet: WalletEntry): Promise<string | null> {
   return null;
 }
 
+async function principalForChain(chain: string): Promise<string | null> {
+  const address = await getWalletAddress(chain);
+  if (!address) return null;
+  return principalFromAddress(address, chain === "solana" ? "solana" : "evm");
+}
+
 function preferredWallets(): WalletEntry[] {
   const wallets = getWallets();
   const defaultWallet = getDefaultWallet();
@@ -115,6 +127,21 @@ export async function getConsumerPrincipal(): Promise<string | null> {
   return null;
 }
 
+export async function getBaseRebatePrincipal(): Promise<string | null> {
+  return (await principalForChain("base")) ?? principalForChain("tempo");
+}
+
+export async function getConsumerPrincipalForMethod(method?: string): Promise<string | null> {
+  if (!method || method === "card") {
+    return getConsumerPrincipal();
+  }
+
+  const resolved = resolveWalletAndChain(method);
+  if (!resolved) return null;
+
+  return principalForChain(resolved.chain);
+}
+
 export async function ensureConsumerPrincipal(): Promise<string> {
   const existing = await getConsumerPrincipal();
   if (existing) return existing;
@@ -126,3 +153,17 @@ export async function ensureConsumerPrincipal(): Promise<string> {
   }
   return principal;
 }
+
+export async function ensureConsumerPrincipalForMethod(method?: string): Promise<string> {
+  const existing = await getConsumerPrincipalForMethod(method);
+  if (existing) return existing;
+
+  if (method && method !== "card") {
+    throw new Error(
+      `Could not derive a consumer principal for payment method "${method}". ` +
+      "Check wallet_status and confirm that chain is configured for the active wallet.",
+    );
+  }
+
+  return ensureConsumerPrincipal();
+}

package/src/core/settings.ts

@@ -0,0 +1,36 @@
+import { getApiUrl } from "./config.js";
+
+export interface ChainSettings {
+  chainId: number | string;
+  usdc: string;
+  rpcUrl: string;
+  explorer?: string;
+}
+
+export interface PublicSettings {
+  network: "testnet" | "mainnet";
+  stripe: { mode: "test" | "live" };
+  chains: {
+    tempo: ChainSettings;
+    base: ChainSettings;
+    solana: ChainSettings & { cluster: "mainnet-beta" | "devnet" };
+  };
+}
+
+let cache: { data: PublicSettings; expiresAt: number } | null = null;
+const TTL_MS = 5 * 60 * 1000;
+
+export async function getSettings(): Promise<PublicSettings | null> {
+  const now = Date.now();
+  if (cache && cache.expiresAt > now) return cache.data;
+
+  try {
+    const res = await fetch(`${getApiUrl()}/settings`);
+    if (!res.ok) return cache?.data ?? null;
+    const data = await res.json() as PublicSettings;
+    cache = { data, expiresAt: now + TTL_MS };
+    return data;
+  } catch {
+    return cache?.data ?? null;
+  }
+}