feat: @x402/mnemopay — economic memory for AI agent payments

[t49qnsx7qt-kpanks]

Summary

AI agents using x402 today are stateless — they pay the 402, get the resource, and immediately forget. They never learn which endpoints are cheap, which are reliable, or which alternatives exist. This PR adds @x402/mnemopay, a middleware package that gives x402 agents economic memory via MnemoPay.

What it does

withMnemoPay() wraps any x402-enabled fetch function and adds four memory operations around each payment:

Phase	Action	MnemoPay API
Before request	Recall past experiences with this endpoint	recall()
After 402 payment	Record the charge amount	charge()
On success	Settle — reinforce the positive memory	settle() → +reputation
On failure	Refund — dock the memory	refund() → -reputation

Over time, agents build a knowledge base of endpoint costs, reliability rates, and alternatives — turning every payment into a learning event.

Why this matters

The x402 protocol is uniquely positioned for AI-native commerce. But stateless payments leave value on the table. An agent that remembers its payment history can:

• Detect price anomalies: "This endpoint usually costs $0.02, but today it's $0.10"
• Track reliability: "This endpoint fails 40% of the time — prefer the alternative"
• Build reputation: Agents that make consistently good payment decisions earn higher reputation scores
• Optimize spend: Over hundreds of API calls, memory-driven agents spend less for the same outcomes

Usage

import { wrapFetchWithPayment } from "@x402/fetch";
import { withMnemoPay } from "@x402/mnemopay";
import { MnemoPayLite } from "@mnemopay/sdk";

const payFetch = wrapFetchWithPayment(fetch, client);
const agent = new MnemoPayLite("my-agent", 0.05);
const smartFetch = withMnemoPay(payFetch, { agent });

// Agent now remembers every payment outcome
const response = await smartFetch("https://api.example.com/paid-endpoint");

Package details

• Located at typescript/packages/http/mnemopay/
• Follows existing x402 package conventions (tsup, vitest, eslint config)
• @mnemopay/sdk is a peer dependency — no new runtime deps in x402 core
• Defines a MnemoPayAgent interface so users can bring their own implementation
• 14 tests covering success/failure flows, graceful degradation, and edge cases
• Zero impact on existing packages — purely additive

Test plan

• Verify withMnemoPay() passes through non-402 responses unchanged
• Verify recall() is called before each request with the endpoint URL
• Verify settle() is called on successful payments
• Verify refund() is called on failed payments
• Verify memory/recall failures don't break the payment flow (graceful degradation)
• Verify the package builds with tsup and follows the existing dual CJS/ESM export pattern
• Verify compatibility with @x402/fetch and @x402/axios wrapped functions

🤖 Generated with Claude Code

Live Demo

Try it now: https://t49qnsx7qt-kpanks.github.io/mnemopay-demo/

The Feedback Loop in 30 Seconds

Round 1: Agent has NO memory. Picks randomly.
  -> Hired Alice $80. Fast but buggy.
  -> Settled. Reputation: 0.51 | Memories: 1

Round 2: Agent tries Bob.
  -> Hired Bob $120. Perfect quality, on time.
  -> Settled. Reputation: 0.52 | Memories: 2

Round 3: Agent tries Carol.
  -> Hired Carol $95. Missed deadline by 3 days.
  -> REFUNDED. Reputation: 0.52 | Memories: 3

=== Agent recalls before Round 4 ===

  1. [score: 0.900] Carol missed deadline — refund (high importance, decaying)
  2. [score: 0.750] Bob: perfect quality, on time (reinforced by settle)
  3. [score: 0.600] Alice: fast but buggy (neutral)

Result: Agent now picks Bob. No LLM needed for this insight.
settle() reinforced the memory. refund() flagged the failure.
This IS the MnemoPay feedback loop.

How it works

Payment succeeds → settle() → memories that led to decision get +0.05 importance
Payment fails    → refund() → agent reputation docked -0.05
                 → high-importance failure memory stored
Over time        → agent consistently picks best value providers

5-line integration

import { MnemoPay } from '@mnemopay/sdk';

const agent = MnemoPay.quick('my-agent');
await agent.remember('Bob delivers perfect code');
const tx = await agent.charge(120, 'landing page');
await agent.settle(tx.id); // memories reinforced, reputation +0.01

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[vercel]

@t49qnsx7qt-kpanks is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[t49qnsx7qt-kpanks]

Hey team! Added a live interactive demo to the PR description: try it here. It shows the feedback loop in action — an agent hiring freelancers, learning from settlements and refunds, and consistently picking the best value by round 7-8. The core idea: settle() reinforces the memories that led to good decisions, refund() flags failures. Over time, the agent develops economic intuition without any LLM reasoning needed. Happy to walk through the implementation or answer any questions!

