@agentwonderland/mcp 0.1.25 → 0.1.27

package/dist/tools/solve.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
 import { getOrCreatePendingCardSetup, formatCardSetupBlocks } from "../core/card-setup.js";
-import { getCompatiblePaymentMethods, hasWalletConfigured, getConfiguredMethods, getAcceptedPaymentMethods, getWalletAddress, normalizePaymentMethod, toRegistryPaymentMethod, } from "../core/payments.js";
+import { getCompatiblePaymentMethods, hasWalletConfigured, getConfiguredMethods, getAcceptedPaymentMethods, getWalletAddress, normalizePaymentMethod, toRegistryPaymentMethod, isCardPaymentEnabled, } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { agentList, formatRunResult } from "../core/formatters.js";
 import { canSpend, recordSpend, requiresPolicyConfirmation } from "../core/spend-policy.js";
@@ -11,9 +11,9 @@ import { formatPaymentLabel, formatSolveConfirmationCommand, makeSolvePendingKey
 import { getActiveCreditPack, getCreditPackInventory, getCreditPackProgram } from "../core/passes.js";
 const POLL_INTERVAL_MS = 3000;
 const POLL_MAX_MS = 120000;
-async function pollSolveJob(jobId) {
+async function pollSolveJob(jobId, paymentMethod) {
     const deadline = Date.now() + POLL_MAX_MS;
-    const walletAddress = await getWalletAddress();
+    const walletAddress = await getWalletAddress(paymentMethod);
     const walletParam = walletAddress ? `?wallet=${walletAddress}` : "";
     while (Date.now() < deadline) {
         await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
@@ -106,29 +106,41 @@ export function registerSolveTools(server) {
             .string()
             .trim()
             .min(1)
-            .describe("Required payment method — wallet ID, chain name (tempo, base, etc.), or 'card'. Use wallet_status to see configured options."),
+            .optional()
+            .describe("Payment method — wallet ID, chain name (tempo, base, etc.), or 'card'. Auto-detected if omitted."),
         confirmed: z
             .boolean()
             .optional()
             .describe("Set to true to confirm spending after seeing the price quote."),
     }, async ({ intent, input, budget, pay_with, confirmed }) => {
         if (!hasWalletConfigured()) {
-            try {
-                const { url } = await getOrCreatePendingCardSetup();
-                return multiText(...formatCardSetupBlocks(url));
+            if (isCardPaymentEnabled()) {
+                try {
+                    const { url } = await getOrCreatePendingCardSetup();
+                    return multiText(...formatCardSetupBlocks(url));
+                }
+                catch {
+                    // Fall through to the setup message below.
+                }
             }
-            catch {
-                return text("No payment method configured.\n\n" +
-                    "To add a credit card: wallet_setup({ action: \"add-card\" })\n" +
-                    "To use crypto: wallet_setup({ action: \"create\" })");
+            const setupLines = [
+                "No payment method configured.",
+                "",
+                "Supported rails: Tempo USDC, Base USDC, Solana USDC.",
+                "Run wallet_setup({ action: \"create\" }) to create a crypto wallet,",
+                "or wallet_setup({ action: \"import\" }) with an existing key.",
+            ];
+            if (isCardPaymentEnabled()) {
+                setupLines.push("", "Or wallet_setup({ action: \"add-card\" }) to connect a credit card.");
             }
+            return text(setupLines.join("\n"));
         }
         const pendingKey = makeSolvePendingKey(intent, input, budget);
         const pending = pendingSolves.get(pendingKey);
         const configuredMethods = getConfiguredMethods();
-        const requestedMethod = pay_with;
-        const normalizedRequestedMethod = normalizePaymentMethod(requestedMethod);
-        if (!normalizedRequestedMethod) {
+        const requestedMethod = pay_with ?? pending?.method;
+        const normalizedRequestedMethod = requestedMethod ? normalizePaymentMethod(requestedMethod) : null;
+        if (requestedMethod && !normalizedRequestedMethod) {
             return text(`Payment method "${requestedMethod}" is not configured.\n\n` +
                 "Use wallet_status to review your current payment methods.");
         }
@@ -156,13 +168,16 @@ export function registerSolveTools(server) {
             const cost = result.cost;
             const usedCreditPack = result.consumption_mode === "credit_pack";
             const tipMsg = result.feedback_token ? await autoTip(jobId, agentId, agentName, result.feedback_token) : "";
-            return multiText(formatRunResult(result), feedbackAsk(jobId, agentId, usedCreditPack ? undefined : cost, tipMsg));
+            const header = agentName ? [`Matched agent: ${agentName}`, ""].join("\n") : "";
+            return multiText(header + formatRunResult(result), feedbackAsk(jobId, agentId, usedCreditPack ? undefined : cost, tipMsg));
         }
         catch (err) {
-            const isAuthError = err instanceof Error &&
-                "status" in err &&
-                err.status === 401;
-            if (!isAuthError || !hasWalletConfigured())
+            const status = err instanceof Error &&
+                "status" in err
+                ? err.status
+                : undefined;
+            const isRecoverableDirectSolveError = status === 401 || status === 402;
+            if (!isRecoverableDirectSolveError || !hasWalletConfigured())
                 throw err;
         }
         const params = new URLSearchParams({ q: intent, limit: "5" });
@@ -182,15 +197,19 @@ export function registerSolveTools(server) {
             return price <= budget;
         });
         const selected = affordable[0] ?? agents[0];
-        const activeCreditPack = await getCreditPackInventory(selected.id).then(getActiveCreditPack);
+        const activeCreditPack = await getCreditPackInventory(selected.id, requestedMethod).then(getActiveCreditPack);
         const compatibleMethods = getCompatiblePaymentMethods(selected, configuredMethods);
-        if (!compatibleMethods.includes(normalizedRequestedMethod)) {
+        if (normalizedRequestedMethod && !compatibleMethods.includes(normalizedRequestedMethod)) {
             return text(`The best matching agent cannot be paid with "${requestedMethod}".\n\n` +
                 `Available payment methods for ${selected.name}: ${compatibleMethods.join(", ") || "none"}.\n` +
                 "Choose another payment method or refine your search.");
         }
-        const method = resolveConfirmationMethod(pay_with, pending?.method, compatibleMethods);
-        const spendCheckMethod = method ?? normalizedRequestedMethod;
+        if (!activeCreditPack && compatibleMethods.length === 0) {
+            return text(`No compatible payment methods are configured for ${selected.name}.\n\n` +
+                "Use wallet_status to review your current payment methods.");
+        }
+        const method = resolveConfirmationMethod(requestedMethod, pending?.method, compatibleMethods);
+        const spendCheckMethod = method ?? normalizedRequestedMethod ?? compatibleMethods[0];
         const selectedPrice = parseFloat(selected.pricePerRunUsd ?? "0.01");
         const estimatedCost = selectedPrice;
         const needsPolicyConfirmation = !activeCreditPack && requiresPolicyConfirmation(spendCheckMethod, estimatedCost);
@@ -247,8 +266,9 @@ export function registerSolveTools(server) {
         catch (err) {
             const apiErr = err;
             if (apiErr?.status === 402) {
+                const reason = apiErr.message ? `Payment failed: ${apiErr.message}` : "Payment failed — wallet may not have enough funds or the selected method was rejected.";
                 return text([
-                    "Payment failed — your wallet may not have enough funds or the selected method was rejected.",
+                    reason,
                     "",
                     "Check your balance and try again.",
                     "Use wallet_status to check your current payment methods.",
@@ -268,7 +288,7 @@ export function registerSolveTools(server) {
             storeFeedbackToken(jobId, result.feedback_token, agentId);
         }
         if (status === "processing") {
-            const pollResult = await pollSolveJob(jobId);
+            const pollResult = await pollSolveJob(jobId, method);
             if (pollResult.status === "completed") {
                 const asyncFormatted = formatRunResult({
                     ...result,

package/dist/tools/wallet.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { getWallets, getCardConfig, setCardConfig, addWallet, getPendingCardSetupToken, getSpendPolicy, setSpendPolicy, } from "../core/config.js";
-import { getWalletAddress } from "../core/payments.js";
+import { getWalletAddress, isCardPaymentEnabled } from "../core/payments.js";
+import { fetchUsdcBalance } from "../core/balances.js";
+import { getSettings } from "../core/settings.js";
 import { getOrCreatePendingCardSetup, formatCardSetupBlocks, getCardCapabilities, pollCardSetup, } from "../core/card-setup.js";
 import { isOwsAvailable, createOwsWallet, importKeyToOws, listOwsWallets, listOwsWalletsByChain, } from "../core/ows-adapter.js";
 import { ensureConsumerPrincipal, getConsumerPrincipal } from "../core/principal.js";
@@ -17,18 +19,33 @@ export function registerWalletTools(server) {
         if (wallets.length === 0 && !card && !pendingCardSetupToken) {
             return text("No payment methods configured.\nUse wallet_setup to create or import a wallet.");
         }
-        const lines = ["Payment methods:"];
+        const settings = await getSettings();
+        const networkLabel = settings ? ` (${settings.network})` : "";
+        const lines = [`Payment methods${networkLabel}:`];
         for (const w of wallets) {
             const label = w.label ? ` (${w.label})` : "";
             const storage = w.keyType === "ows" ? " [encrypted]" : " [plaintext]";
-            const chainAddresses = await Promise.all(w.chains.map(async (chainName) => {
+            const chainLines = await Promise.all(w.chains.map(async (chainName) => {
                 const addr = await getWalletAddress(chainName);
-                return `${chainName}: ${addr ?? "unknown"}`;
+                if (!addr)
+                    return `${chainName}: unknown`;
+                let balanceStr = "";
+                if (chainName === "tempo" || chainName === "base" || chainName === "solana") {
+                    const balance = await fetchUsdcBalance(chainName, addr);
+                    if (balance !== null) {
+                        const num = Number(balance);
+                        balanceStr = `   ${Number.isFinite(num) ? num.toFixed(4).replace(/\.?0+$/, "") : balance} USDC`;
+                    }
+                }
+                return `${chainName}: ${addr}${balanceStr}`;
             }));
-            lines.push(`  ${w.id}${label}${storage}: ${chainAddresses.join(" | ")}`);
+            lines.push(`  ${w.id}${label}${storage}:`);
+            for (const line of chainLines)
+                lines.push(`    ${line}`);
         }
-        if (card) {
-            lines.push(`  Card: ${card.brand} ****${card.last4}`);
+        if (card && isCardPaymentEnabled()) {
+            const stripeMode = settings?.stripe.mode === "test" ? " [Stripe test mode]" : "";
+            lines.push(`  Card: ${card.brand} ****${card.last4}${stripeMode}`);
             const capabilities = await getCardCapabilities();
             if (capabilities.spt_status === "enabled") {
                 lines.push("  Card MPP: ready");
@@ -48,11 +65,11 @@ export function registerWalletTools(server) {
         }
         return text(lines.join("\n"));
     });
-    // ── wallet_setup (NEW) ──────────────────────────────────────────
-    server.tool("wallet_setup", "Set up or manage payment methods. Options: 'add-card' to connect a credit/debit card (recommended), 'remove-card' to disconnect a card, 'create' a crypto wallet, or 'import' an existing key. For crypto wallet changes (removal, key rotation), direct users to edit their config files manually — never handle private keys programmatically.", {
+    // ── wallet_setup ────────────────────────────────────────────────
+    server.tool("wallet_setup", "Set up or manage a payment wallet. 'create' makes a new encrypted crypto wallet (OWS); 'import' takes an existing private key. Tempo/Base share one EVM key — a single wallet covers both. Solana uses a separate ed25519 key. For crypto wallet deletion or key rotation, direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually; never handle key material programmatically.", {
         action: z
             .enum(["create", "import", "add-card", "remove-card"])
-            .describe("'add-card' to connect a card, 'remove-card' to disconnect it, 'create' a crypto wallet, or 'import' an existing key"),
+            .describe("'create' a crypto wallet (recommended), 'import' an existing key, 'add-card'/'remove-card' for credit card (card-backed MPP availability depends on Stripe SPT)"),
         name: z
             .string()
             .optional()
@@ -62,10 +79,13 @@ export function registerWalletTools(server) {
             .optional()
             .describe("Private key hex string (required for 'import', ignored for 'create')"),
         chain: z.enum(["tempo", "base", "solana"]).optional()
-            .describe("Primary chain (default: tempo). Solana uses an OWS wallet plus Stripe deposit-mode USDC."),
+            .describe("Primary chain (default: tempo). Tempo/Base use a shared EVM wallet; Solana uses a separate OWS wallet."),
     }, async ({ action, name, key, chain }) => {
         // ── Card setup flow ──────────────────────────────────────
         if (action === "add-card") {
+            if (!isCardPaymentEnabled()) {
+                return text("Card payments are temporarily unavailable. Use wallet_setup({ action: \"create\" }) for a crypto wallet instead.");
+            }
             const existing = getCardConfig();
             if (existing) {
                 return text(`Card already connected: ${existing.brand} ****${existing.last4}\n\nTo replace it, remove the current card first.`);
@@ -257,8 +277,8 @@ export function registerWalletTools(server) {
         }
     });
     // ── wallet_set_policy (NEW) ─────────────────────────────────────
-    server.tool("wallet_set_policy", "Set spending limits on a wallet to control agent costs. Limits reset daily.", {
-        wallet_id: z.string().describe("Wallet ID to set policy on"),
+    server.tool("wallet_set_policy", "Set client-side spending limits on a wallet to control agent costs in this MCP client. Limits reset daily.", {
+        wallet_id: z.string().describe("Wallet ID to set local policy on"),
         max_per_tx: z
             .number()
             .positive()
@@ -306,10 +326,10 @@ export function registerWalletTools(server) {
             policies.push(`Require confirmation above: $${nextPolicy.requireConfirmationAboveUsd.toFixed(2)}`);
         }
         return text([
-            `Spending policy set for wallet "${wallet_id}":`,
+            `Local spending policy set for wallet "${wallet_id}":`,
             ...policies.map((p) => `  ${p}`),
             "",
-            "Policy will be enforced on all future transactions from this wallet.",
+            "Policy is stored in this MCP client's local config and enforced on future transactions from this wallet on this client.",
         ].join("\n"));
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentwonderland/mcp",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "description": "MCP server for the Agent Wonderland AI agent marketplace",
   "bin": {
@@ -25,7 +25,7 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",
-    "mppx": "^0.4.9",
+    "mppx": "^0.5.10",
     "qrcode": "^1.5.4",
     "viem": "^2.47.6",
     "zod": "^3.24.0"

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

@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  mockGetApiUrl,
+  mockGetApiKey,
+  mockGetPaymentFetch,
+  mockEnsureConsumerPrincipalForMethod,
+  mockGetConsumerPrincipalForMethod,
+  mockGetBaseRebatePrincipal,
+  mockPaymentFetch,
+} = vi.hoisted(() => ({
+  mockGetApiUrl: vi.fn(),
+  mockGetApiKey: vi.fn(),
+  mockGetPaymentFetch: vi.fn(),
+  mockEnsureConsumerPrincipalForMethod: vi.fn(),
+  mockGetConsumerPrincipalForMethod: vi.fn(),
+  mockGetBaseRebatePrincipal: vi.fn(),
+  mockPaymentFetch: vi.fn(),
+}));
+
+vi.mock("../config.js", () => ({
+  getApiUrl: () => mockGetApiUrl(),
+  getApiKey: () => mockGetApiKey(),
+}));
+
+vi.mock("../payments.js", () => ({
+  getPaymentFetch: (...args: unknown[]) => mockGetPaymentFetch(...args),
+}));
+
+vi.mock("../principal.js", () => ({
+  ensureConsumerPrincipal: vi.fn(),
+  ensureConsumerPrincipalForMethod: (...args: unknown[]) => mockEnsureConsumerPrincipalForMethod(...args),
+  getConsumerPrincipal: vi.fn(),
+  getConsumerPrincipalForMethod: (...args: unknown[]) => mockGetConsumerPrincipalForMethod(...args),
+  getBaseRebatePrincipal: (...args: unknown[]) => mockGetBaseRebatePrincipal(...args),
+}));
+
+describe("api-client headers", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetApiUrl.mockReturnValue("https://api.agentwonderland.test");
+    mockGetApiKey.mockReturnValue(null);
+    mockGetPaymentFetch.mockResolvedValue(mockPaymentFetch);
+    mockEnsureConsumerPrincipalForMethod.mockResolvedValue(
+      "did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+    );
+    mockGetConsumerPrincipalForMethod.mockResolvedValue(
+      "did:pkh:eip155:8453:0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    );
+    mockGetBaseRebatePrincipal.mockResolvedValue(
+      "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    );
+    mockPaymentFetch.mockResolvedValue(new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    }));
+  });
+
+  it("includes the Base rebate principal alongside the method-specific consumer principal", async () => {
+    const { apiPostWithPayment } = await import("../api-client.js");
+
+    await apiPostWithPayment("/agents/agent-1/run", { input: { text: "hello" } }, "solana");
+
+    expect(mockPaymentFetch).toHaveBeenCalledWith(
+      "https://api.agentwonderland.test/agents/agent-1/run",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          "X-AW-Consumer-Principal":
+            "did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+          "X-AW-Rebate-Principal":
+            "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        }),
+      }),
+    );
+  });
+});

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),