@agentwonderland/mcp 0.1.51 → 0.1.52

package/dist/core/__tests__/api-client.test.js

@@ -1,9 +1,11 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-const { mockGetApiUrl, mockGetApiKey, mockGetPaymentFetch, mockEnsureConsumerPrincipalForMethod, mockGetConsumerPrincipalForMethod, mockGetBaseRebatePrincipal, mockPaymentFetch, } = vi.hoisted(() => ({
+import { MCP_PACKAGE_VERSION } from "../version.js";
+const { mockGetApiUrl, mockGetApiKey, mockGetPaymentFetch, mockEnsureConsumerPrincipalForMethod, mockEnsureBaseRebatePrincipal, mockGetConsumerPrincipalForMethod, mockGetBaseRebatePrincipal, mockPaymentFetch, } = vi.hoisted(() => ({
     mockGetApiUrl: vi.fn(),
     mockGetApiKey: vi.fn(),
     mockGetPaymentFetch: vi.fn(),
     mockEnsureConsumerPrincipalForMethod: vi.fn(),
+    mockEnsureBaseRebatePrincipal: vi.fn(),
     mockGetConsumerPrincipalForMethod: vi.fn(),
     mockGetBaseRebatePrincipal: vi.fn(),
     mockPaymentFetch: vi.fn(),
@@ -17,6 +19,7 @@ vi.mock("../payments.js", () => ({
 }));
 vi.mock("../principal.js", () => ({
     ensureConsumerPrincipal: vi.fn(),
+    ensureBaseRebatePrincipal: (...args) => mockEnsureBaseRebatePrincipal(...args),
     ensureConsumerPrincipalForMethod: (...args) => mockEnsureConsumerPrincipalForMethod(...args),
     getConsumerPrincipal: vi.fn(),
     getConsumerPrincipalForMethod: (...args) => mockGetConsumerPrincipalForMethod(...args),
@@ -31,6 +34,7 @@ describe("api-client headers", () => {
         mockEnsureConsumerPrincipalForMethod.mockResolvedValue("did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF");
         mockGetConsumerPrincipalForMethod.mockResolvedValue("did:pkh:eip155:8453:0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
         mockGetBaseRebatePrincipal.mockResolvedValue("did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
+        mockEnsureBaseRebatePrincipal.mockResolvedValue("did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
         mockPaymentFetch.mockResolvedValue(new Response(JSON.stringify({ ok: true }), {
             status: 200,
             headers: { "content-type": "application/json" },
@@ -46,7 +50,7 @@ describe("api-client headers", () => {
                 "X-AW-Consumer-Principal": "did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
                 "X-AW-Rebate-Principal": "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
                 "X-AW-Surface": "mcp",
-                "X-AW-MCP-Version": "0.1.44",
+                "X-AW-MCP-Version": MCP_PACKAGE_VERSION,
                 "X-AW-MCP-Tool": "run_agent",
                 "X-AW-MCP-Action": "execute",
             }),

package/dist/core/__tests__/principal.test.js

@@ -106,6 +106,19 @@ describe("consumer principal helpers", () => {
         expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
         expect(state.addedWallets).toHaveLength(1);
     });
+    it("creates an EVM identity for Link payments when only a Solana wallet exists", async () => {
+        state.wallets = [
+            { id: "sol-wallet", keyType: "ows", owsWalletId: "ows-sol", chains: ["solana"], defaultChain: "solana" },
+        ];
+        state.addresses = {
+            "sol-wallet": "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+        };
+        const { ensureConsumerPrincipalForMethod } = await import("../principal.js");
+        const principal = await ensureConsumerPrincipalForMethod("link");
+        expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
+        expect(state.addedWallets).toHaveLength(1);
+        expect(state.addedWallets[0]?.chains).toEqual(["tempo", "base"]);
+    });
     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" },
@@ -119,4 +132,16 @@ describe("consumer principal helpers", () => {
         const principal = await getBaseRebatePrincipal();
         expect(principal).toBe("did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
     });
+    it("ensures a Base rebate principal even when the default wallet is Solana-only", async () => {
+        state.wallets = [
+            { id: "sol-wallet", keyType: "ows", owsWalletId: "ows-sol", chains: ["solana"], defaultChain: "solana" },
+        ];
+        state.addresses = {
+            "sol-wallet": "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+        };
+        const { ensureBaseRebatePrincipal } = await import("../principal.js");
+        const principal = await ensureBaseRebatePrincipal();
+        expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
+        expect(state.addedWallets).toHaveLength(1);
+    });
 });

package/dist/core/api-client.js

@@ -1,6 +1,6 @@
 import { getApiUrl, getApiKey } from "./config.js";
 import { getPaymentFetch } from "./payments.js";
-import { getBaseRebatePrincipal, ensureConsumerPrincipalForMethod, getConsumerPrincipalForMethod, } from "./principal.js";
+import { getBaseRebatePrincipal, ensureBaseRebatePrincipal, ensureConsumerPrincipalForMethod, getConsumerPrincipalForMethod, } from "./principal.js";
 import { MCP_PACKAGE_VERSION } from "./version.js";
 // ── Error class ────────────────────────────────────────────────────
 export class ApiError extends Error {
@@ -49,7 +49,9 @@ async function buildHeaders(path, method, options) {
     if (principal) {
         headers["X-AW-Consumer-Principal"] = principal;
     }
-    const rebatePrincipal = await getBaseRebatePrincipal();
+    const rebatePrincipal = options?.ensureConsumerPrincipal
+        ? await ensureBaseRebatePrincipal()
+        : await getBaseRebatePrincipal();
     if (rebatePrincipal) {
         headers["X-AW-Rebate-Principal"] = rebatePrincipal;
     }

package/dist/core/principal.d.ts

@@ -1,5 +1,6 @@
 export declare function getConsumerPrincipal(): Promise<string | null>;
 export declare function getBaseRebatePrincipal(): Promise<string | null>;
+export declare function ensureBaseRebatePrincipal(): Promise<string>;
 export declare function getConsumerPrincipalForMethod(method?: string): Promise<string | null>;
 export declare function ensureConsumerPrincipal(): Promise<string>;
 export declare function ensureConsumerPrincipalForMethod(method?: string): Promise<string>;

package/dist/core/principal.js

@@ -59,6 +59,40 @@ async function createFallbackIdentityWallet() {
     addWallet(entry);
     return entry;
 }
+async function ensureEvmIdentityWallet() {
+    const existing = preferredWallets().find((wallet) => walletSupportsEvm(wallet));
+    if (existing)
+        return existing;
+    if (await isOwsAvailable()) {
+        const existingOwsWallets = await listOwsWallets();
+        const linked = existingOwsWallets[0];
+        if (linked) {
+            const entry = {
+                id: linked.name,
+                keyType: "ows",
+                owsWalletId: linked.id,
+                chains: ["tempo", "base"],
+                defaultChain: "base",
+                label: linked.name,
+            };
+            addWallet(entry);
+            return entry;
+        }
+        const walletName = `aw-identity-${Date.now()}`;
+        const created = await createOwsWallet(walletName, "evm");
+        const entry = {
+            id: walletName,
+            keyType: "ows",
+            owsWalletId: created.walletId,
+            chains: ["tempo", "base"],
+            defaultChain: "base",
+            label: AUTO_IDENTITY_LABEL,
+        };
+        addWallet(entry);
+        return entry;
+    }
+    return createFallbackIdentityWallet();
+}
 async function ensureIdentityWallet() {
     const wallets = preferredWallets();
     const existing = wallets.find((wallet) => walletSupportsEvm(wallet) || walletSupportsSolana(wallet));
@@ -105,9 +139,20 @@ export async function getConsumerPrincipal() {
 export async function getBaseRebatePrincipal() {
     return (await principalForChain("base")) ?? principalForChain("tempo");
 }
+export async function ensureBaseRebatePrincipal() {
+    const existing = await getBaseRebatePrincipal();
+    if (existing)
+        return existing;
+    const wallet = await ensureEvmIdentityWallet();
+    const principal = await walletPrincipal(wallet);
+    if (!principal || !principal.startsWith(`did:pkh:eip155:${BASE_CHAIN_ID}:`)) {
+        throw new Error("Could not derive a Base rebate principal from the configured identity wallet.");
+    }
+    return principal;
+}
 export async function getConsumerPrincipalForMethod(method) {
     if (!method || method === "card" || method === "link") {
-        return getConsumerPrincipal();
+        return getBaseRebatePrincipal();
     }
     const resolved = resolveWalletAndChain(method);
     if (!resolved)
@@ -129,6 +174,9 @@ export async function ensureConsumerPrincipalForMethod(method) {
     const existing = await getConsumerPrincipalForMethod(method);
     if (existing)
         return existing;
+    if (!method || method === "card" || method === "link") {
+        return ensureBaseRebatePrincipal();
+    }
     if (method && method !== "card" && method !== "link") {
         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.");

package/dist/index.js

@@ -12,6 +12,7 @@ import { registerWalletTools } from "./tools/wallet.js";
 import { registerFavoriteTools } from "./tools/favorites.js";
 import { registerTipTools } from "./tools/tip.js";
 import { registerPassTools } from "./tools/passes.js";
+import { registerRebateTools } from "./tools/rebates.js";
 import { registerUploadTools } from "./tools/upload.js";
 import { registerProbeTools } from "./tools/probe.js";
 import { registerProviderTools } from "./tools/providers.js";
@@ -64,6 +65,7 @@ export async function startMcpServer() {
             "",
             "WALLET HYGIENE:",
             "- wallet_status shows per-chain USDC balance and the active network (mainnet vs testnet).",
+            "- rebate_status shows accrued, pending, paid, and blocked consumer rebates plus recent payout transactions.",
             "- To set up payments: wallet_setup({ action: \"start\" }). Link card/bank is recommended for most users.",
             "- To create or import a crypto wallet directly: wallet_setup({ action: \"create\" }) or { action: \"import\", key }.",
             "- NEVER delete or rotate keys programmatically. Direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually.",
@@ -80,6 +82,7 @@ export async function startMcpServer() {
     registerFavoriteTools(server);
     registerTipTools(server);
     registerPassTools(server);
+    registerRebateTools(server);
     registerUploadTools(server);
     registerProbeTools(server);
     registerProviderTools(server);

package/dist/tools/__tests__/rebates.test.d.ts

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

package/dist/tools/__tests__/rebates.test.js

@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const { mockApiGet } = vi.hoisted(() => ({
+    mockApiGet: vi.fn(),
+}));
+vi.mock("../../core/api-client.js", () => ({
+    apiGet: (...args) => mockApiGet(...args),
+}));
+async function getRebateStatusTool() {
+    const tools = new Map();
+    const server = {
+        tool: (name, _description, _schema, handler) => {
+            tools.set(name, handler);
+        },
+    };
+    const { registerRebateTools } = await import("../rebates.js");
+    registerRebateTools(server);
+    const tool = tools.get("rebate_status");
+    if (!tool)
+        throw new Error("rebate_status tool was not registered");
+    return tool;
+}
+function flattenText(result) {
+    return result.content.map((item) => item.text).join("\n");
+}
+describe("rebate_status tool", () => {
+    beforeEach(() => {
+        vi.resetModules();
+        mockApiGet.mockReset();
+    });
+    it("formats rebate balances and recent payouts", async () => {
+        mockApiGet.mockResolvedValueOnce({
+            consumer_principal: "did:pkh:eip155:8453:0xabc",
+            principal_type: "evm",
+            principal_value: "0xabc",
+            payout_address: "0xabc",
+            payout_chain: "base",
+            auto_payout_threshold_usd: "5.000000",
+            totals: {
+                lifetime_earned_usd: "2.500000",
+                pending_usd: "1.250000",
+                paid_usd: "1.000000",
+                blocked_usd: "0.250000",
+                total_count: 5,
+                pending_count: 2,
+                paid_count: 2,
+                blocked_count: 1,
+            },
+            by_source: [
+                { source_type: "job_execution", status: "earned", count: 2, rebate_usd: "1.250000" },
+            ],
+            recent_payouts: [
+                {
+                    id: "payout-1",
+                    status: "completed",
+                    amount_usd: "1.000000",
+                    earning_count: 2,
+                    tx_hash: "0xhash",
+                    processed_at: "2026-05-09T12:00:00.000Z",
+                },
+            ],
+        });
+        const tool = await getRebateStatusTool();
+        const result = await tool({});
+        const text = flattenText(result);
+        expect(mockApiGet).toHaveBeenCalledWith("/rebates/status", { ensureConsumerPrincipal: true });
+        expect(text).toContain("Lifetime earned: $2.5000 across 5 rebate(s)");
+        expect(text).toContain("Pending: $1.2500 across 2 rebate(s)");
+        expect(text).toContain("Auto payout: $3.7500 until the $5.0000 threshold");
+        expect(text).toContain("job execution / earned: $1.2500 (2)");
+        expect(text).toContain("completed: $1.0000 (2) tx=0xhash");
+    });
+});

package/dist/tools/__tests__/wallet.test.js

@@ -124,6 +124,7 @@ vi.mock("../../core/ows-adapter.js", () => ({
 }));
 vi.mock("../../core/principal.js", () => ({
     ensureConsumerPrincipal: async () => state.consumerPrincipal,
+    ensureConsumerPrincipalForMethod: async () => state.consumerPrincipal,
     getConsumerPrincipal: async () => state.consumerPrincipal,
 }));
 function resetState() {

package/dist/tools/index.d.ts

@@ -8,6 +8,7 @@ export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
 export { registerPassTools } from "./passes.js";
+export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";

package/dist/tools/index.js

@@ -8,6 +8,7 @@ export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
 export { registerPassTools } from "./passes.js";
+export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";

package/dist/tools/observability.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerObservabilityTools(server: McpServer): void;

package/dist/tools/observability.js

@@ -0,0 +1,20 @@
+import { apiPost } from "../core/api-client.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+export function registerObservabilityTools(server) {
+    server.tool("open_observability_dashboard", "Generate a secure one-click sign-in URL for the Agent Wonderland web observability dashboard. The dashboard shows your agent runs, spend, rebates, and recent activity.", {}, async () => {
+        const result = await apiPost("/observability/link", {}, { ensureConsumerPrincipal: true });
+        const lines = [
+            "Your secure observability link is ready:",
+            result.url,
+            "",
+            `Expires: ${result.expires_at}`,
+        ];
+        if (result.consumer_principal) {
+            lines.push(`Consumer principal: ${result.consumer_principal}`);
+        }
+        lines.push("", "Open the link in your browser to view usage metrics, spend, rebates, and recent runs.");
+        return text(lines.join("\n"));
+    });
+}

package/dist/tools/rebates.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRebateTools(server: McpServer): void;

package/dist/tools/rebates.js

@@ -0,0 +1,51 @@
+import { apiGet } from "../core/api-client.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+function money(value) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? `$${numeric.toFixed(4)}` : `$${value}`;
+}
+function sourceLabel(value) {
+    return value.replace(/_/g, " ");
+}
+export function registerRebateTools(server) {
+    server.tool("rebate_status", "Show your Agent Wonderland consumer rebate balance, payout threshold, blocked rebates, and recent payout transactions.", {}, async () => {
+        const status = await apiGet("/rebates/status", { ensureConsumerPrincipal: true });
+        const threshold = Number(status.auto_payout_threshold_usd);
+        const pending = Number(status.totals.pending_usd);
+        const remaining = Math.max(0, threshold - pending);
+        const lines = [
+            "Rebate status",
+            `Consumer principal: ${status.consumer_principal}`,
+            `Base payout address: ${status.payout_address ?? "not configured"}`,
+            "",
+            `Lifetime earned: ${money(status.totals.lifetime_earned_usd)} across ${status.totals.total_count} rebate(s)`,
+            `Paid out: ${money(status.totals.paid_usd)} across ${status.totals.paid_count} rebate(s)`,
+            `Pending: ${money(status.totals.pending_usd)} across ${status.totals.pending_count} rebate(s)`,
+            `Blocked: ${money(status.totals.blocked_usd)} across ${status.totals.blocked_count} rebate(s)`,
+        ];
+        if (Number.isFinite(threshold) && threshold > 0) {
+            lines.push(pending >= threshold
+                ? `Auto payout: eligible for the next processor run (threshold ${money(threshold)})`
+                : `Auto payout: ${money(remaining)} until the ${money(threshold)} threshold`);
+        }
+        if (status.by_source.length > 0) {
+            lines.push("", "By source:");
+            for (const row of status.by_source) {
+                lines.push(`  ${sourceLabel(row.source_type)} / ${row.status}: ${money(row.rebate_usd)} (${row.count})`);
+            }
+        }
+        if (status.recent_payouts.length > 0) {
+            lines.push("", "Recent payouts:");
+            for (const payout of status.recent_payouts.slice(0, 5)) {
+                const tx = payout.tx_hash ? ` tx=${payout.tx_hash}` : "";
+                lines.push(`  ${payout.status}: ${money(payout.amount_usd)} (${payout.earning_count})${tx}`);
+            }
+        }
+        if (!status.payout_address) {
+            lines.push("", "No Base payout address is configured, so new rebates may be blocked.");
+        }
+        return text(lines.join("\n"));
+    });
+}

package/dist/tools/wallet.js

@@ -6,7 +6,7 @@ import { getSettings } from "../core/settings.js";
 import { getOrCreatePendingCardSetup, formatCardSetupBlocks, getCardCapabilities, pollCardSetup, } from "../core/card-setup.js";
 import { getLinkCliAuthStatus, listLinkPaymentMethods, openLinkPaymentMethodAdd, startLinkCliLogin, } from "../core/link-cli.js";
 import { isOwsAvailable, createOwsWallet, importKeyToOws, listOwsWallets, listOwsWalletsByChain, installOws, platformSupportsOws, } from "../core/ows-adapter.js";
-import { ensureConsumerPrincipal, getConsumerPrincipal } from "../core/principal.js";
+import { ensureConsumerPrincipal, ensureConsumerPrincipalForMethod, getConsumerPrincipal } from "../core/principal.js";
 import { MCP_PACKAGE_VERSION } from "../core/version.js";
 function text(t) {
     return { content: [{ type: "text", text: t }] };
@@ -221,7 +221,7 @@ export function registerWalletTools(server) {
                     paymentMethodId: selected.id,
                     label: name ?? selected.label,
                 });
-                const principal = await ensureConsumerPrincipal();
+                const principal = await ensureConsumerPrincipalForMethod("link");
                 return text([
                     "Link payment method connected.",
                     `  Payment method: ${selected.label ?? selected.id}${selected.label ? ` (${selected.id})` : ""}`,
@@ -254,7 +254,7 @@ export function registerWalletTools(server) {
                     paymentMethodId: method.id,
                     label: method.label,
                 });
-                const principal = await ensureConsumerPrincipal();
+                const principal = await ensureConsumerPrincipalForMethod("link");
                 return text([
                     "Link payment method connected.",
                     `  Payment method: ${method.id}${method.label ? ` (${method.label})` : ""}`,
@@ -293,7 +293,7 @@ export function registerWalletTools(server) {
             if (pendingToken) {
                 const result = await pollCardSetup(pendingToken, 250);
                 if (result) {
-                    const principal = await ensureConsumerPrincipal();
+                    const principal = await ensureConsumerPrincipalForMethod("card");
                     return text(`Connected! ${result.brand} ****${result.last4} is ready for payments.\n\n` +
                         `Consumer principal: ${principal}`);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentwonderland/mcp",
-  "version": "0.1.51",
+  "version": "0.1.52",
   "type": "module",
   "description": "MCP server for the Agent Wonderland AI agent marketplace",
   "bin": {

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

@@ -1,10 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MCP_PACKAGE_VERSION } from "../version.js";
 
 const {
   mockGetApiUrl,
   mockGetApiKey,
   mockGetPaymentFetch,
   mockEnsureConsumerPrincipalForMethod,
+  mockEnsureBaseRebatePrincipal,
   mockGetConsumerPrincipalForMethod,
   mockGetBaseRebatePrincipal,
   mockPaymentFetch,
@@ -13,6 +15,7 @@ const {
   mockGetApiKey: vi.fn(),
   mockGetPaymentFetch: vi.fn(),
   mockEnsureConsumerPrincipalForMethod: vi.fn(),
+  mockEnsureBaseRebatePrincipal: vi.fn(),
   mockGetConsumerPrincipalForMethod: vi.fn(),
   mockGetBaseRebatePrincipal: vi.fn(),
   mockPaymentFetch: vi.fn(),
@@ -29,6 +32,7 @@ vi.mock("../payments.js", () => ({
 
 vi.mock("../principal.js", () => ({
   ensureConsumerPrincipal: vi.fn(),
+  ensureBaseRebatePrincipal: (...args: unknown[]) => mockEnsureBaseRebatePrincipal(...args),
   ensureConsumerPrincipalForMethod: (...args: unknown[]) => mockEnsureConsumerPrincipalForMethod(...args),
   getConsumerPrincipal: vi.fn(),
   getConsumerPrincipalForMethod: (...args: unknown[]) => mockGetConsumerPrincipalForMethod(...args),
@@ -50,6 +54,9 @@ describe("api-client headers", () => {
     mockGetBaseRebatePrincipal.mockResolvedValue(
       "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
     );
+    mockEnsureBaseRebatePrincipal.mockResolvedValue(
+      "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    );
     mockPaymentFetch.mockResolvedValue(new Response(JSON.stringify({ ok: true }), {
       status: 200,
       headers: { "content-type": "application/json" },
@@ -72,7 +79,7 @@ describe("api-client headers", () => {
           "X-AW-Rebate-Principal":
             "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
           "X-AW-Surface": "mcp",
-          "X-AW-MCP-Version": "0.1.44",
+          "X-AW-MCP-Version": MCP_PACKAGE_VERSION,
           "X-AW-MCP-Tool": "run_agent",
           "X-AW-MCP-Action": "execute",
         }),

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

@@ -137,6 +137,22 @@ describe("consumer principal helpers", () => {
     expect(state.addedWallets).toHaveLength(1);
   });
 
+  it("creates an EVM identity for Link payments when only a Solana wallet exists", async () => {
+    state.wallets = [
+      { id: "sol-wallet", keyType: "ows", owsWalletId: "ows-sol", chains: ["solana"], defaultChain: "solana" },
+    ];
+    state.addresses = {
+      "sol-wallet": "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+    };
+
+    const { ensureConsumerPrincipalForMethod } = await import("../principal.js");
+    const principal = await ensureConsumerPrincipalForMethod("link");
+
+    expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
+    expect(state.addedWallets).toHaveLength(1);
+    expect(state.addedWallets[0]?.chains).toEqual(["tempo", "base"]);
+  });
+
   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" },
@@ -152,4 +168,19 @@ describe("consumer principal helpers", () => {
 
     expect(principal).toBe("did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
   });
+
+  it("ensures a Base rebate principal even when the default wallet is Solana-only", async () => {
+    state.wallets = [
+      { id: "sol-wallet", keyType: "ows", owsWalletId: "ows-sol", chains: ["solana"], defaultChain: "solana" },
+    ];
+    state.addresses = {
+      "sol-wallet": "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+    };
+
+    const { ensureBaseRebatePrincipal } = await import("../principal.js");
+    const principal = await ensureBaseRebatePrincipal();
+
+    expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
+    expect(state.addedWallets).toHaveLength(1);
+  });
 });

package/src/core/api-client.ts

@@ -2,7 +2,7 @@ import { getApiUrl, getApiKey } from "./config.js";
 import { getPaymentFetch } from "./payments.js";
 import {
   getBaseRebatePrincipal,
-  ensureConsumerPrincipal,
+  ensureBaseRebatePrincipal,
   ensureConsumerPrincipalForMethod,
   getConsumerPrincipal,
   getConsumerPrincipalForMethod,
@@ -70,7 +70,9 @@ async function buildHeaders(path: string, method: string, options?: RequestOptio
     headers["X-AW-Consumer-Principal"] = principal;
   }
 
-  const rebatePrincipal = await getBaseRebatePrincipal();
+  const rebatePrincipal = options?.ensureConsumerPrincipal
+    ? await ensureBaseRebatePrincipal()
+    : await getBaseRebatePrincipal();
   if (rebatePrincipal) {
     headers["X-AW-Rebate-Principal"] = rebatePrincipal;
   }

package/src/core/principal.ts

@@ -80,6 +80,43 @@ async function createFallbackIdentityWallet(): Promise<WalletEntry> {
   return entry;
 }
 
+async function ensureEvmIdentityWallet(): Promise<WalletEntry> {
+  const existing = preferredWallets().find((wallet) => walletSupportsEvm(wallet));
+  if (existing) return existing;
+
+  if (await isOwsAvailable()) {
+    const existingOwsWallets = await listOwsWallets();
+    const linked = existingOwsWallets[0];
+    if (linked) {
+      const entry: WalletEntry = {
+        id: linked.name,
+        keyType: "ows",
+        owsWalletId: linked.id,
+        chains: ["tempo", "base"],
+        defaultChain: "base",
+        label: linked.name,
+      };
+      addWallet(entry);
+      return entry;
+    }
+
+    const walletName = `aw-identity-${Date.now()}`;
+    const created = await createOwsWallet(walletName, "evm");
+    const entry: WalletEntry = {
+      id: walletName,
+      keyType: "ows",
+      owsWalletId: created.walletId,
+      chains: ["tempo", "base"],
+      defaultChain: "base",
+      label: AUTO_IDENTITY_LABEL,
+    };
+    addWallet(entry);
+    return entry;
+  }
+
+  return createFallbackIdentityWallet();
+}
+
 async function ensureIdentityWallet(): Promise<WalletEntry> {
   const wallets = preferredWallets();
   const existing = wallets.find((wallet) => walletSupportsEvm(wallet) || walletSupportsSolana(wallet));
@@ -131,9 +168,21 @@ export async function getBaseRebatePrincipal(): Promise<string | null> {
   return (await principalForChain("base")) ?? principalForChain("tempo");
 }
 
+export async function ensureBaseRebatePrincipal(): Promise<string> {
+  const existing = await getBaseRebatePrincipal();
+  if (existing) return existing;
+
+  const wallet = await ensureEvmIdentityWallet();
+  const principal = await walletPrincipal(wallet);
+  if (!principal || !principal.startsWith(`did:pkh:eip155:${BASE_CHAIN_ID}:`)) {
+    throw new Error("Could not derive a Base rebate principal from the configured identity wallet.");
+  }
+  return principal;
+}
+
 export async function getConsumerPrincipalForMethod(method?: string): Promise<string | null> {
   if (!method || method === "card" || method === "link") {
-    return getConsumerPrincipal();
+    return getBaseRebatePrincipal();
   }
 
   const resolved = resolveWalletAndChain(method);
@@ -158,6 +207,10 @@ export async function ensureConsumerPrincipalForMethod(method?: string): Promise
   const existing = await getConsumerPrincipalForMethod(method);
   if (existing) return existing;
 
+  if (!method || method === "card" || method === "link") {
+    return ensureBaseRebatePrincipal();
+  }
+
   if (method && method !== "card" && method !== "link") {
     throw new Error(
       `Could not derive a consumer principal for payment method "${method}". ` +

package/src/index.ts

@@ -14,6 +14,7 @@ import { registerWalletTools } from "./tools/wallet.js";
 import { registerFavoriteTools } from "./tools/favorites.js";
 import { registerTipTools } from "./tools/tip.js";
 import { registerPassTools } from "./tools/passes.js";
+import { registerRebateTools } from "./tools/rebates.js";
 import { registerUploadTools } from "./tools/upload.js";
 import { registerProbeTools } from "./tools/probe.js";
 import { registerProviderTools } from "./tools/providers.js";
@@ -71,6 +72,7 @@ export async function startMcpServer(): Promise<void> {
         "",
         "WALLET HYGIENE:",
         "- wallet_status shows per-chain USDC balance and the active network (mainnet vs testnet).",
+        "- rebate_status shows accrued, pending, paid, and blocked consumer rebates plus recent payout transactions.",
         "- To set up payments: wallet_setup({ action: \"start\" }). Link card/bank is recommended for most users.",
         "- To create or import a crypto wallet directly: wallet_setup({ action: \"create\" }) or { action: \"import\", key }.",
         "- NEVER delete or rotate keys programmatically. Direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually.",
@@ -89,6 +91,7 @@ export async function startMcpServer(): Promise<void> {
   registerFavoriteTools(server);
   registerTipTools(server);
   registerPassTools(server);
+  registerRebateTools(server);
   registerUploadTools(server);
   registerProbeTools(server);
   registerProviderTools(server);

package/src/tools/__tests__/rebates.test.ts

@@ -0,0 +1,91 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type ToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+};
+
+const { mockApiGet } = vi.hoisted(() => ({
+  mockApiGet: vi.fn(),
+}));
+
+vi.mock("../../core/api-client.js", () => ({
+  apiGet: (...args: unknown[]) => mockApiGet(...args),
+}));
+
+async function getRebateStatusTool(): Promise<(args: Record<string, unknown>) => Promise<ToolResult>> {
+  const tools = new Map<string, (args: Record<string, unknown>) => Promise<ToolResult>>();
+  const server = {
+    tool: (
+      name: string,
+      _description: string,
+      _schema: unknown,
+      handler: (args: Record<string, unknown>) => Promise<ToolResult>,
+    ) => {
+      tools.set(name, handler);
+    },
+  } as unknown as McpServer;
+
+  const { registerRebateTools } = await import("../rebates.js");
+  registerRebateTools(server);
+
+  const tool = tools.get("rebate_status");
+  if (!tool) throw new Error("rebate_status tool was not registered");
+  return tool;
+}
+
+function flattenText(result: ToolResult): string {
+  return result.content.map((item) => item.text).join("\n");
+}
+
+describe("rebate_status tool", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mockApiGet.mockReset();
+  });
+
+  it("formats rebate balances and recent payouts", async () => {
+    mockApiGet.mockResolvedValueOnce({
+      consumer_principal: "did:pkh:eip155:8453:0xabc",
+      principal_type: "evm",
+      principal_value: "0xabc",
+      payout_address: "0xabc",
+      payout_chain: "base",
+      auto_payout_threshold_usd: "5.000000",
+      totals: {
+        lifetime_earned_usd: "2.500000",
+        pending_usd: "1.250000",
+        paid_usd: "1.000000",
+        blocked_usd: "0.250000",
+        total_count: 5,
+        pending_count: 2,
+        paid_count: 2,
+        blocked_count: 1,
+      },
+      by_source: [
+        { source_type: "job_execution", status: "earned", count: 2, rebate_usd: "1.250000" },
+      ],
+      recent_payouts: [
+        {
+          id: "payout-1",
+          status: "completed",
+          amount_usd: "1.000000",
+          earning_count: 2,
+          tx_hash: "0xhash",
+          processed_at: "2026-05-09T12:00:00.000Z",
+        },
+      ],
+    });
+
+    const tool = await getRebateStatusTool();
+    const result = await tool({});
+    const text = flattenText(result);
+
+    expect(mockApiGet).toHaveBeenCalledWith("/rebates/status", { ensureConsumerPrincipal: true });
+    expect(text).toContain("Lifetime earned: $2.5000 across 5 rebate(s)");
+    expect(text).toContain("Pending: $1.2500 across 2 rebate(s)");
+    expect(text).toContain("Auto payout: $3.7500 until the $5.0000 threshold");
+    expect(text).toContain("job execution / earned: $1.2500 (2)");
+    expect(text).toContain("completed: $1.0000 (2) tx=0xhash");
+  });
+});

package/src/tools/__tests__/wallet.test.ts

@@ -175,6 +175,7 @@ vi.mock("../../core/ows-adapter.js", () => ({
 
 vi.mock("../../core/principal.js", () => ({
   ensureConsumerPrincipal: async () => state.consumerPrincipal,
+  ensureConsumerPrincipalForMethod: async () => state.consumerPrincipal,
   getConsumerPrincipal: async () => state.consumerPrincipal,
 }));
 

package/src/tools/index.ts

@@ -8,6 +8,7 @@ export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
 export { registerPassTools } from "./passes.js";
+export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";

package/src/tools/rebates.ts

@@ -0,0 +1,102 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { apiGet } from "../core/api-client.js";
+
+type RebateStatus = {
+  consumer_principal: string;
+  principal_type: string;
+  principal_value: string;
+  payout_address: string | null;
+  payout_chain: string;
+  auto_payout_threshold_usd: string;
+  totals: {
+    lifetime_earned_usd: string;
+    pending_usd: string;
+    paid_usd: string;
+    blocked_usd: string;
+    total_count: number;
+    pending_count: number;
+    paid_count: number;
+    blocked_count: number;
+  };
+  by_source: Array<{
+    source_type: string;
+    status: string;
+    count: number;
+    rebate_usd: string;
+  }>;
+  recent_payouts: Array<{
+    id: string;
+    status: string;
+    amount_usd: string;
+    earning_count: number;
+    tx_hash: string | null;
+    processed_at: string | null;
+  }>;
+};
+
+function text(t: string) {
+  return { content: [{ type: "text" as const, text: t }] };
+}
+
+function money(value: string | number): string {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? `$${numeric.toFixed(4)}` : `$${value}`;
+}
+
+function sourceLabel(value: string): string {
+  return value.replace(/_/g, " ");
+}
+
+export function registerRebateTools(server: McpServer): void {
+  server.tool(
+    "rebate_status",
+    "Show your Agent Wonderland consumer rebate balance, payout threshold, blocked rebates, and recent payout transactions.",
+    {},
+    async () => {
+      const status = await apiGet<RebateStatus>("/rebates/status", { ensureConsumerPrincipal: true });
+      const threshold = Number(status.auto_payout_threshold_usd);
+      const pending = Number(status.totals.pending_usd);
+      const remaining = Math.max(0, threshold - pending);
+
+      const lines = [
+        "Rebate status",
+        `Consumer principal: ${status.consumer_principal}`,
+        `Base payout address: ${status.payout_address ?? "not configured"}`,
+        "",
+        `Lifetime earned: ${money(status.totals.lifetime_earned_usd)} across ${status.totals.total_count} rebate(s)`,
+        `Paid out: ${money(status.totals.paid_usd)} across ${status.totals.paid_count} rebate(s)`,
+        `Pending: ${money(status.totals.pending_usd)} across ${status.totals.pending_count} rebate(s)`,
+        `Blocked: ${money(status.totals.blocked_usd)} across ${status.totals.blocked_count} rebate(s)`,
+      ];
+
+      if (Number.isFinite(threshold) && threshold > 0) {
+        lines.push(
+          pending >= threshold
+            ? `Auto payout: eligible for the next processor run (threshold ${money(threshold)})`
+            : `Auto payout: ${money(remaining)} until the ${money(threshold)} threshold`,
+        );
+      }
+
+      if (status.by_source.length > 0) {
+        lines.push("", "By source:");
+        for (const row of status.by_source) {
+          lines.push(`  ${sourceLabel(row.source_type)} / ${row.status}: ${money(row.rebate_usd)} (${row.count})`);
+        }
+      }
+
+      if (status.recent_payouts.length > 0) {
+        lines.push("", "Recent payouts:");
+        for (const payout of status.recent_payouts.slice(0, 5)) {
+          const tx = payout.tx_hash ? ` tx=${payout.tx_hash}` : "";
+          lines.push(`  ${payout.status}: ${money(payout.amount_usd)} (${payout.earning_count})${tx}`);
+        }
+      }
+
+      if (!status.payout_address) {
+        lines.push("", "No Base payout address is configured, so new rebates may be blocked.");
+      }
+
+      return text(lines.join("\n"));
+    },
+  );
+}

package/src/tools/wallet.ts

@@ -39,7 +39,7 @@ import {
   installOws,
   platformSupportsOws,
 } from "../core/ows-adapter.js";
-import { ensureConsumerPrincipal, getConsumerPrincipal } from "../core/principal.js";
+import { ensureConsumerPrincipal, ensureConsumerPrincipalForMethod, getConsumerPrincipal } from "../core/principal.js";
 import { MCP_PACKAGE_VERSION } from "../core/version.js";
 
 function text(t: string) {
@@ -292,7 +292,7 @@ export function registerWalletTools(server: McpServer): void {
             paymentMethodId: selected.id,
             label: name ?? selected.label,
           });
-          const principal = await ensureConsumerPrincipal();
+          const principal = await ensureConsumerPrincipalForMethod("link");
           return text(
             [
               "Link payment method connected.",
@@ -330,7 +330,7 @@ export function registerWalletTools(server: McpServer): void {
             paymentMethodId: method.id,
             label: method.label,
           });
-          const principal = await ensureConsumerPrincipal();
+          const principal = await ensureConsumerPrincipalForMethod("link");
           return text(
             [
               "Link payment method connected.",
@@ -380,7 +380,7 @@ export function registerWalletTools(server: McpServer): void {
           const result = await pollCardSetup(pendingToken, 250);
 
           if (result) {
-            const principal = await ensureConsumerPrincipal();
+            const principal = await ensureConsumerPrincipalForMethod("card");
             return text(
               `Connected! ${result.brand} ****${result.last4} is ready for payments.\n\n` +
               `Consumer principal: ${principal}`,