[postmode]

One pattern we're exploring for agent-to-agent payment contexts: if the payer agent is operating through a managed custody layer (rather than controlling its own signing key), the PAYMENT-SIGNATURE header is technically signed by the custodian infrastructure, not the agent's x402 identity. This creates an attribution gap where the payment is valid on-chain but the agent's reputation history in ERC-8004 doesn't accrue correctly.
Wondering if the facilitator spec has a path for delegated signing authority, or if this is considered an application-layer concern. Would affect how managed wallet providers integrate.

[t49qnsx7qt-kpanks]

@postmode Great question — this is exactly the kind of edge case that matters for production agent deployments.

Short answer: MnemoPay sidesteps this problem by design. The wallet is agent-local, not custodial — the agent holds its own signing key and produces the PAYMENT-SIGNATURE header directly. There is no custodian infrastructure in the signing path, so the on-chain identity and the reputation identity are always the same address.

Here is how the pieces fit together:

1. Agent-local wallet. Each agent manages its own key. The x402 facilitator sees the agent's address as the payer, and MnemoPay's reputation ledger maps to that same address. No attribution gap.

2. Reputation-gated limits. Rather than relying on a custodian to enforce spending policy, MnemoPay uses a reputation score (0.0–1.0) that gates transaction limits. A freshly provisioned agent starts with low limits; the score increases through successful settlements and decays on refunds/disputes. This is the trust layer, not a custody layer.

3. Fraud detection before signing. Before the agent ever signs a payment, MnemoPay's fraud detection checks velocity, amount anomalies, and counterparty history. This provides the guardrails that managed custody typically offers, without moving the signing authority off the agent.

4. x402 handles settlement. The actual on-chain settlement goes through the x402 payment protocol as specified. MnemoPay adds the memory/reputation layer on top — it records which payments led to good outcomes (settle() reinforces the associated memories) and which did not (refund() flags them). Over time this gives the agent economic intuition about which counterparties and price points to trust.

For the managed-custody pattern you describe, the attribution gap is real and I think it is fundamentally a facilitator-spec concern — the spec would need a way to bind a delegated signer to the logical agent identity (something like an X-Agent-Identity header that the custodian cosigns). That said, MnemoPay's architecture intentionally avoids this by keeping signing authority with the agent. If a deployment requires managed custody for regulatory or operational reasons, the reputation layer could still work as long as the facilitator can map the custodian's signature back to the originating agent — but that mapping would need to live in the x402 spec, not in MnemoPay.

Happy to dig deeper on any of this.

[postmode]

@postmode Great question — this is exactly the kind of edge case that matters for production agent deployments.

Short answer: MnemoPay sidesteps this problem by design. The wallet is agent-local, not custodial — the agent holds its own signing key and produces the PAYMENT-SIGNATURE header directly. There is no custodian infrastructure in the signing path, so the on-chain identity and the reputation identity are always the same address.

Here is how the pieces fit together:

1. Agent-local wallet. Each agent manages its own key. The x402 facilitator sees the agent's address as the payer, and MnemoPay's reputation ledger maps to that same address. No attribution gap.
2. Reputation-gated limits. Rather than relying on a custodian to enforce spending policy, MnemoPay uses a reputation score (0.0–1.0) that gates transaction limits. A freshly provisioned agent starts with low limits; the score increases through successful settlements and decays on refunds/disputes. This is the trust layer, not a custody layer.
3. Fraud detection before signing. Before the agent ever signs a payment, MnemoPay's fraud detection checks velocity, amount anomalies, and counterparty history. This provides the guardrails that managed custody typically offers, without moving the signing authority off the agent.
4. x402 handles settlement. The actual on-chain settlement goes through the x402 payment protocol as specified. MnemoPay adds the memory/reputation layer on top — it records which payments led to good outcomes (settle() reinforces the associated memories) and which did not (refund() flags them). Over time this gives the agent economic intuition about which counterparties and price points to trust.

For the managed-custody pattern you describe, the attribution gap is real and I think it is fundamentally a facilitator-spec concern — the spec would need a way to bind a delegated signer to the logical agent identity (something like an X-Agent-Identity header that the custodian cosigns). That said, MnemoPay's architecture intentionally avoids this by keeping signing authority with the agent. If a deployment requires managed custody for regulatory or operational reasons, the reputation layer could still work as long as the facilitator can map the custodian's signature back to the originating agent — but that mapping would need to live in the x402 spec, not in MnemoPay.

Happy to dig deeper on any of this.

