@wzrd_sol/eliza-plugin 0.3.1 → 0.3.3

package/README.md

@@ -1,8 +1,15 @@
 # @wzrd_sol/eliza-plugin
 
-ElizaOS plugin for WZRD Agent Intel and the legacy earn loop on Solana.
+ElizaOS plugin for WZRD Agent Intel — x402 firewall, free preflight checks before spends,
+paid trust receipts (V6 + ERC-8004), and the earn loop on Solana.
 
-**Before any x402 spend:** run `WZRD_INTEL_PREFLIGHT` (free ReadinessCard). Escalate to `WZRD_INTEL_TRUST` only when you need a signed V5 receipt. Verify offline with `WZRD_VERIFY_RECEIPT`.
+## 3-line quickstart
+
+```typescript
+import wzrdPlugin from '@wzrd_sol/eliza-plugin';
+const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
+// "Preflight seller JUP6Lkb... at 0.25 USDC" → allow/warn/block, free, no wallet
+```
 
 ## Install
 
@@ -15,93 +22,194 @@ npm install @wzrd_sol/eliza-plugin
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `WZRD_INTEL_URL` | No | `https://intel.twzrd.xyz` | Agent Intel API (preflight, trust, verify) |
-| `WZRD_API_URL` | No | `https://api.twzrd.xyz` | Legacy earn API (infer/report/claim) |
+| `WZRD_API_URL` | No | `https://api.twzrd.xyz` | Earn API (infer/report/claim) |
 | `SOLANA_PRIVATE_KEY` | Earn lane only | — | JSON array of secret key bytes for agent Ed25519 auth |
 
-### Wiring a paying fetch (intel paid actions)
+## Intel actions (primary)
 
-The plugin does **not** embed a wallet. Paid `WZRD_INTEL_TRUST` needs an x402-capable `fetch` from the host:
+| Action | Auth/Pay | Description |
+|--------|----------|-------------|
+| `WZRD_INTEL_PREFLIGHT` | Free | ReadinessCard: `decision`, `trust_score`, `can_spend`, `caveats`, `preflight_id` |
+| `WZRD_MERCHANT_CARD` | Free | Graph card: `wash_flagged`, tier, catalog join; default refuse if wash |
+| `WZRD_INTEL_TRUST` | x402 (~0.05 USDC) | Paid trust payload + V6 signed receipt + ERC-8004 `reputation_credential` |
+| `WZRD_VERIFY_RECEIPT` | Free (offline) | Recompute leaf + Ed25519 verify; no network when pubkey is known |
 
-```typescript
-import { AgentRuntime } from '@elizaos/core';
-import wzrdPlugin, { setPayingFetch } from '@wzrd_sol/eliza-plugin';
-import { agentcashFetch } from 'your-x402-wrapper'; // agentcash, twzrd-x402-gate, etc.
+### Preflight (free, no wallet)
 
-setPayingFetch(agentcashFetch);
+```typescript
+import { intelPreflightAction } from '@wzrd_sol/eliza-plugin';
 
