@remitmd/sdk 0.1.0

package/src/x402.ts

@@ -0,0 +1,202 @@
+/**
+ * x402 client middleware for auto-paying HTTP 402 Payment Required responses.
+ *
+ * x402 is an open payment standard where resource servers return HTTP 402 with
+ * a `PAYMENT-REQUIRED` header describing the cost. This module provides a
+ * `fetch` wrapper that intercepts those responses, signs an EIP-3009
+ * authorization, and retries the request with a `PAYMENT-SIGNATURE` header.
+ *
+ * Usage:
+ *   ```typescript
+ *   import { PrivateKeySigner } from "@remitmd/sdk";
+ *   import { X402Client } from "@remitmd/sdk/x402";
+ *
+ *   const signer = new PrivateKeySigner("0x...");
+ *   const client = new X402Client({
+ *     signer,
+ *     address: signer.getAddress(),
+ *     maxAutoPayUsdc: 0.10,
+ *   });
+ *
+ *   const response = await client.fetch("https://api.provider.com/v1/data");
+ *   ```
+ */
+
+import { randomBytes } from "node:crypto";
+import type { Signer } from "./signer.js";
+
+/** EIP-712 type definitions for USDC's transferWithAuthorization (EIP-3009). */
+const EIP3009_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+/** Raised when an x402 payment amount exceeds the configured auto-pay limit. */
+export class AllowanceExceededError extends Error {
+  readonly amountUsdc: number;
+  readonly limitUsdc: number;
+
+  constructor(amountUsdc: number, limitUsdc: number) {
+    super(
+      `x402 payment ${amountUsdc.toFixed(6)} USDC exceeds auto-pay limit ${limitUsdc.toFixed(6)} USDC`,
+    );
+    this.name = "AllowanceExceededError";
+    this.amountUsdc = amountUsdc;
+    this.limitUsdc = limitUsdc;
+  }
+}
+
+/** Configuration for {@link X402Client}. */
+export interface X402ClientOptions {
+  /** Signer used for EIP-3009 authorization signatures. */
+  signer: Signer;
+  /** Checksummed payer address — must match the signer's public key. */
+  address: string;
+  /** Maximum USDC amount to auto-pay per request (default: 0.10). */
+  maxAutoPayUsdc?: number;
+}
+
+/** Shape of the base64-decoded PAYMENT-REQUIRED header (V2). */
+export interface PaymentRequired {
+  scheme: string;
+  network: string;
+  amount: string;
+  asset: string;
+  payTo: string;
+  maxTimeoutSeconds?: number;
+  // V2 optional fields — informational metadata about the resource being paid for.
+  /** URL or path of the resource being protected (e.g. "/api/v0/data"). */
+  resource?: string;
+  /** Human-readable description of what the payment is for. */
+  description?: string;
+  /** MIME type of the resource (e.g. "application/json"). */
+  mimeType?: string;
+}
+
+/**
+ * `fetch` wrapper that auto-handles HTTP 402 Payment Required responses.
+ *
+ * On receiving a 402, the client:
+ * 1. Decodes the `PAYMENT-REQUIRED` header (base64 JSON)
+ * 2. Checks the amount is within `maxAutoPayUsdc`
+ * 3. Builds and signs an EIP-3009 `transferWithAuthorization`
+ * 4. Base64-encodes the `PAYMENT-SIGNATURE` header
+ * 5. Retries the original request with payment attached
+ *
+ * V2: The decoded `PAYMENT-REQUIRED` may include `resource`, `description`,
+ * and `mimeType` fields. Access the last payment via `lastPayment`.
+ */
+export class X402Client {
+  readonly #signer: Signer;
+  readonly #address: string;
+  readonly #maxAutoPayUsdc: number;
+  /** The last PAYMENT-REQUIRED decoded before payment. Useful for logging/display. */
+  lastPayment: PaymentRequired | null = null;
+
+  constructor({ signer, address, maxAutoPayUsdc = 0.1 }: X402ClientOptions) {
+    this.#signer = signer;
+    this.#address = address;
+    this.#maxAutoPayUsdc = maxAutoPayUsdc;
+  }
+
+  /** Make a fetch request, auto-paying any 402 responses within the configured limit. */
+  async fetch(url: string, init?: RequestInit): Promise<Response> {
+    const response = await globalThis.fetch(url, init);
+    if (response.status === 402) {
+      return this.#handle402(url, response, init);
+    }
+    return response;
+  }
+
+  async #handle402(url: string, response: Response, init?: RequestInit): Promise<Response> {
+    // 1. Decode PAYMENT-REQUIRED header (header names are case-insensitive per HTTP spec).
+    const raw = response.headers.get("payment-required");
+    if (!raw) {
+      throw new Error("402 response missing PAYMENT-REQUIRED header");
+    }
+    const required = JSON.parse(Buffer.from(raw, "base64").toString("utf8")) as PaymentRequired;
+
+    // 2. Only the "exact" scheme is supported in V5.
+    if (required.scheme !== "exact") {
+      throw new Error(`Unsupported x402 scheme: ${required.scheme}`);
+    }
+
+    // Store for caller inspection (V2 fields: resource, description, mimeType).
+    this.lastPayment = required;
+
+    // 3. Check auto-pay limit.
+    const amountBaseUnits = BigInt(required.amount);
+    const amountUsdc = Number(amountBaseUnits) / 1_000_000;
+    if (amountUsdc > this.#maxAutoPayUsdc) {
+      throw new AllowanceExceededError(amountUsdc, this.#maxAutoPayUsdc);
+    }
+
+    // 4. Parse chainId from CAIP-2 network string (e.g. "eip155:84532" → 84532).
+    const chainId = parseInt(required.network.split(":")[1]!, 10);
+
+    // 5. Build EIP-3009 authorization fields.
+    const nowSecs = Math.floor(Date.now() / 1000);
+    const validBefore = nowSecs + (required.maxTimeoutSeconds ?? 60);
+    const nonce = `0x${randomBytes(32).toString("hex")}` as `0x${string}`;
+
+    const domain = {
+      name: "USD Coin",
+      version: "2",
+      chainId,
+      verifyingContract: required.asset as `0x${string}`,
+    };
+
+    // viem requires uint256 values as bigint.
+    const message = {
+      from: this.#address as `0x${string}`,
+      to: required.payTo as `0x${string}`,
+      value: amountBaseUnits,
+      validAfter: BigInt(0),
+      validBefore: BigInt(validBefore),
+      nonce,
+    };
+
+    // 6. Sign EIP-712 typed data.
+    const signature = await this.#signer.signTypedData(
+      domain,
+      // Cast: EIP3009_TYPES satisfies TypedDataTypes but has readonly arrays.
+      EIP3009_TYPES as unknown as Record<string, Array<{ name: string; type: string }>>,
+      message as unknown as Record<string, unknown>,
+    );
+
+    // 7. Build PAYMENT-SIGNATURE JSON payload.
+    const paymentPayload = {
+      scheme: required.scheme,
+      network: required.network,
+      x402Version: 1,
+      payload: {
+        signature,
+        authorization: {
+          from: this.#address,
+          to: required.payTo,
+          value: required.amount, // string (base units)
+          validAfter: "0",
+          validBefore: String(validBefore),
+          nonce,
+        },
+      },
+    };
+    const paymentHeader = Buffer.from(JSON.stringify(paymentPayload)).toString("base64");
+
+    // 8. Retry with PAYMENT-SIGNATURE header.
+    const newHeaders = new Headers(init?.headers);
+    newHeaders.set("PAYMENT-SIGNATURE", paymentHeader);
+    return globalThis.fetch(url, { ...init, headers: newHeaders });
+  }
+
+  /** Prevent address leakage via structured cloning / serialisation. */
+  toJSON(): Record<string, string> {
+    return { address: this.#address };
+  }
+}