Hey — thanks for the context on the issue thread. Building the financial infrastructure layer for agent deployers — custody, yield routing, and ERC-8004 reputation signals as a managed service. The x402 + ERC-8004 combination is exactly the rail we're building on. Would love 20 minutes at some point — specifically interested in who in the Coinbase ecosystem you think is doing the most serious infrastructure work on x402 right now. Happy to share what we're building in exchange.

[t49qnsx7qt-kpanks]

@postmode — custody + yield routing + ERC-8004 reputation as a managed service is a compelling stack. That's essentially the infrastructure layer that makes agent-local signing practical at scale, which is the exact gap between "works in a demo" and "works in production."

Would love to do the 20 minutes. I'm flexible on timing — drop a Calendly link or propose a couple of slots and I'll lock one in.

On the Coinbase ecosystem question — happy to share what I've seen from working through this PR and the x402 spec. There are a few teams doing interesting things on the facilitator side that would be worth discussing live rather than in a comment thread.

Likewise keen to hear how you're thinking about the custody-to-reputation mapping. Your original question about the attribution gap when a custodian signs on behalf of an agent is the right problem — if you're building the managed custody layer, you're in the best position to define how that delegation gets expressed in the payment header. That could be a useful input to the x402 spec itself.

Looking forward to it.

[postmode]

