@agentwonderland/mcp 0.1.50 → 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__/payments.test.js

@@ -21,6 +21,7 @@ vi.mock("../config.js", () => ({
     getApiUrl: () => "http://api.test",
     getCardConfig: () => currentCard,
     getLinkConfig: () => currentLink,
+    getLinkCooldown: () => null,
     getConfig: () => ({ defaultPaymentMethod: currentDefaultPaymentMethod }),
     getDefaultWallet: () => currentDefaultWallet,
     getWallets: () => currentWallets,
@@ -124,15 +125,35 @@ describe("payment method initialization", () => {
             networkId: "profile_test",
         });
         expect(mockCreateLinkSharedPaymentToken).toHaveBeenCalledWith(expect.objectContaining({
-            amount: "2000",
+            amount: "25",
             currency: "usd",
             networkId: "profile_test",
             paymentMethodId: "csmrpd_link_123",
         }));
         const linkTokenRequest = mockCreateLinkSharedPaymentToken.mock.calls[0]?.[0];
-        expect(linkTokenRequest?.context).toContain("up to USD 20.00");
+        expect(linkTokenRequest?.context).toContain("up to USD 0.25");
         expect(linkTokenRequest?.context).toContain("quoted at USD 0.25");
     });
+    it("uses an explicit Link approval override when configured", async () => {
+        process.env.AGENTWONDERLAND_LINK_APPROVAL_LIMIT_CENTS = "2000";
+        currentLink = {
+            paymentMethodId: "csmrpd_link_123",
+            label: "Visa ****4242",
+        };
+        currentDefaultPaymentMethod = "link";
+        const { getPaymentFetch } = await import("../payments.js");
+        await getPaymentFetch("link");
+        const stripeConfig = mockStripe.mock.calls[0]?.[0];
+        await stripeConfig.createToken({
+            amount: "25",
+            currency: "usd",
+            expiresAt: 1778290000,
+            networkId: "profile_test",
+        });
+        expect(mockCreateLinkSharedPaymentToken).toHaveBeenCalledWith(expect.objectContaining({
+            amount: "2000",
+        }));
+    });
     it("allows a low env override while never approving below the quoted amount", async () => {
         process.env.AGENTWONDERLAND_LINK_APPROVAL_LIMIT_CENTS = "10";
         currentLink = {

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/config.d.ts

@@ -22,6 +22,22 @@ export interface PendingLinkSetup {
     phrase: string;
     createdAt: string;
 }
+export interface PendingLinkSpendRequest {
+    id: string;
+    approvalUrl?: string;
+    amount: string;
+    currency: string;
+    context: string;
+    expiresAt: number;
+    networkId: string;
+    paymentMethodId: string;
+    createdAt: string;
+}
+export interface LinkCooldown {
+    reason: string;
+    createdAt: string;
+    blockedUntil: string;
+}
 export interface SpendPolicy {
     maxPerTxUsd?: number;
     maxPerDayUsd?: number;
@@ -43,6 +59,8 @@ export interface Config {
     card: CardConfig | null;
     link: LinkConfig | null;
     pendingLinkSetup?: PendingLinkSetup | null;
+    pendingLinkSpendRequest?: PendingLinkSpendRequest | null;
+    linkCooldown?: LinkCooldown | null;
     pendingCardSetupToken?: string | null;
     favorites: string[];
     /** Require user confirmation before spending. Default: true. Set false for headless/automated use. */
@@ -103,6 +121,10 @@ export declare function removeWallet(id: string): void;
 export declare function getCardConfig(): CardConfig | null;
 export declare function getLinkConfig(): LinkConfig | null;
 export declare function getPendingLinkSetup(): PendingLinkSetup | null;
+export declare function getPendingLinkSpendRequest(): PendingLinkSpendRequest | null;
+export declare function setPendingLinkSpendRequest(pendingLinkSpendRequest: PendingLinkSpendRequest | null): void;
+export declare function getLinkCooldown(): LinkCooldown | null;
+export declare function setLinkCooldown(linkCooldown: LinkCooldown | null): void;
 /**
  * Save card configuration after setup.
  */

package/dist/core/config.js

@@ -38,6 +38,8 @@ function migrateIfNeeded(raw) {
             card: raw.card ?? null,
             link: raw.link ?? null,
             pendingLinkSetup: raw.link ? null : (raw.pendingLinkSetup ?? null),
+            pendingLinkSpendRequest: raw.pendingLinkSpendRequest ?? null,
+            linkCooldown: raw.linkCooldown ?? null,
             pendingCardSetupToken: r.pendingCardSetupToken ?? null,
             favorites: r.favorites ?? [],
             confirmBeforeSpend: r.confirmBeforeSpend !== false,
@@ -113,6 +115,8 @@ function migrateIfNeeded(raw) {
         card,
         link: raw.link ?? null,
         pendingLinkSetup: raw.link ? null : (raw.pendingLinkSetup ?? null),
+        pendingLinkSpendRequest: raw.pendingLinkSpendRequest ?? null,
+        linkCooldown: raw.linkCooldown ?? null,
         pendingCardSetupToken: null,
         favorites: [],
         confirmBeforeSpend: true,
@@ -138,6 +142,8 @@ export function getConfig() {
         card: null,
         link: null,
         pendingLinkSetup: null,
+        pendingLinkSpendRequest: null,
+        linkCooldown: null,
         pendingCardSetupToken: null,
         favorites: [],
         confirmBeforeSpend: true,
@@ -301,6 +307,18 @@ export function getLinkConfig() {
 export function getPendingLinkSetup() {
     return getConfig().pendingLinkSetup ?? null;
 }
+export function getPendingLinkSpendRequest() {
+    return getConfig().pendingLinkSpendRequest ?? null;
+}
+export function setPendingLinkSpendRequest(pendingLinkSpendRequest) {
+    saveConfig({ pendingLinkSpendRequest });
+}
+export function getLinkCooldown() {
+    return getConfig().linkCooldown ?? null;
+}
+export function setLinkCooldown(linkCooldown) {
+    saveConfig({ linkCooldown });
+}
 /**
  * Save card configuration after setup.
  */
@@ -330,12 +348,14 @@ export function setLinkConfig(link) {
             link,
             defaultPaymentMethod: "link",
             pendingLinkSetup: null,
+            pendingLinkSpendRequest: null,
         });
     }
     else {
         saveConfig({
             link,
             pendingLinkSetup: null,
+            pendingLinkSpendRequest: null,
             defaultPaymentMethod: current.defaultPaymentMethod === "link"
                 ? undefined
                 : current.defaultPaymentMethod,

package/dist/core/link-cli.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { getPendingLinkSpendRequest, setLinkCooldown, setPendingLinkSpendRequest, } from "./config.js";
 const execFileAsync = promisify(execFile);
 const LINK_CLI_PACKAGE = "@stripe/link-cli";
 const LINK_CLI_TIMEOUT_MS = 10 * 60 * 1000;
@@ -92,6 +93,34 @@ function extractSpendRequestApproval(output) {
     }
     return null;
 }
+function isMatchingPendingSpendRequest(pending, params) {
+    if (!pending)
+        return false;
+    if (pending.amount !== params.amount)
+        return false;
+    if (pending.currency.toLowerCase() !== params.currency.toLowerCase())
+        return false;
+    if (pending.context !== params.context)
+        return false;
+    if (pending.networkId !== params.networkId)
+        return false;
+    if (pending.paymentMethodId !== params.paymentMethodId)
+        return false;
+    if (pending.expiresAt <= Math.floor(Date.now() / 1000))
+        return false;
+    return true;
+}
+function isProjectedSpendCapError(message) {
+    return /projected daily spend|projected spend|exceeds limit/i.test(message);
+}
+function recordLinkCooldown(reason) {
+    const now = new Date();
+    setLinkCooldown({
+        reason,
+        createdAt: now.toISOString(),
+        blockedUntil: new Date(now.getTime() + 24 * 60 * 60 * 1000).toISOString(),
+    });
+}
 function normalizePaymentMethods(output) {
     const values = Array.isArray(output)
         ? output
@@ -181,6 +210,22 @@ export async function listLinkPaymentMethods() {
     return normalizePaymentMethods(output);
 }
 export async function createLinkSharedPaymentToken(params) {
+    const existing = getPendingLinkSpendRequest();
+    if (isMatchingPendingSpendRequest(existing, params)) {
+        try {
+            console.error(`Resuming pending Link approval: ${existing.id}`);
+            const spt = await retrieveSharedPaymentToken(existing.id, existing.approvalUrl);
+            setPendingLinkSpendRequest(null);
+            return spt;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!/denied|expired|not found|without a shared payment token|POLLING_TIMEOUT/i.test(message)) {
+                throw err;
+            }
+            setPendingLinkSpendRequest(null);
+        }
+    }
     const args = [
         "spend-request",
         "create",
@@ -207,6 +252,16 @@ export async function createLinkSharedPaymentToken(params) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        if (isProjectedSpendCapError(message)) {
+            recordLinkCooldown(message);
+            throw new Error([
+                "Link is temporarily blocked by Stripe's projected-spend cap.",
+                "Reauthing Link or switching cards in the same Link account will not fix this.",
+                "Use USDC for now, wait for the rolling Link window to clear, or ask Stripe to raise/clear the merchant projected-spend cap.",
+                "",
+                message,
+            ].join("\n"));
+        }
         if (/invalid network_id|could not retrieve merchant information/i.test(message)) {
             throw new Error([
                 message,
@@ -219,41 +274,58 @@ export async function createLinkSharedPaymentToken(params) {
     }
     const spt = extractSharedPaymentToken(output);
     if (spt) {
+        setPendingLinkSpendRequest(null);
         return spt;
     }
     const approval = extractSpendRequestApproval(output);
     if (approval?.id && approval.status === "pending_approval") {
+        setPendingLinkSpendRequest({
+            id: approval.id,
+            approvalUrl: approval.approvalUrl,
+            amount: params.amount,
+            currency: params.currency,
+            context: params.context,
+            expiresAt: params.expiresAt,
+            networkId: params.networkId,
+            paymentMethodId: params.paymentMethodId,
+            createdAt: new Date().toISOString(),
+        });
         if (approval.approvalUrl) {
             console.error(`Link approval required: ${approval.approvalUrl}`);
         }
-        let retrieved = await runLinkCli([
+        const retrievedSpt = await retrieveSharedPaymentToken(approval.id, approval.approvalUrl);
+        setPendingLinkSpendRequest(null);
+        return retrievedSpt;
+    }
+    {
+        throw new Error("Link spend request completed without a shared payment token in the CLI response.");
+    }
+}
+async function retrieveSharedPaymentToken(spendRequestId, approvalUrl) {
+    let retrieved = await runLinkCli([
+        "spend-request",
+        "retrieve",
+        spendRequestId,
+        "--interval",
+        "2",
+        "--max-attempts",
+        "150",
+    ]);
+    let retrievedSpt = extractSharedPaymentToken(retrieved);
+    for (let attempt = 0; !retrievedSpt && attempt < 30; attempt += 1) {
+        await sleep(2_000);
+        retrieved = await runLinkCli([
             "spend-request",
             "retrieve",
-            approval.id,
-            "--interval",
-            "2",
-            "--max-attempts",
-            "150",
+            spendRequestId,
         ]);
-        let retrievedSpt = extractSharedPaymentToken(retrieved);
-        for (let attempt = 0; !retrievedSpt && attempt < 30; attempt += 1) {
-            await sleep(2_000);
-            retrieved = await runLinkCli([
-                "spend-request",
-                "retrieve",
-                approval.id,
-            ]);
-            retrievedSpt = extractSharedPaymentToken(retrieved);
-        }
-        if (retrievedSpt) {
-            return retrievedSpt;
-        }
-        throw new Error([
-            "Link spend request finished without a shared payment token.",
-            approval.approvalUrl ? `Approval URL: ${approval.approvalUrl}` : undefined,
-        ].filter(Boolean).join("\n"));
+        retrievedSpt = extractSharedPaymentToken(retrieved);
     }
-    {
-        throw new Error("Link spend request completed without a shared payment token in the CLI response.");
+    if (retrievedSpt) {
+        return retrievedSpt;
     }
+    throw new Error([
+        "Link spend request finished without a shared payment token.",
+        approvalUrl ? `Approval URL: ${approvalUrl}` : undefined,
+    ].filter(Boolean).join("\n"));
 }

package/dist/core/payments.js

@@ -9,7 +9,7 @@
  * Users can configure multiple wallets with different chains and select
  * which to use per-request via `--pay-with <wallet-id|chain|card>`.
  */
-import { getConfig, getWallets, getDefaultWallet, getCardConfig, getLinkConfig, resolveWalletAndChain, getApiUrl, } from "./config.js";
+import { getConfig, getWallets, getDefaultWallet, getCardConfig, getLinkConfig, getLinkCooldown, resolveWalletAndChain, getApiUrl, } from "./config.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.
@@ -26,7 +26,6 @@ const REGISTRY_METHOD_MAP = {
     card: "stripe_card",
     link: "stripe_card",
 };
-const DEFAULT_LINK_APPROVAL_LIMIT_CENTS = 2_000;
 const ACCEPTED_PAYMENT_ALIASES = {
     tempo: ["tempo_usdc", "tempo"],
     base: ["base_usdc", "base"],
@@ -164,10 +163,24 @@ function formatMinorCurrencyAmount(currency, amount) {
 function getLinkApprovalLimitAmount(actualAmount) {
     const actualAmountCents = Number(actualAmount);
     const configuredLimit = Number(process.env.AGENTWONDERLAND_LINK_APPROVAL_LIMIT_CENTS);
-    const defaultLimit = Number.isFinite(configuredLimit) && configuredLimit > 0
-        ? Math.floor(configuredLimit)
-        : DEFAULT_LINK_APPROVAL_LIMIT_CENTS;
-    return String(Math.max(actualAmountCents, defaultLimit));
+    const approvalLimit = Number.isFinite(configuredLimit) && configuredLimit > 0
+        ? Math.max(actualAmountCents, Math.floor(configuredLimit))
+        : actualAmountCents;
+    return String(approvalLimit);
+}
+function assertLinkNotCoolingDown() {
+    const cooldown = getLinkCooldown();
+    if (!cooldown)
+        return;
+    const blockedUntil = Date.parse(cooldown.blockedUntil);
+    if (!Number.isFinite(blockedUntil) || blockedUntil <= Date.now())
+        return;
+    throw new Error([
+        "Link is temporarily blocked by Stripe's projected-spend cap.",
+        "Reauthing Link or switching cards in the same Link account will not fix this.",
+        `Try again after ${cooldown.blockedUntil}, use USDC, or ask Stripe to raise/clear the merchant projected-spend cap.`,
+        `Last Link error: ${cooldown.reason}`,
+    ].join("\n"));
 }
 function buildLinkApprovalContext(params) {
     const amountText = formatMinorCurrencyAmount(params.currency, params.amount);
@@ -188,6 +201,7 @@ async function initLink() {
             methods: [stripe({
                     paymentMethod: linkConfig.paymentMethodId,
                     createToken: async (params) => {
+                        assertLinkNotCoolingDown();
                         const approvalAmount = getLinkApprovalLimitAmount(params.amount);
                         console.error(`Requesting Link approval up to ${formatMinorCurrencyAmount(params.currency, approvalAmount)} ` +
                             `for this ${formatMinorCurrencyAmount(params.currency, params.amount)} Agent Wonderland run.`);

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/core/version.d.ts

@@ -1 +1 @@
-export declare const MCP_PACKAGE_VERSION = "0.1.50";
+export declare const MCP_PACKAGE_VERSION = "0.1.51";

package/dist/core/version.js

@@ -1 +1 @@
-export const MCP_PACKAGE_VERSION = "0.1.50";
+export const MCP_PACKAGE_VERSION = "0.1.51";

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");
+    });
+});