package/tests/acceptance/bounty.test.ts

@@ -0,0 +1,82 @@
+/**
+ * SDK acceptance: Bounty lifecycle via wallet.postBounty(), submitBounty(), awardBounty().
+ * Verifies SDK permit signing + full bounty lifecycle with balance assertions.
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import type { Wallet } from "../../src/wallet.js";
+import {
+  createWallet,
+  fundWallet,
+  getUsdcBalance,
+  getFeeWalletBalance,
+  assertBalanceChange,
+  waitForBalanceChange,
+} from "./setup.js";
+
+describe("SDK: Bounty Lifecycle", { timeout: 180_000 }, () => {
+  let poster: Wallet;
+  let provider: Wallet;
+
+  before(async () => {
+    poster = await createWallet();
+    provider = await createWallet();
+    await fundWallet(poster, 100);
+  });
+
+  it("postBounty → submitBounty → awardBounty with correct balances", async () => {
+    const amount = 5.0;
+    const fee = amount * 0.01; // 1% = $0.05
+    const providerReceives = amount - fee; // $4.95
+
+    const posterBefore = await getUsdcBalance(poster.address);
+    const providerBefore = await getUsdcBalance(provider.address);
+    const feeBefore = await getFeeWalletBalance();
+
+    // Step 1: Post bounty with permit for Bounty contract
+    const contracts = await poster.getContracts();
+    const permit = await poster.signPermit(contracts.bounty, amount + 1);
+    const deadline = Math.floor(Date.now() / 1000) + 3600;
+
+    const bounty = await poster.postBounty({
+      amount,
+      task: "sdk-bounty-acceptance-test",
+      deadline,
+      permit,
+    });
+
+    assert.ok(bounty.id, "bounty should have an id");
+
+    // Wait for on-chain bounty creation (poster USDC locked in Bounty contract)
+    await waitForBalanceChange(poster.address, posterBefore);
+
+    // Step 2: Provider submits evidence
+    const evidenceHash = `0x${"ab".repeat(32)}`;
+    const submission = await provider.submitBounty(bounty.id, evidenceHash);
+    const submissionId =
+      (submission as unknown as Record<string, number>).id ??
+      (submission as unknown as Record<string, number>).submissionId;
+
+    // Wait for submission tx
+    await new Promise((r) => setTimeout(r, 5000));
+
+    // Step 3: Poster awards to the submission
+    const awarded = await poster.awardBounty(bounty.id, submissionId);
+    const awardedStatus =
+      awarded.status ?? (awarded as unknown as Record<string, string>).status;
+    assert.equal(awardedStatus, "awarded", "bounty should be awarded");
+
+    // Verify balances
+    const providerAfter = await waitForBalanceChange(provider.address, providerBefore);
+    const feeAfter = await getFeeWalletBalance();
+    const posterAfter = await getUsdcBalance(poster.address);
+
+    // Poster: lost $5 (bounty amount)
+    assertBalanceChange("poster", posterBefore, posterAfter, -amount);
+    // Provider: received $5 minus 1% fee = $4.95
+    assertBalanceChange("provider", providerBefore, providerAfter, providerReceives);
+    // Fee wallet: received 1% of $5 = $0.05
+    assertBalanceChange("fee wallet", feeBefore, feeAfter, fee);
+  });
+});

package/tests/acceptance/deposit.test.ts

@@ -0,0 +1,70 @@
+/**
+ * SDK acceptance: Deposit lifecycle via wallet.placeDeposit(), returnDeposit().
+ * Verifies SDK permit signing + deposit lock/return with full refund (no fee).
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import type { Wallet } from "../../src/wallet.js";
+import {
+  createWallet,
+  fundWallet,
+  getUsdcBalance,
+  getFeeWalletBalance,
+  assertBalanceChange,
+  waitForBalanceChange,
+} from "./setup.js";
+
+describe("SDK: Deposit Lifecycle", { timeout: 180_000 }, () => {
+  let agent: Wallet;
+  let provider: Wallet;
+
+  before(async () => {
+    agent = await createWallet();
+    provider = await createWallet();
+    await fundWallet(agent, 100);
+  });
+
+  it("placeDeposit → returnDeposit with full refund (no fee)", async () => {
+    const amount = 5.0;
+
+    const agentBefore = await getUsdcBalance(agent.address);
+    const providerBefore = await getUsdcBalance(provider.address);
+    const feeBefore = await getFeeWalletBalance();
+
+    // Step 1: Place deposit with permit for Deposit contract
+    const contracts = await agent.getContracts();
+    const permit = await agent.signPermit(contracts.deposit, amount + 1);
+
+    const deposit = await agent.placeDeposit({
+      to: provider.address,
+      amount,
+      expires: 3600, // 1 hour
+      permit,
+    });
+
+    assert.ok(deposit.id, "deposit should have an id");
+
+    // Wait for on-chain deposit lock
+    const agentMid = await waitForBalanceChange(agent.address, agentBefore);
+    assertBalanceChange("agent locked", agentBefore, agentMid, -amount);
+
+    // Step 2: Provider returns the deposit
+    const returned = await provider.returnDeposit(deposit.id);
+    const returnedStatus =
+      returned.status ?? (returned as unknown as Record<string, string>).status;
+    assert.equal(returnedStatus, "returned", "deposit should be returned");
+
+    // Wait for return settlement (agent gets full refund)
+    const agentAfter = await waitForBalanceChange(agent.address, agentMid);
+    const providerAfter = await getUsdcBalance(provider.address);
+    const feeAfter = await getFeeWalletBalance();
+
+    // Agent: full refund — net change ≈ $0
+    assertBalanceChange("agent net", agentBefore, agentAfter, 0);
+    // Provider: unchanged
+    assertBalanceChange("provider", providerBefore, providerAfter, 0);
+    // Fee wallet: unchanged (deposits have no fee)
+    assertBalanceChange("fee wallet", feeBefore, feeAfter, 0);
+  });
+});

package/tests/acceptance/direct.test.ts

@@ -0,0 +1,53 @@
+/**
+ * SDK acceptance: Direct payment via wallet.payDirect().
+ * Verifies SDK permit signing + payment works end-to-end.
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import type { Wallet } from "../../src/wallet.js";
+import {
+  createWallet,
+  fundWallet,
+  getUsdcBalance,
+  getFeeWalletBalance,
+  assertBalanceChange,
+  waitForBalanceChange,
+} from "./setup.js";
+
+describe("SDK: Direct Payment", { timeout: 120_000 }, () => {
+  let agent: Wallet;
+  let provider: Wallet;
+
+  before(async () => {
+    agent = await createWallet();
+    provider = await createWallet();
+    await fundWallet(agent, 100);
+  });
+
+  it("payDirect with signPermit — correct balances", async () => {
+    const amount = 1.0;
+    const fee = 0.01;
+    const providerReceives = amount - fee;
+
+    const agentBefore = await getUsdcBalance(agent.address);
+    const providerBefore = await getUsdcBalance(provider.address);
+    const feeBefore = await getFeeWalletBalance();
+
+    // SDK: get contracts, sign permit, pay
+    const contracts = await agent.getContracts();
+    const permit = await agent.signPermit(contracts.router, 2.0);
+    const tx = await agent.payDirect(provider.address, amount, "sdk-acceptance", { permit });
+
+    const txHash = tx.txHash ?? (tx as unknown as Record<string, string>).tx_hash;
+    assert.ok(txHash?.startsWith("0x"), `should return tx hash, got: ${txHash}`);
+
+    const agentAfter = await waitForBalanceChange(agent.address, agentBefore);
+    const providerAfter = await getUsdcBalance(provider.address);
+    const feeAfter = await getFeeWalletBalance();
+
+    assertBalanceChange("agent", agentBefore, agentAfter, -amount);
+    assertBalanceChange("provider", providerBefore, providerAfter, providerReceives);
+    assertBalanceChange("fee wallet", feeBefore, feeAfter, fee);
+  });
+});

package/tests/acceptance/escrow.test.ts

@@ -0,0 +1,67 @@
+/**
+ * SDK acceptance: Escrow lifecycle via wallet.pay(), claimStart(), releaseEscrow().
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import type { Wallet } from "../../src/wallet.js";
+import {
+  createWallet,
+  fundWallet,
+  getUsdcBalance,
+  getFeeWalletBalance,
+  assertBalanceChange,
+  waitForBalanceChange,
+} from "./setup.js";
+
+describe("SDK: Escrow Lifecycle", { timeout: 180_000 }, () => {
+  let agent: Wallet;
+  let provider: Wallet;
+
+  before(async () => {
+    agent = await createWallet();
+    provider = await createWallet();
+    await fundWallet(agent, 100);
+  });
+
+  it("pay → claimStart → release with correct balances", async () => {
+    const amount = 5.0;
+    const fee = amount * 0.01;
+    const providerReceives = amount - fee;
+
+    const agentBefore = await getUsdcBalance(agent.address);
+    const providerBefore = await getUsdcBalance(provider.address);
+    const feeBefore = await getFeeWalletBalance();
+
+    // Sign permit for Escrow contract
+    const contracts = await agent.getContracts();
+    const permit = await agent.signPermit(contracts.escrow, amount + 1);
+
+    // Fund escrow
+    const escrow = await agent.pay(
+      { to: provider.address, amount, memo: "sdk-escrow-test" },
+      { permit },
+    );
+    const escrowId = escrow.invoiceId ?? (escrow as unknown as Record<string, string>).invoice_id;
+    assert.ok(escrowId, "escrow should have id");
+
+    // Wait for lock
+    await waitForBalanceChange(agent.address, agentBefore);
+
+    // Provider claims
+    await provider.claimStart(escrowId);
+    await new Promise((r) => setTimeout(r, 5000));
+
+    // Agent releases
+    await agent.releaseEscrow(escrowId);
+
+    // Verify balances
+    const providerAfter = await waitForBalanceChange(provider.address, providerBefore);
+    const feeAfter = await getFeeWalletBalance();
+    const agentAfter = await getUsdcBalance(agent.address);
+
+    assertBalanceChange("agent", agentBefore, agentAfter, -amount);
+    assertBalanceChange("provider", providerBefore, providerAfter, providerReceives);
+    assertBalanceChange("fee wallet", feeBefore, feeAfter, fee);
+  });
+});

package/tests/acceptance/setup.ts

@@ -0,0 +1,113 @@
+/**
+ * SDK acceptance test harness.
+ *
+ * Uses SDK Wallet to interact with the live Base Sepolia API.
+ * No raw HTTP — everything goes through SDK methods.
+ */
+
+import { Wallet } from "../../src/wallet.js";
+import { generatePrivateKey } from "viem/accounts";
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+export const API_URL = process.env["ACCEPTANCE_API_URL"] ?? "https://remit.md/api/v0";
+export const RPC_URL = process.env["ACCEPTANCE_RPC_URL"] ?? "https://sepolia.base.org";
+export const FEE_WALLET = "0xd3f721BDF92a2bB5Dd8d2FE2AFC03aFE5629B420";
+
+// ─── Router address (fetched once from /contracts) ──────────────────────────
+
+let _routerAddress: string | null = null;
+
+async function getRouterAddress(): Promise<string> {
+  if (_routerAddress) return _routerAddress;
+  const res = await fetch(`${API_URL}/contracts`);
+  if (!res.ok) throw new Error(`GET /contracts failed: ${res.status}`);
+  const data = (await res.json()) as { router: string };
+  _routerAddress = data.router;
+  return _routerAddress;
+}
+
+// ─── Wallet creation ────────────────────────────────────────────────────────
+
+export async function createWallet(): Promise<Wallet> {
+  const key = generatePrivateKey();
+  const routerAddress = await getRouterAddress();
+  return new Wallet({
+    privateKey: key,
+    chain: "base-sepolia",
+    apiUrl: API_URL,
+    rpcUrl: RPC_URL,
+    routerAddress,
+  });
+}
+
+// ─── Funding ────────────────────────────────────────────────────────────────
+
+/** Mint testnet USDC and wait for on-chain confirmation. */
+export async function fundWallet(wallet: Wallet, amount = 100): Promise<void> {
+  await wallet.mint(amount);
+  // Wait for balance via RPC (doesn't require auth)
+  await waitForBalanceChange(wallet.address, 0);
+}
+
+// ─── On-chain balance via RPC ───────────────────────────────────────────────
+
+/** Read USDC balance via RPC eth_call to balanceOf(address). Returns USD. */
+export async function getUsdcBalance(address: string): Promise<number> {
+  const paddedAddr = address.toLowerCase().replace("0x", "").padStart(64, "0");
+  const data = `0x70a08231${paddedAddr}`;
+  const usdcAddress = "0x142aD61B8d2edD6b3807D9266866D97C35Ee0317";
+
+  const res = await fetch(RPC_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "eth_call",
+      params: [{ to: usdcAddress, data }, "latest"],
+    }),
+  });
+  const json = (await res.json()) as { result?: string; error?: { message: string } };
+  if (json.error) throw new Error(`RPC balanceOf error: ${json.error.message}`);
+  return Number(BigInt(json.result ?? "0x0")) / 1e6;
+}
+
+export async function getFeeWalletBalance(): Promise<number> {
+  return getUsdcBalance(FEE_WALLET);
+}
+
+/** Wait for a balance change (polls every 2s, up to maxWait). */
+export async function waitForBalanceChange(
+  address: string,
+  beforeBalance: number,
+  maxWaitMs = 30000,
+): Promise<number> {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    const current = await getUsdcBalance(address);
+    if (Math.abs(current - beforeBalance) > 0.0001) return current;
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  return getUsdcBalance(address);
+}
+
+/** Assert a balance changed by expected delta within tolerance. */
+export function assertBalanceChange(
+  label: string,
+  before: number,
+  after: number,
+  expectedDelta: number,
+  toleranceBps = 10,
+): void {
+  const actualDelta = after - before;
+  const tolerance = Math.abs(expectedDelta) * (toleranceBps / 10000);
+  const diff = Math.abs(actualDelta - expectedDelta);
+
+  if (diff > tolerance) {
+    throw new Error(
+      `${label}: expected delta ${expectedDelta}, got ${actualDelta} ` +
+      `(before=${before}, after=${after}, tolerance=${tolerance})`,
+    );
+  }
+}