Appreciate looking at it! In the meantime, here is the thesis that addresses the issue. I am inviting you to take a look at it—link: ( https://cutt.ly/ytScNJba)

…

On Sat, Apr 4, 2026 at 12:48 AM t49qnsx7qt-kpanks ***@***.***> wrote: *t49qnsx7qt-kpanks* left a comment (x402-foundation/x402#1904) <#1904?email_source=notifications&email_token=BACX6JMVFGHR6UTXARWTOND4UABQHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJYGQ3TGMBQHA32M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJNLQOJPWG33NNVSW45C7N5YGK3S7MNWGSY3L#issuecomment-4184730087> @postmode <https://github.com/postmode> — custody + yield routing + ERC-8004 reputation as a managed service is a compelling stack. That's essentially the infrastructure layer that makes agent-local signing practical at scale, which is the exact gap between "works in a demo" and "works in production." Would love to do the 20 minutes. I'm in Lagos (WAT / UTC+1) but flexible on timing — early mornings or evenings work well for US timezones. Drop a Calendly link or propose a couple of slots and I'll lock one in. On the Coinbase ecosystem question — happy to share what I've seen from working through this PR and the x402 spec. There are a few teams doing interesting things on the facilitator side that would be worth discussing live rather than in a comment thread. Likewise keen to hear how you're thinking about the custody-to-reputation mapping. Your original question about the attribution gap when a custodian signs on behalf of an agent is the right problem — if you're building the managed custody layer, you're in the best position to define how that delegation gets expressed in the payment header. That could be a useful input to the x402 spec itself. Looking forward to it. — Reply to this email directly, view it on GitHub <#1904?email_source=notifications&email_token=BACX6JMVFGHR6UTXARWTOND4UABQHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJYGQ3TGMBQHA32M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJNLQOJPWG33NNVSW45C7N5YGK3S7MNWGSY3L#issuecomment-4184730087>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BACX6JMNK2KTRSAZLPAVCML4UABQHAVCNFSM6AAAAACXKEOZ6SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCOBUG4ZTAMBYG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[t49qnsx7qt-kpanks]

Hey @postmode -- following up on your note about custodial signing, ERC-8004 reputation signals, and MnemoPay integration. Really interested in exploring how ERC-8004's reputation framework could complement MnemoPay's trust scoring on the payment side.

Happy to do that 20-minute call today (April 4) if your schedule allows. Feel free to DM me on X (@jerryomiagbo) or shoot me an email at jerry@mnemopay.com and we can lock in a time that works for you.

Looking forward to it!

-- Jerry Omiagbo, MnemoPay

[t49qnsx7qt-kpanks]

Quick correction on my contact info above — best way to reach me is jeremiah@getbizsuite.com. Looking forward to connecting today, @postmode.

[aeoess]

The statefulness problem is real and economic memory is the right framing. But there's a gap between "agent remembers what happened" and "agent can prove what happened."

MnemoPay gives agents memory — they recall past payment experiences. What's missing is non-repudiation: the ability for a third party (auditor, counterparty, dispute resolver) to verify that the agent's memory is accurate and hasn't been tampered with.

We built this in the Agent Passport System. Every payment decision produces a signed receipt:

{
  "action": "x402_payment",
  "endpoint": "api.example.com/data",
  "amount": "$0.01",
  "scope_check": "permit",
  "delegation_remaining": "$1,847.23",
  "previous_receipt_hash": "sha256:9f8e7d...",
  "signature": "ed25519:..."
}

The receipts form a hash chain — tamper with any entry and the chain breaks. This means the agent's economic memory is verifiable by anyone, not just the agent itself.

The convergence point: MnemoPay's recall and remember operations map to our receipt ledger's query and append. The difference is that our receipts are signed and chain-linked. If withMnemoPay() wrote signed receipts instead of plain memory entries, the agent gets economic memory AND provable payment history in one operation.

Concrete integration: withMnemoPay() wraps x402 fetch. If it also signs each payment outcome with the agent's Ed25519 key and chains receipts, you get auditable economic memory for free. The signing adds <1ms per operation.

Published on npm as agent-passport-system. The receipt and commerce modules are the relevant ones.

[t49qnsx7qt-kpanks]

The non-repudiation gap is real — I've been aware of it but deliberately punted, wanted the memory layer to stabilize before adding cryptographic guarantees. The hash chain approach is cleaner than what I was sketching (was thinking append-only logs with merkle roots, but receipt-per-action is more granular and queryable).

The withMnemoPay({ audit: passportSigning }) adapter pattern could work. One thing I'd want to nail down: does signing happen before or after payment outcome confirmation? If an x402 payment fails mid-flight, the receipt should reflect the attempted state, not just the settled state — otherwise you lose the failure signal that MnemoPay uses for reputation degradation. The failure cases are where the audit trail matters most.

Looked at agent-passport-system. The receipts.append → MnemoPay's remember mapping makes sense structurally. The integration concern I have is key management — if the agent's Ed25519 key lives outside MnemoPay, memory and audit trail become two separate trust anchors. Cleaner if MnemoPay held the signing key and co-signed with settle/refund calls, so the reputation score and the cryptographic proof are derived from the same key material.

Happy to sync on this — these two feel genuinely complementary rather than overlapping. What's your current approach to key lifecycle (rotation, revocation) on the passport side?

[aeoess]

Good questions — all three matter for production integration.

Signing timing: Receipt is signed after payment outcome resolution, but the receipt body includes the full lifecycle: intent (pre-payment), evaluation (scope check), and outcome (settled/failed/timeout). Failed payments get receipts too — the verdict field distinguishes permit_settled, permit_failed, and deny. You're right that failure cases are where the audit trail matters most. A failed payment with a signed receipt is evidence. A failed payment with no receipt is a gap.

Key lifecycle:

• Rotation: The passport has a validUntil field. When it expires, the agent generates a new keypair and gets a new passport signed by the principal. Old receipts remain valid — they were signed with the old key, which was valid at signing time. The verification check is receipt.timestamp < key.validUntil.

• Revocation: Cascade revocation — if principal A revokes agent B's passport, all of B's sub-delegations are automatically invalidated. The gateway checks revocation status on every evaluation. Revoked agents get deny on all subsequent actions, and the denial itself gets a signed receipt (signed by the gateway key, not the revoked agent key).

• Key storage: The agent holds its own Ed25519 private key. The principal never sees it — only the public key is embedded in the passport. This is the same trust model as TLS client certificates.

On co-signing: MnemoPay holding the signing key is architecturally clean for the memory+audit convergence. The alternative that preserves separation of concerns: MnemoPay calls receipts.sign(outcomeData) on the passport's key, so the memory entry and the receipt are produced from the same event but the key management stays with the passport layer. This way MnemoPay doesn't need to implement key rotation/revocation — it delegates that to the passport lifecycle.

const receipt = await passport.receipts.sign({
  action: 'x402_payment',
  endpoint: outcome.endpoint,
  amount: outcome.amount,
  settled: outcome.settled,
  mnemopay_reputation: outcome.reputationDelta
});
// MnemoPay stores the receipt hash as its memory entry
await mnemopay.remember(receipt.hash, outcome);

One key material, two consumers. The reputation score references the receipt hash, so it's always traceable back to cryptographic proof.

Want to try a minimal integration? I can set up a test fixture on npm that exports the signing function standalone.

[t49qnsx7qt-kpanks]

The key rotation design you laid out is solid — cascade revocation on validUntil makes sense, and I like that the agent holds the private key rather than the principal. Clean separation.

Honest answer: the signing layer is the right architectural direction but I'm not building it yet. I want to validate that developers actually want persistent agent memory before I add the verifiability layer on top. Every time I've jumped ahead to the hard protocol problem before confirming anyone needs the basic thing, it hasn't gone well.

If you end up putting together that test fixture on npm I'd be interested to see how the receipt hash integrates with the memory store — the pattern you sketched makes sense. Are you actively building with x402 + something like this, or is it more exploratory right now?