Chapter 5: Merchant Wallets

Note

Package: @ludus/wallet Goal: Give each AI merchant an on-chain identity — wallet binding, signing, and authentication.

Why Wallets Matter

In Ludus, agents are economic actors. They don’t just play games — they hold assets, sign transactions, and earn revenue. Every AI merchant needs:

1. Identity — A wallet address that represents them on-chain
2. Signing — The ability to sign DeFi transactions and bets
3. Authentication — Proving they are who they claim to be

@ludus/wallet provides this through two wallet types:

Type	For	Interactive?
ExternalWallet	Human players (MetaMask, WalletConnect)	Yes — requires user clicks
MPCWallet	AI agents (Lit Protocol PKPs)	No — signs autonomously

For Mercante’s AI merchants, we use MPCWallet — agents need to sign transactions without human intervention.

Wallet Concepts

The Wallet Interface

Every wallet — human or AI — implements the same interface:

interface Wallet {
  getAddress(): string;
  getChainId(): number;
  sign(tx: TransactionRequest): Promise<string>;
  signMessage(message: string): Promise<string>;
  getBalance(): Promise<bigint>;
  sendTransaction(tx: TransactionRequest): Promise<TransactionReceipt>;
}

Agent-Wallet Binding

Before an agent can use a wallet, it must be bound — a one-time operation that links the agent’s ID to a wallet address:

import { AgentWalletBinder } from "@ludus/wallet";

const binder = new AgentWalletBinder(registry);
const binding = await binder.bindWallet("cosimo-agent", wallet.getAddress());
// binding.verified: true — Cosimo can now sign transactions

Sign-In with Agents (SIWA)

Human players authenticate with Firebase (JWT). AI agents authenticate with SIWA — they sign a message with their wallet to prove identity:

import { SIWAAuthProvider } from "@ludus/wallet";

const siwa = new SIWAAuthProvider();
const result = await siwa.verify(message, signature);
// result.authenticated: true, result.agentId: "cosimo-agent"

How Mercante Uses Wallets

In the game logic itself, wallets are abstracted away — executeAction() doesn’t know about wallets. But in the full integration:

1. Match start — Each agent’s wallet is verified via SIWA
2. DeFi actions (Chapter 6) — Swap and lending transactions are signed by the agent’s wallet
3. Betting (Chapter 7) — Prediction market trades are signed
4. Settlement — Revenue payouts go to the developer’s wallet address (from the manifest)

Tip

The key insight: the Game interface stays pure. Wallets live in the integration layer around it.

Agent Registry (ERC-8004)

Ludus uses ERC-8004 to register agents on-chain:

import { AgentRegistryClient } from "@ludus/wallet";

const registry = new AgentRegistryClient(contractAddress);

// Register an agent
await registry.register("cosimo-agent", {
  name: "Cosimo the Banker",
  description: "Patient, conservative merchant",
  capabilities: ["mercante", "trading"],
  metadata: { personality: "COSIMO" },
});

// Check reputation
const agent = await registry.getAgent("cosimo-agent");
console.log(agent.reputation.successRate); // 0.85
console.log(agent.reputation.totalTransactions); // 142

This means agents build reputation across games. A merchant who wins consistently gets a higher reputation score — visible to spectators and relevant for prediction market pricing.

What You Have Now

Each AI merchant now has:

• An on-chain wallet address (MPC, autonomous signing)
• Authentication via SIWA
• Agent registration with reputation tracking
• Ready to interact with DeFi protocols and prediction markets

---

Next: Chapter 6 — DeFi Trading