package/tests/acceptance/stream.test.ts

@@ -0,0 +1,98 @@
+/**
+ * SDK acceptance: Stream lifecycle via wallet.openStream(), closeStream().
+ * Verifies SDK permit signing + stream accrual + close with balance bounds.
+ *
+ * Stream accrual is time-dependent (block timestamps). We use generous bounds
+ * and conservation-of-funds checks rather than exact delta assertions.
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import type { Wallet } from "../../src/wallet.js";
+import {
+  createWallet,
+  fundWallet,
+  getUsdcBalance,
+  getFeeWalletBalance,
+  waitForBalanceChange,
+} from "./setup.js";
+
+describe("SDK: Stream Lifecycle", { timeout: 180_000 }, () => {
+  let agent: Wallet;
+  let provider: Wallet;
+
+  before(async () => {
+    agent = await createWallet();
+    provider = await createWallet();
+    await fundWallet(agent, 100);
+  });
+
+  it("openStream → wait → closeStream with correct balance bounds", async () => {
+    const ratePerSecond = 0.1; // $0.10/s
+    const maxTotal = 5.0;
+
+    const agentBefore = await getUsdcBalance(agent.address);
+    const providerBefore = await getUsdcBalance(provider.address);
+    const feeBefore = await getFeeWalletBalance();
+
+    // Step 1: Open stream with permit for Stream contract
+    const contracts = await agent.getContracts();
+    const permit = await agent.signPermit(contracts.stream, maxTotal + 1);
+
+    const stream = await agent.openStream({
+      to: provider.address,
+      rate: ratePerSecond,
+      maxTotal,
+      permit,
+    });
+
+    assert.ok(stream.id, "stream should have an id");
+
+    // Wait for on-chain creation (agent locks maxTotal in Stream contract)
+    await waitForBalanceChange(agent.address, agentBefore);
+
+    // Step 2: Wait for accrual (~5 seconds real time)
+    await new Promise((r) => setTimeout(r, 5000));
+
+    // Step 3: Close stream (payer only, no body)
+    const closed = await agent.closeStream(stream.id);
+    const closedStatus = closed.status ?? (closed as unknown as Record<string, string>).status;
+    assert.equal(closedStatus, "closed", "stream should be closed");
+
+    // Wait for settlement (provider balance should increase)
+    const providerAfter = await waitForBalanceChange(provider.address, providerBefore);
+    const feeAfter = await getFeeWalletBalance();
+    const agentAfter = await getUsdcBalance(agent.address);
+
+    // Calculate actual changes
+    const agentLoss = agentBefore - agentAfter;
+    const providerGain = providerAfter - providerBefore;
+    const feeGain = feeAfter - feeBefore;
+
+    // Agent should have lost money (stream accrued), but <= maxTotal
+    assert.ok(
+      agentLoss > 0.05,
+      `agent should have lost money from streaming, got loss=${agentLoss}`,
+    );
+    assert.ok(
+      agentLoss <= maxTotal + 0.01,
+      `agent loss should not exceed maxTotal ($${maxTotal}), got loss=${agentLoss}`,
+    );
+
+    // Provider should have received payout (accrued minus 1% fee)
+    assert.ok(
+      providerGain > 0.04,
+      `provider should have received payout, got gain=${providerGain}`,
+    );
+
+    // Fee wallet should not decrease
+    assert.ok(feeGain >= 0, `fee wallet should not decrease, got change=${feeGain}`);
+
+    // Conservation of funds: agent loss ≈ provider gain + fee
+    const conservationDiff = Math.abs(agentLoss - (providerGain + feeGain));
+    assert.ok(
+      conservationDiff < 0.01,
+      `conservation violated: agent lost ${agentLoss}, provider+fee gained ${providerGain + feeGain}, diff=${conservationDiff}`,
+    );
+  });
+});