-const agent = new AgentRuntime({
-  plugins: [wzrdPlugin],
-  settings: {
-    WZRD_INTEL_URL: 'https://intel.twzrd.xyz',
-    SOLANA_PRIVATE_KEY: process.env.SOLANA_PRIVATE_KEY,
+// Reads seller_wallet / price_usdc / agent_intent from message content.
+await intelPreflightAction.handler(runtime, {
+  content: {
+    seller_wallet: 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4',
+    price_usdc: 0.25,
+    agent_intent: 'quote preview',
   },
-});
+}, state, opts, callback);
+```
+
+Response (formatted text returned to agent):
+
+```
+ReadinessCard v1
+Decision: allow
+Trust score: 72
+Can spend: yes
+Preflight ID: pf_abc123
+Paid deep dive available (0.05 USDC) — use WZRD_INTEL_TRUST
 ```
 
-Without a paying fetch, `WZRD_INTEL_TRUST` returns the HTTP 402 requirements and an `npx agentcash@latest fetch ...` one-liner.
+### Guard pattern: fire-before-pay with `withTwzrdGuard`
 
-## Usage
+For agents that call x402-gated URLs directly (not via pre-known seller wallet), pair this
+plugin with `twzrd-x402-gate` to intercept 402s before any spend:
 
 ```typescript
-import { wzrdPlugin } from '@wzrd_sol/eliza-plugin';
-
-const agent = new AgentRuntime({
-  plugins: [wzrdPlugin],
+import wzrdPlugin from '@wzrd_sol/eliza-plugin';
+import { withTwzrdGuard } from 'twzrd-x402-gate';
+import { createAgentcashFetch } from 'agentcash';
+
+// Wrap the paying fetch — guard runs preflight on every 402 before USDC moves.
+const x402Fetch = createAgentcashFetch({ apiKey: process.env.AGENTCASH_API_KEY });
+const safeFetch = withTwzrdGuard(x402Fetch, {
+  autoReceipt: true,   // auto-buy $0.05 TWZRD receipt on warn/allow
+  x402Fetch,
 });
+
+// Wire safeFetch into any tool or skill that calls paid resources:
+const response = await safeFetch('https://api.exa.ai/search');
+// → decision=block throws before payment
+// → decision=warn/allow: payment proceeds, TWZRD receipt captured
 ```
 
-Programmatic SDK calls (same types as the plugin) are re-exported:
+Guard flow:
+1. `safeFetch` hits the resource, gets HTTP 402.
+2. `withTwzrdGuard` reads `accepts[0].payTo` (seller wallet).
+3. Calls `POST /v1/intel/preflight` — free, no auth.
+4. `block` - throws, no payment made.
+5. `warn/allow` - returns the 402 for the x402 client to pay.
+
+### Pre-spend gate (programmatic)
 
 ```typescript
-import { intelPreflight, fetchIntelTrust, verifyReceipt, IntelPaymentRequiredError } from '@wzrd_sol/eliza-plugin';
+import { preSpendGate, fetchIntelTrust, fetchMerchantCard } from '@wzrd_sol/eliza-plugin';
+
+// Gate before paying (free preflight + free merchant_card wash refuse, default on):
+const gate = await preSpendGate({ seller_wallet: sellerPubkey, price_usdc: 0.25 });
+if (!gate.allow) return `Blocked (${gate.decision}): ${gate.reason}`;
+// gate.washFlagged === true was refuse default; null = card gap (fail-open)
+
+// Or inspect the card alone:
+const card = await fetchMerchantCard(sellerPubkey);
+if (card?.wash_flagged) return 'refuse dirty pay_to';
+
+// Then pay and get the receipt:
+const trust = await fetchIntelTrust(sellerPubkey, { fetchImpl: myX402Fetch });
 ```
 
-## Intel actions (primary)
+**Default:** `refuseWashFlagged: true` — if free `merchant_card.wash_flagged`, do not pay.
+Soft cap: `{ washMaxUsdc: 0.05 }`. Opt out: `{ refuseWashFlagged: false }`.
 
-| Action | Auth/Pay | Description |
-|--------|----------|-------------|
-| `WZRD_INTEL_PREFLIGHT` | Free | ReadinessCard: decision, trust_score, can_spend, caveats, paid upsell |
-| `WZRD_INTEL_TRUST` | x402 (~0.05 USDC) | Paid trust payload + V5 `twzrd_receipt` (needs `setPayingFetch`) |
-| `WZRD_VERIFY_RECEIPT` | Free (offline) | Recompute leaf + Ed25519 verify; no network when pubkey is known |
+### Paid trust receipt (agentcash)
+
+```typescript
+import wzrdPlugin, { setPayingFetch } from '@wzrd_sol/eliza-plugin';
+import { createAgentcashFetch } from 'agentcash';
 
-### Example prompts
+setPayingFetch(createAgentcashFetch({ apiKey: process.env.AGENTCASH_API_KEY }));
 
-- "Preflight Jupiter Quote Preview before I pay 0.25 USDC to 6EF8rrect..."
-- "Get the trust receipt for seller JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"
-- "Verify this receipt: {leaf, preimage, signature...}"
-- "Is it safe to call the paid intel endpoint on this seller?"
+const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
+// "Get the trust receipt for seller JUP6LkbZ..."
+// → WZRD_INTEL_TRUST: runs free preflight, pays $0.05 USDC, returns VC
+```
 
-### Free preflight (no wallet)
+### Paid trust receipt (PayAI)
 
 ```typescript
-import { intelPreflightAction } from '@wzrd_sol/eliza-plugin';
+import wzrdPlugin, { setPayingFetch } from '@wzrd_sol/eliza-plugin';
+import { PayAIClient } from '@payai/client';
 
-// Handler reads seller_wallet / price_usdc / agent_intent from message content
-await intelPreflightAction.handler(runtime, {
-  content: {
-    seller_wallet: 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4',
-    price_usdc: 0.25,
-    agent_intent: 'quote preview',
-  },
-}, ...);
+const payai = new PayAIClient({ keypairPath: '~/.config/solana/id.json' });
+setPayingFetch((url, init) => payai.fetch(url, init));
+
+const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
+```
+
+Without a paying fetch, `WZRD_INTEL_TRUST` returns the HTTP 402 requirements and an
+`npx agentcash@latest fetch ...` one-liner to pay manually.
+
+**`WZRD_INTEL_TRUST` response fields:**
+
+```
+Trust payload for JUP6Lkb...
+Score: 61.8  Paid: yes
+Settlement tx: 4xK3n...
+Reputation credential (ERC-8004 AgentReputationCredential):
+  effectiveTrustScore: 62       <- route on this (wash-adjusted)
+  trustScore: 72  washFactor: 0.86
+  distinctCounterparties: 14    <- cross-facilitator breadth
+  corpusScope: cross-facilitator
+  version: intel_renorm_v1
+Routing gate: effectiveTrustScore < 30 -> block, 30-60 -> warn, > 60 -> allow
+Receipt v6, leaf: 0x3a4f...
+Use WZRD_VERIFY_RECEIPT to verify offline.
+```
+
+**Routing logic:**
+
+```typescript
+const vc = trust.reputation_credential.credentialSubject;
+if (vc.effectiveTrustScore < 30) return 'block';
+if (vc.distinctCounterparties < 3) return 'warn'; // thin history
+if (vc.washFactor < 0.5) return 'warn';           // suspicious ring
 ```
 
+`effectiveTrustScore` is the cross-facilitator wash-adjusted score — computed across all known
+x402 facilitators, not just one settlement path.
+
+### Example agent prompts (trust)
+
+- `"Preflight Jupiter Quote Preview before I pay 0.25 USDC to 6EF8rrect..."`
+- `"Get the trust receipt for seller JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"`
+- `"Is it safe to call the paid intel endpoint on this seller?"`
+- `"Verify this receipt: {leaf, preimage, signature...}"`
+
 ## Legacy earn actions
 
 | Action | Auth | Description |
 |--------|------|-------------|
 | `WZRD_INFER` | Agent Ed25519 | Server-witnessed inference; returns `execution_id` |
 | `WZRD_REPORT` | Agent Ed25519 | Report outcome with `execution_id` for verified rewards |
-| `WZRD_EARN` | Agent Ed25519 | Full infer → report → rewards check in one action |
+| `WZRD_EARN` | Agent Ed25519 | Full infer -> report -> rewards check in one action |
 | `WZRD_CLAIM` | Agent Ed25519 | Gasless CCM claim via relay |
 | `WZRD_REWARDS` | Agent Ed25519 | Pending and lifetime CCM balance |
 
 ### Example prompts (earn)
 
-- "Run inference through WZRD: explain quicksort in Python"
-- "Earn some CCM on WZRD"
-- "Check my WZRD rewards"
-- "Claim my CCM"
+- `"Run inference through WZRD: explain quicksort in Python"`
+- `"Earn some CCM on WZRD"`
+- `"Check my WZRD rewards"`
+- `"Claim my CCM"`
+
+## Programmatic SDK usage
+
+```typescript
+import {
+  intelPreflight,
+  fetchIntelTrust,
+  verifyReceipt,
+  preSpendGate,
+  IntelPaymentRequiredError,
+} from '@wzrd_sol/eliza-plugin';
+
+import type {
+  ReadinessCard,
+  PreflightResponse,
+  IntelTrustResponse,
+  TwzrdReceipt,
+} from '@wzrd_sol/eliza-plugin';
+```
 
 ## Test
 
@@ -112,7 +220,8 @@ npm run build
 npm test
 ```
 
-`npm test` loads the plugin into a real `@elizaos/core` `AgentRuntime`, runs live free preflight against `intel.twzrd.xyz`, offline receipt verify, and a mocked paid trust path.
+`npm test` runs live free preflight against `intel.twzrd.xyz`, offline receipt verify, and a
+mocked paid trust path.
 
 Manual earn smoke (requires `SOLANA_PRIVATE_KEY`):
 
@@ -123,11 +232,11 @@ npx tsx test/earn-e2e.ts
 ## Links
 
 - [Agent Intel API](https://intel.twzrd.xyz)
-- [Legacy API](https://api.twzrd.xyz)
-- [SDK](https://www.npmjs.com/package/@wzrd_sol/sdk)
-- [twzrd-agent-intel (Python/MCP)](https://github.com/twzrd-sol/wzrd-final/tree/main/packages/twzrd-agent-intel)
-- [Agent discovery](https://twzrd.xyz/llms.txt)
+- [API docs / llms.txt](https://intel.twzrd.xyz/llms.txt)
+- [x402 gate (standalone firewall)](https://www.npmjs.com/package/twzrd-x402-gate)
+- [GOAT plugin](https://www.npmjs.com/package/@wzrd_sol/goat-plugin)
+- [TWZRD trust quickstart](https://intel.twzrd.xyz/docs/QUICKSTART.md)
 
 ## License
 
-MIT
+MIT

package/dist/actions/intel-preflight.js

@@ -62,9 +62,9 @@ export const intelPreflightAction = {
     handler: async (runtime, message, _state, _opt, callback) => {
         const content = (message.content ?? {});
         const input = parsePreflightInput(content);
-        if (!input.seller_wallet && !input.resource_name && !input.resource_url && !input.agent_intent) {
+        if (!input.seller_wallet && !input.resource_name && !input.resource_url) {
             await callback?.({
-                text: 'Provide seller_wallet, resource_name, resource_url, or agent_intent for preflight. ' +
+                text: 'Provide seller_wallet, resource_name, or resource_url for preflight. ' +
                     'Example: "Preflight seller JUP6Lkb... at 0.25 USDC"',
             });
             return { success: false, error: 'Missing preflight input' };

package/dist/actions/intel-trust.d.ts

@@ -1,7 +1,7 @@
 /**
  * WZRD_INTEL_TRUST — Paid trust payload + signed receipt (V5/V6) via x402-capable
- * fetch. Preflight-gated: the free ReadinessCard runs BEFORE the payment and a
- * decision=block aborts before any spend (the protocol's preflight-before-pay rule).
+ * fetch. Preflight-gated: free ReadinessCard + free merchant_card wash check run
+ * BEFORE payment; decision=block or wash_flagged aborts before any spend.
  */
 import type { Action } from '@elizaos/core';
 export declare const intelTrustAction: Action;

package/dist/actions/intel-trust.js

@@ -5,7 +5,7 @@ export const intelTrustAction = {
     name: 'WZRD_INTEL_TRUST',
     similes: ['WZRD_TRUST_RECEIPT', 'INTEL_TRUST', 'GET_TRUST_RECEIPT'],
     description: 'Paid GET /v1/intel/trust/{pubkey} (~0.05 USDC). Returns trust score + signed twzrd_receipt (V5/V6). ' +
-        'Runs the free preflight first and aborts on decision=block before spending. ' +
+        'Runs free preflight + merchant_card wash check first; aborts on decision=block or wash_flagged. ' +
         'Requires an x402-capable fetchImpl (setPayingFetch or host service). ' +
         'Surfaces payment requirements if no payer is configured.',
     examples: [
@@ -24,24 +24,32 @@ export const intelTrustAction = {
         }
         const apiBase = getIntelBase(runtime);
         const baseFetchImpl = resolvePayingFetch(runtime);
-        // preflight-before-pay: run the FREE ReadinessCard on the counterparty and
-        // abort on decision=block BEFORE any payment is signed/sent. failOpen=false so
+        // preflight-before-pay + wash refuse: FREE ReadinessCard + free merchant_card.
+        // Abort on decision=block or wash_flagged before any payment. failOpen=false so
         // the block-on-block guarantee holds even if the gate errors — a reference
-        // plugin must demonstrate the safe posture, not bypass it. The preflight call
-        // is free (the gate only ever reads), so this adds no spend.
+        // plugin must demonstrate the safe posture, not bypass it. Free reads only.
         try {
-            const gate = await preSpendGate({ seller_wallet: pubkey }, { apiBase, failOpen: false, fetchImpl: baseFetchImpl });
+            const gate = await preSpendGate({ seller_wallet: pubkey }, { apiBase, failOpen: false, refuseWashFlagged: true, fetchImpl: baseFetchImpl });
             if (!gate.allow) {
+                const washLine = gate.washFlagged === true
+                    ? `Wash flagged: yes (merchant_card refuse default)\n`
+                    : '';
                 await callback?.({
                     text: `Preflight blocked the trust purchase for ${pubkey}.\n` +
                         `Decision: ${gate.decision}${gate.trustScore != null ? `, trust_score=${gate.trustScore}` : ''}\n` +
+                        washLine +
                         `Reason: ${gate.reason}\n` +
                         `No payment was sent.`,
                 });
                 return {
                     success: false,
-                    error: 'preflight_block',
-                    data: { decision: gate.decision, trustScore: gate.trustScore, reason: gate.reason },
+                    error: gate.washFlagged === true ? 'wash_flagged' : 'preflight_block',
+                    data: {
+                        decision: gate.decision,
+                        trustScore: gate.trustScore,
+                        reason: gate.reason,
+                        washFlagged: gate.washFlagged ?? null,
+                    },
                 };
             }
         }
@@ -57,14 +65,21 @@ export const intelTrustAction = {
                 return fetchIntelTrust(pubkey, { apiBase, fetchImpl: abortingFetch });
             });
             const receipt = res.twzrd_receipt;
-            const text = `Trust payload for ${pubkey}\n` +
-                `Score: ${res.trust?.score ?? 'n/a'}\n` +
-                `Paid: ${res.paid ? 'yes' : 'no'}\n` +
-                (res.tx ? `Settlement tx: ${res.tx}\n` : '') +
-                (receipt
-                    ? `Receipt v${receipt.version}, leaf: ${receipt.leaf}\n` +
-                        `Use WZRD_VERIFY_RECEIPT to verify offline.`
-                    : 'No twzrd_receipt in response.');
+            const vc = res.reputation_credential?.credentialSubject;
+            const lines = [
+                `Trust payload for ${pubkey}`,
+                `Score: ${res.trust?.score ?? 'n/a'}  Paid: ${res.paid ? 'yes' : 'no'}`,
+            ];
+            const settleTx = res.tx ?? res.tx_pending;
+            if (settleTx)
+                lines.push(`Settlement tx${res.tx ? '' : ' (pending)'}: ${settleTx}`);
+            if (vc) {
+                lines.push(`Reputation credential (ERC-8004 AgentReputationCredential):`, `  effectiveTrustScore: ${vc.effectiveTrustScore ?? 'n/a'}`, `  trustScore: ${vc.trustScore ?? 'n/a'}  washFactor: ${vc.washFactor ?? 'n/a'}`, `  distinctCounterparties: ${vc.distinctCounterparties ?? 'n/a'}`, `  corpusScope: ${vc.corpusScope ?? 'n/a'}`, `  version: ${vc.trustScoreVersion ?? 'n/a'}`, `Routing gate: effectiveTrustScore < 30 → block, 30-60 → warn, > 60 → allow`);
+            }
+            lines.push(receipt
+                ? `Receipt v${receipt.version}, leaf: ${receipt.leaf}\nUse WZRD_VERIFY_RECEIPT to verify offline.`
+                : 'No twzrd_receipt in response.');
+            const text = lines.join('\n');
             await callback?.({ text });
             return { success: true, data: res };
         }

package/dist/actions/merchant-card.d.ts

@@ -0,0 +1,6 @@
+/**
+ * WZRD_MERCHANT_CARD — Free demand-quality graph card for a receive wallet.
+ * Includes wash_flagged (buyer refuse default) and optional catalog join.
+ */
+import type { Action } from '@elizaos/core';
+export declare const merchantCardAction: Action;

package/dist/actions/merchant-card.js

@@ -0,0 +1,85 @@
+import { fetchMerchantCard } from '@wzrd_sol/sdk';
+import { extractPubkey, getIntelBase, withTimeout } from '../intel-helpers.js';
+function formatMerchantCard(card) {
+    const lines = [
+        `Merchant card for ${card.merchant ?? 'unknown'}`,
+        `In corpus: ${card.in_corpus ? 'yes' : 'no'}`,
+        `Wash flagged: ${card.wash_flagged === true ? 'YES — default refuse pay' : card.wash_flagged === false ? 'no' : 'unknown'}`,
+    ];
+    if (card.wash_label)
+        lines.push(`Wash label: ${card.wash_label}`);
+    if (card.provider_reputation_tier)
+        lines.push(`Tier: ${card.provider_reputation_tier}`);
+    if (card.unique_payers_90d != null)
+        lines.push(`Unique payers (90d): ${card.unique_payers_90d}`);
+    if (card.offering_status)
+        lines.push(`Offering: ${card.offering_status}`);
+    if (card.catalog_enriched) {
+        const name = card.catalog && typeof card.catalog === 'object' && 'name' in card.catalog
+            ? String(card.catalog.name ?? '')
+            : '';
+        lines.push(`Catalog enriched: yes${name ? ` (${name})` : ''} — listing only, not quality proof`);
+    }
+    else {
+        lines.push('Catalog enriched: no (graph only)');
+    }
+    if (card.wash_flagged === true) {
+        lines.push('Policy: do not pay this pay_to (trustless default). Cap only if operator set washMaxUsdc.');
+    }
+    return lines.join('\n');
+}
+export const merchantCardAction = {
+    name: 'WZRD_MERCHANT_CARD',
+    similes: ['WZRD_MERCHANT', 'MERCHANT_CARD', 'INTEL_MERCHANT_CARD', 'CHECK_WASH'],
+    description: 'Free GET merchant demand-quality card for a Solana receive wallet (no auth). ' +
+        'Returns wash_flagged, tier, unique payers, catalog join when listed. ' +
+        'Default: if wash_flagged is true, do not pay that pay_to.',
+    examples: [
+        [
+            {
+                name: '{{user1}}',
+                content: { text: 'Merchant card for 7G73dUxj8Qn4yH4x9zXkKqZ8oKqZ8oKqZ8o' },
+            },
+            {
+                name: '{{agentName}}',
+                content: { text: 'Merchant card: wash_flagged YES — default refuse pay' },
+            },
+        ],
+    ],
+    validate: async () => true,
+    handler: async (runtime, message, _state, _opt, callback) => {
+        const content = (message.content ?? {});
+        const pubkey = extractPubkey(content);
+        if (!pubkey) {
+            await callback?.({
+                text: 'Provide a merchant/seller wallet (32-44 char base58) for merchant_card.',
+            });
+            return { success: false, error: 'Missing pubkey' };
+        }
+        const apiBase = getIntelBase(runtime);
+        try {
+            const card = await withTimeout(() => fetchMerchantCard(pubkey, { apiBase }));
+            if (!card) {
+                await callback?.({
+                    text: `Merchant card unavailable for ${pubkey} (network or invalid). ` +
+                        `Fail-open: do not invent wash_flagged; use WZRD_INTEL_PREFLIGHT decision only.`,
+                });
+                return { success: false, error: 'merchant_card_unavailable' };
+            }
+            const text = formatMerchantCard(card);
+            await callback?.({ text });
+            return {
+                success: true,
+                data: {
+                    ...card,
+                    refuse_pay: card.wash_flagged === true,
+                },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            await callback?.({ text: `Merchant card failed: ${msg}` });
+            return { success: false, error: msg };
+        }
+    },
+};

package/dist/client.d.ts

@@ -75,7 +75,7 @@ export declare class WzrdClient {
         quality_score?: number;
         latency_ms?: number;
     }): Promise<ReportResult>;
-    /** Check pending + total rewards (flattens nested /v1/agent/earned response) */
+    /** Check pending + total rewards (reads flat /v1/agent/earned response) */
     getRewards(): Promise<RewardsBalance>;
     /** Gasless CCM claim via server relay */
     claimRelay(): Promise<ClaimResult>;

package/dist/client.js

@@ -87,19 +87,17 @@ export class WzrdClient {
         }
         return res.json();
     }
-    /** Check pending + total rewards (flattens nested /v1/agent/earned response) */
+    /** Check pending + total rewards (reads flat /v1/agent/earned response) */
     async getRewards() {
         const res = await this.authedFetch('/v1/agent/earned');
         if (!res.ok)
             throw new Error(`Rewards check failed: ${res.status}`);
         const data = await res.json();
-        const economy = data.economy;
-        const routing = data.routing;
         return {
-            pending_ccm: Number(economy?.pending_ccm ?? 0),
-            total_rewarded_ccm: Number(economy?.earned_ccm ?? 0),
-            rank: null, // rank not in this endpoint
-            contribution_count: Number(routing?.lifetime_contributions ?? 0),
+            pending_ccm: Number(data.pending_ccm ?? 0),
+            total_rewarded_ccm: Number(data.total_earned_ccm ?? 0),
+            rank: data.rank == null ? null : Number(data.rank),
+            contribution_count: Number(data.lifetime_contributions ?? 0),
         };
     }
     /** Gasless CCM claim via server relay */

package/dist/index.d.ts

@@ -2,8 +2,9 @@
  * @wzrd_sol/eliza-plugin — WZRD Agent Intel + Earn Loop for ElizaOS
  *
  * Intel lane (default https://intel.twzrd.xyz):
- *   WZRD_INTEL_PREFLIGHT → WZRD_INTEL_TRUST → WZRD_VERIFY_RECEIPT
+ *   WZRD_INTEL_PREFLIGHT → WZRD_MERCHANT_CARD → WZRD_INTEL_TRUST → WZRD_VERIFY_RECEIPT
  * Paid intel requires caller-supplied x402 fetch via setPayingFetch().
+ * Default: preSpendGate refuses wash_flagged pay_to (free merchant_card).
  *
  * Earn lane (default https://api.twzrd.xyz):
  *   WZRD_INFER → WZRD_REPORT → WZRD_EARN → WZRD_CLAIM / WZRD_REWARDS
@@ -20,14 +21,15 @@ import { earnAction } from './actions/earn.js';
 import { claimAction } from './actions/claim.js';
 import { rewardsAction } from './actions/rewards.js';
 import { intelPreflightAction } from './actions/intel-preflight.js';
+import { merchantCardAction } from './actions/merchant-card.js';
 import { intelTrustAction } from './actions/intel-trust.js';
 import { verifyReceiptAction } from './actions/verify-receipt.js';
 export declare const wzrdPlugin: Plugin;
 export default wzrdPlugin;
-export { intelPreflightAction, intelTrustAction, verifyReceiptAction, earnAction, inferAction, reportAction, claimAction, rewardsAction, };
+export { intelPreflightAction, merchantCardAction, intelTrustAction, verifyReceiptAction, earnAction, inferAction, reportAction, claimAction, rewardsAction, };
 export { getWzrdClient, clearClientCache, getIntelApiBase, getIntelClient } from './client-factory.js';
 export { setPayingFetch, clearPayingFetch, resolvePayingFetch } from './paying-fetch.js';
 export { WzrdClient } from './client.js';
 export type { InferResult, ReportResult, RewardsBalance, ClaimResult } from './client.js';
-export { IntelPaymentRequiredError, intelPreflight, fetchIntelTrust, verifyReceipt, preSpendGate, intelTrustUrl, TRUSTED_RECEIPT_PUBKEY, INTEL_TRUST_PRICE_USDC, } from '@wzrd_sol/sdk';
-export type { ReadinessCard, PreflightInput, PreflightResponse, TwzrdReceipt, IntelTrustResponse, VerifyReceiptResult, X402PaymentRequired, } from '@wzrd_sol/sdk';
+export { IntelPaymentRequiredError, intelPreflight, fetchIntelTrust, fetchMerchantCard, verifyReceipt, preSpendGate, intelTrustUrl, TRUSTED_RECEIPT_PUBKEY, INTEL_TRUST_PRICE_USDC, } from '@wzrd_sol/sdk';
+export type { ReadinessCard, PreflightInput, PreflightResponse, MerchantCard, TwzrdReceipt, IntelTrustResponse, VerifyReceiptResult, X402PaymentRequired, } from '@wzrd_sol/sdk';

package/dist/index.js

@@ -4,15 +4,17 @@ import { earnAction } from './actions/earn.js';
 import { claimAction } from './actions/claim.js';
 import { rewardsAction } from './actions/rewards.js';
 import { intelPreflightAction } from './actions/intel-preflight.js';
+import { merchantCardAction } from './actions/merchant-card.js';
 import { intelTrustAction } from './actions/intel-trust.js';
 import { verifyReceiptAction } from './actions/verify-receipt.js';
 export const wzrdPlugin = {
     name: 'wzrd',
-    description: 'WZRD Agent Intel — free ReadinessCard preflight (gates spends before paying), x402-paid trust receipts ' +
-        '(V5/V6), offline verification on intel.twzrd.xyz. Also ships the legacy earn loop (infer/report/claim) ' +
-        'on api.twzrd.xyz.',
+    description: 'WZRD Agent Intel — free ReadinessCard preflight + merchant_card wash refuse (default), ' +
+        'x402-paid trust receipts (V5/V6), offline verification on intel.twzrd.xyz. ' +
+        'Also ships the legacy earn loop (infer/report/claim) on api.twzrd.xyz.',
     actions: [
         intelPreflightAction,
+        merchantCardAction,
         intelTrustAction,
         verifyReceiptAction,
         earnAction,
@@ -23,8 +25,8 @@ export const wzrdPlugin = {
     ],
 };
 export default wzrdPlugin;
-export { intelPreflightAction, intelTrustAction, verifyReceiptAction, earnAction, inferAction, reportAction, claimAction, rewardsAction, };
+export { intelPreflightAction, merchantCardAction, intelTrustAction, verifyReceiptAction, earnAction, inferAction, reportAction, claimAction, rewardsAction, };
 export { getWzrdClient, clearClientCache, getIntelApiBase, getIntelClient } from './client-factory.js';
 export { setPayingFetch, clearPayingFetch, resolvePayingFetch } from './paying-fetch.js';
 export { WzrdClient } from './client.js';
-export { IntelPaymentRequiredError, intelPreflight, fetchIntelTrust, verifyReceipt, preSpendGate, intelTrustUrl, TRUSTED_RECEIPT_PUBKEY, INTEL_TRUST_PRICE_USDC, } from '@wzrd_sol/sdk';
+export { IntelPaymentRequiredError, intelPreflight, fetchIntelTrust, fetchMerchantCard, verifyReceipt, preSpendGate, intelTrustUrl, TRUSTED_RECEIPT_PUBKEY, INTEL_TRUST_PRICE_USDC, } from '@wzrd_sol/sdk';

package/dist/intel-helpers.js

@@ -41,9 +41,10 @@ export function parseReceipt(content) {
     }
     return null;
 }
+const SOLANA_PUBKEY_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 export function extractPubkey(content) {
     const direct = str(content.pubkey ?? content.seller_wallet ?? content.wallet);
-    if (direct)
+    if (direct && SOLANA_PUBKEY_RE.test(direct))
         return direct;
     const text = str(content.text);
     if (!text)
@@ -51,7 +52,7 @@ export function extractPubkey(content) {
     const fromJson = tryParseJson(text);
     if (fromJson) {
         const w = str(fromJson.pubkey ?? fromJson.seller_wallet ?? fromJson.wallet);
-        if (w)
+        if (w && SOLANA_PUBKEY_RE.test(w))
             return w;
     }
     return extractWallet(text);
@@ -71,7 +72,10 @@ export function formatPaymentRequired(err, apiBase, pubkey) {
         `No paying fetch configured. Wire one before runtime creation:\n` +
         `  import { setPayingFetch } from '@wzrd_sol/eliza-plugin';\n` +
         `  setPayingFetch(myAgentcashFetch);\n\n` +
-        `Or pay out of band:\n` +
+        `Pay out of band only with an x402 client that preserves the sponsored fee-payer slot.\n` +
+        `Caveat: npx agentcash@latest fetch is not currently a green TWZRD repro; ` +
+        `it failed closed with payment_invalid / fee_payer_slot_already_signed on 2026-06-23.\n` +
+        `Known-bad compatibility command:\n` +
         `  npx agentcash@latest fetch ${url}`);
 }
 function str(v) {

package/dist/test/plugin-registration.intel.js

@@ -10,7 +10,7 @@
 import assert from 'node:assert/strict';
 import { describe, it, before, after } from 'node:test';
 import { AgentRuntime } from '@elizaos/core';
-import wzrdPlugin, { intelPreflightAction, intelTrustAction, verifyReceiptAction, setPayingFetch, clearPayingFetch, getIntelClient, resolvePayingFetch, } from '@wzrd_sol/eliza-plugin';
+import wzrdPlugin, { intelPreflightAction, merchantCardAction, intelTrustAction, verifyReceiptAction, setPayingFetch, clearPayingFetch, getIntelClient, resolvePayingFetch, } from '@wzrd_sol/eliza-plugin';
 function mockMemory(content) {
     return {
         id: '00000000-0000-0000-0000-000000000001',
@@ -43,6 +43,7 @@ describe('wzrdPlugin intel registration + E2E (real runtime load)', () => {
     it('constructs runtime with plugins and registers intel actions', () => {
         const names = runtime.actions.map((a) => a.name);
         assert.ok(names.includes('WZRD_INTEL_PREFLIGHT'), 'preflight must be registered');
+        assert.ok(names.includes('WZRD_MERCHANT_CARD'), 'merchant card must be registered');
         assert.ok(names.includes('WZRD_INTEL_TRUST'), 'trust must be registered');
         assert.ok(names.includes('WZRD_VERIFY_RECEIPT'), 'verify must be registered');
     });
@@ -121,35 +122,115 @@ describe('wzrdPlugin intel registration + E2E (real runtime load)', () => {
             assert.ok(result.data);
     });
     it('PREFLIGHT-BEFORE-PAY: decision=block aborts the trust purchase before any payment', async () => {
-        // preSpendGate runs the FREE preflight via the SDK's intelPreflight, which uses
-        // the global fetch (not the injected paying fetch — that is reserved for the
-        // paid leg). So we stub global fetch to return a block ReadinessCard, and put a
-        // tripwire on the injected paying fetch: if the pay leg runs after a block, the
-        // tripwire fires and the test fails.
+        // preSpendGate runs FREE preflight + merchant_card via global fetch (not the
+        // injected paying fetch). Stub both; tripwire on pay leg.
         const realFetch = globalThis.fetch;
         let payAttempted = false;
         setPayingFetch(async () => {
             payAttempted = true;
             return { ok: true, status: 200, json: async () => ({}) };
         });
+        globalThis.fetch = (async (input) => {
+            const url = String(input);
+            if (url.includes('/merchant_card/')) {
+                return {
+                    ok: true,
+                    status: 200,
+                    json: async () => ({ wash_flagged: false }),
+                };
+            }
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    readiness_card: { decision: 'block', trust_score: 5, can_spend: false },
+                    reason: 'seller flagged by corpus',
+                }),
+            };
+        });
+        try {
+            const callbacks = [];
+            const result = await intelTrustAction.handler(mockRuntime(), mockMemory({ pubkey: '4LkEFjJdXARkKx8FBx4LBFa2SvJNmjQpgGDLoJcypZUE' }), undefined, undefined, async (r) => {
+                callbacks.push(r.text ?? '');
+                return [];
+            });
+            assert.equal(result?.success, false);
+            assert.equal(result?.error, 'preflight_block');
+            assert.equal(payAttempted, false, 'payment must NOT be attempted after a block decision');
+            assert.match(callbacks.join('\n'), /blocked|No payment was sent/i);
+        }
+        finally {
+            globalThis.fetch = realFetch;
+        }
+    });
+    it('WASH REFUSE: wash_flagged aborts trust purchase even when preflight allows', async () => {
+        const realFetch = globalThis.fetch;
+        let payAttempted = false;
+        setPayingFetch(async () => {
+            payAttempted = true;
+            return { ok: true, status: 200, json: async () => ({}) };
+        });
+        globalThis.fetch = (async (input) => {
+            const url = String(input);
+            if (url.includes('/merchant_card/')) {
+                return {
+                    ok: true,
+                    status: 200,
+                    json: async () => ({
+                        merchant: '4LkEFjJdXARkKx8FBx4LBFa2SvJNmjQpgGDLoJcypZUE',
+                        wash_flagged: true,
+                        wash_label: 'fleet_dominated',
+                    }),
+                };
+            }
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    readiness_card: { decision: 'allow', trust_score: 80, can_spend: true },
+                    reason: 'preflight decision=allow',
+                }),
+            };
+        });
+        try {
+            const callbacks = [];
+            const result = await intelTrustAction.handler(mockRuntime(), mockMemory({ pubkey: '4LkEFjJdXARkKx8FBx4LBFa2SvJNmjQpgGDLoJcypZUE' }), undefined, undefined, async (r) => {
+                callbacks.push(r.text ?? '');
+                return [];
+            });
+            assert.equal(result?.success, false);
+            assert.equal(result?.error, 'wash_flagged');
+            assert.equal(payAttempted, false, 'payment must NOT run after wash refuse');
+            assert.match(callbacks.join('\n'), /wash|No payment was sent/i);
+        }
+        finally {
+            globalThis.fetch = realFetch;
+        }
+    });
+    it('merchant card handler returns wash / catalog fields (mocked)', async () => {
+        const realFetch = globalThis.fetch;
         globalThis.fetch = (async () => ({
             ok: true,
             status: 200,
             json: async () => ({
-                readiness_card: { decision: 'block', trust_score: 5, can_spend: false },
-                reason: 'seller flagged by corpus',
+                merchant: '4LkEFjJdXARkKx8FBx4LBFa2SvJNmjQpgGDLoJcypZUE',
+                in_corpus: true,
+                wash_flagged: false,
+                wash_label: 'provider_organic_broad',
+                catalog_enriched: false,
+                offering_status: 'Offering unknown — graph only',
+                unique_payers_90d: 12,
             }),
         }));
         try {
             const callbacks = [];
-            const result = await intelTrustAction.handler(mockRuntime(), mockMemory({ pubkey: '4LkEFjJdXARkKx8FBx4LBFa2SvJNmjQpgGDLoJcypZUE' }), undefined, undefined, async (r) => {
+            const result = await merchantCardAction.handler(mockRuntime(), mockMemory({ pubkey: '4LkEFjJdXARkKx8FBx4LBFa2SvJNmjQpgGDLoJcypZUE' }), undefined, undefined, async (r) => {
                 callbacks.push(r.text ?? '');
                 return [];
             });
-            assert.equal(result?.success, false);
-            assert.equal(result?.error, 'preflight_block');
-            assert.equal(payAttempted, false, 'payment must NOT be attempted after a block decision');
-            assert.match(callbacks.join('\n'), /blocked|No payment was sent/i);
+            assert.equal(result?.success, true);
+            assert.match(callbacks.join('\n'), /Wash flagged: no/i);
+            assert.match(callbacks.join('\n'), /graph only/i);
         }
         finally {
             globalThis.fetch = realFetch;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wzrd_sol/eliza-plugin",
-  "version": "0.3.1",
-  "description": "WZRD Agent Intel for ElizaOS — preflight ReadinessCards, x402-paid signed trust receipts (V6 reputation leaf), offline verification on intel.twzrd.xyz. Also ships the legacy earn loop.",
+  "version": "0.3.3",
+  "description": "WZRD Agent Intel for ElizaOS — preflight ReadinessCards, free merchant_card wash refuse default, x402-paid signed trust receipts (V6 reputation leaf), offline verification on intel.twzrd.xyz. Also ships the legacy earn loop.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@solana/web3.js": "^1.95.0",
-    "@wzrd_sol/sdk": "^0.4.3",
+    "@wzrd_sol/sdk": "^0.4.7",
     "bs58": "^5.0.0",
     "tweetnacl": "^1.0.3"
   },