@subly_fi/pay 0.1.0 → 0.2.0

package/dist/mcp-server.js

@@ -1,5 +1,4 @@
-// ../../demo/mcp-server.ts
-import { readFileSync as readFileSync2, writeFileSync } from "node:fs";
+// demo/mcp-server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -7,11 +6,11 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 
-// ../../src/client/agent-wallet-signer.ts
+// src/client/agent-wallet-signer.ts
 import { signBytes } from "@solana/kit";
 import bs584 from "bs58";
 
-// ../../src/solana/tx.ts
+// src/solana/tx.ts
 import bs58 from "bs58";
 import {
   appendTransactionMessageInstructions,
@@ -26,9 +25,8 @@ import {
   setTransactionMessageLifetimeUsingBlockhash
 } from "@solana/kit";
 
-// ../../src/lib/hash.ts
+// src/lib/hash.ts
 import { createHash } from "node:crypto";
-var EMPTY_BODY_HASH = "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 function sha256TaggedHex(data) {
   return `sha256-${createHash("sha256").update(data).digest("hex")}`;
 }
@@ -52,7 +50,7 @@ function hashStableJson(value) {
   return sha256TaggedHex(stableStringify(value));
 }
 
-// ../../src/solana/tx.ts
+// src/solana/tx.ts
 function decodeSerializedTransaction(serializedBase64) {
   return getTransactionDecoder().decode(Buffer.from(serializedBase64, "base64"));
 }
@@ -72,11 +70,11 @@ function signatureBase58ForSigner(transaction, signer2) {
   return bs58.encode(signature);
 }
 
-// ../../src/client/transaction-intent-validator.ts
+// src/client/transaction-intent-validator.ts
 import bs583 from "bs58";
 import { getCompiledTransactionMessageDecoder } from "@solana/kit";
 
-// ../../src/config/constants.ts
+// src/config/constants.ts
 var PAYMENT_SCHEME = "subly-yield-exact";
 var SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 var SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
@@ -92,7 +90,7 @@ var SUBLY_VAULT = {
 };
 var USDC_DECIMALS = 6;
 
-// ../../src/domain/request-binding.ts
+// src/domain/request-binding.ts
 function computeRequestBindingHash(fields) {
   return hashStableJson({
     sellerRequestId: fields.sellerRequestId,
@@ -107,7 +105,7 @@ function computeRequestBindingHash(fields) {
   });
 }
 
-// ../../src/lib/associated-token-account.ts
+// src/lib/associated-token-account.ts
 import { createHash as createHash2 } from "node:crypto";
 import bs582 from "bs58";
 var PDA_MARKER = Buffer.from("ProgramDerivedAddress", "utf8");
@@ -125,12 +123,12 @@ function deriveAssociatedTokenAddress(params) {
     "associatedTokenProgramId"
   );
   for (let bump = 255; bump >= 0; bump -= 1) {
-    const address2 = createProgramAddress(
+    const address3 = createProgramAddress(
       [owner, tokenProgramId, mint, Uint8Array.of(bump)],
       associatedTokenProgramId
     );
-    if (address2 !== null) {
-      return bs582.encode(address2);
+    if (address3 !== null) {
+      return bs582.encode(address3);
     }
   }
   throw new Error("Unable to derive associated token account address");
@@ -199,7 +197,7 @@ function modPow(base, exponent, modulus) {
   return result;
 }
 
-// ../../src/client/transaction-intent-validator.ts
+// src/client/transaction-intent-validator.ts
 var COMPUTE_BUDGET_PROGRAM_ID = "ComputeBudget111111111111111111111111111111";
 var SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
 var ASSOCIATED_TOKEN_PROGRAM_ID2 = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
@@ -885,7 +883,7 @@ function readShortVec(bytes, startOffset) {
   return null;
 }
 
-// ../../src/client/agent-wallet-signer.ts
+// src/client/agent-wallet-signer.ts
 var LocalKeypairAgentWalletSigner = class {
   validationMode = "structured_intent_transaction";
   keyPairSigner;
@@ -955,7 +953,104 @@ var LocalKeypairAgentWalletSigner = class {
   }
 };
 
-// ../../src/client/lookup-tables.ts
+// src/api/wallet-auth.ts
+import { createHash as createHash3 } from "node:crypto";
+import bs585 from "bs58";
+import nacl from "tweetnacl";
+var WALLET_AUTH_WALLET_HEADER = "x-subly-wallet";
+var WALLET_AUTH_SIGNED_AT_HEADER = "x-subly-signed-at";
+var WALLET_AUTH_SIGNATURE_HEADER = "x-subly-signature";
+function sha256Hex(data) {
+  return createHash3("sha256").update(data, "utf8").digest("hex");
+}
+function walletAuthMessage(params) {
+  return new TextEncoder().encode(
+    `subly-api:${params.method.toUpperCase()}:${params.path}:${sha256Hex(
+      params.rawBody
+    )}:${params.signedAtMs}`
+  );
+}
+
+// src/client/wallet-auth-headers.ts
+async function walletAuthHeaders(params) {
+  const signedAtMs = String(Date.now());
+  const message = walletAuthMessage({
+    method: params.method,
+    path: new URL(params.url).pathname,
+    rawBody: params.body ?? "",
+    signedAtMs
+  });
+  return {
+    [WALLET_AUTH_WALLET_HEADER]: params.signer.walletAddress,
+    [WALLET_AUTH_SIGNED_AT_HEADER]: signedAtMs,
+    [WALLET_AUTH_SIGNATURE_HEADER]: await params.signer.signApiMessage(message)
+  };
+}
+
+// src/client/onboarding.ts
+var SELF_SERVE_POLICY_ID = "self-serve";
+var OnboardingError = class extends Error {
+  constructor(step, message, detail = null) {
+    super(message);
+    this.step = step;
+    this.detail = detail;
+    this.name = "OnboardingError";
+  }
+  step;
+  detail;
+};
+async function ensureWalletOnboarded(params) {
+  const fetchImpl = params.fetchImpl ?? fetch;
+  const baseUrl = params.facilitatorBaseUrl.replace(/\/$/, "");
+  const post = async (step, path, body) => {
+    const url = `${baseUrl}${path}`;
+    const serialized = JSON.stringify(body);
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...await walletAuthHeaders({
+          signer: params.signer,
+          method: "POST",
+          url,
+          body: serialized
+        }),
+        "content-type": "application/json"
+      },
+      body: serialized
+    });
+    if (response.status !== 200) {
+      let detail = null;
+      try {
+        detail = await response.json();
+      } catch {
+        detail = null;
+      }
+      throw new OnboardingError(
+        step,
+        `wallet onboarding ${step} failed with ${response.status}`,
+        detail
+      );
+    }
+  };
+  const wallet = params.signer.walletAddress;
+  await post("register", "/v1/wallets/agent", {
+    wallet,
+    signingPolicyId: SELF_SERVE_POLICY_ID,
+    signingMode: "non_interactive",
+    signerValidationMode: params.signer.validationMode,
+    signerProvider: "local-keypair",
+    activateForPayments: true
+  });
+  await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain" });
+}
+
+// src/client/standard-x402-factory.ts
+import { createX402Client } from "x402-solana/client";
+
+// src/client/relayer-yield-realizer.ts
+import { address as address2 } from "@solana/kit";
+
+// src/client/lookup-tables.ts
 import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
 import { address, getCompiledTransactionMessageDecoder as getCompiledTransactionMessageDecoder2 } from "@solana/kit";
 function lookupTableAddressesForTransaction(serializedTransaction) {
@@ -995,12 +1090,143 @@ async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
   return result;
 }
 
-// ../../src/x402/headers.ts
+// src/client/relayer-yield-realizer.ts
+var RelayerRealizeError = class extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+    this.name = "RelayerRealizeError";
+  }
+  code;
+  detail;
+};
+var RelayerYieldRealizer = class {
+  config;
+  signer;
+  rpc;
+  fetchImpl;
+  lookupTablesFor;
+  constructor(config) {
+    this.config = {
+      facilitatorBaseUrl: config.facilitatorBaseUrl.replace(/\/$/, ""),
+      usdcMint: config.usdcMint ?? SUBLY_VAULT.usdcMint
+    };
+    this.signer = config.signer;
+    this.rpc = config.rpc;
+    this.fetchImpl = config.fetchImpl ?? fetch;
+    this.lookupTablesFor = config.lookupTablesFor ?? ((serializedTransaction) => fetchLookupTablesForTransaction(this.rpc, serializedTransaction));
+  }
+  async ensureUsdcAvailable(input) {
+    const agentAta = deriveAssociatedTokenAddress({
+      owner: this.signer.walletAddress,
+      mint: this.config.usdcMint
+    });
+    const currentBalance = await this.readTokenBalance(agentAta);
+    if (currentBalance >= input.amountRawUsdc) {
+      return { realizedRawUsdc: 0n, txSignature: null };
+    }
+    const shortfallRawUsdc = input.amountRawUsdc - currentBalance;
+    await this.assertSpendableYield(shortfallRawUsdc);
+    const prepared = await this.postJson("/v1/withdrawals/prepare", {
+      wallet: this.signer.walletAddress,
+      amountRawUsdc: shortfallRawUsdc.toString()
+    });
+    const signed = await this.signer.signWithdrawal({
+      intent: prepared.signingIntent,
+      serializedTransaction: prepared.serializedTransaction,
+      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
+    });
+    const submitted = await this.postJson("/v1/withdrawals/submit", {
+      withdrawalId: prepared.withdrawalId,
+      serializedTransaction: signed.serializedTransaction,
+      agentSignature: signed.agentSignature
+    });
+    if (submitted.status !== "confirmed" || submitted.txSignature === null) {
+      throw new RelayerRealizeError(
+        "realize_not_confirmed",
+        `yield realize withdrawal did not confirm (status=${submitted.status})`,
+        submitted
+      );
+    }
+    return {
+      realizedRawUsdc: BigInt(submitted.actualWithdrawRawUsdc ?? "0"),
+      txSignature: submitted.txSignature
+    };
+  }
+  /** Refuses to realize more than the ledger's spendable yield (principal). */
+  async assertSpendableYield(shortfallRawUsdc) {
+    const url = `${this.config.facilitatorBaseUrl}/v1/wallets/${this.signer.walletAddress}/budget`;
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        headers: await walletAuthHeaders({
+          signer: this.signer,
+          method: "GET",
+          url
+        })
+      });
+    } catch (error) {
+      throw new RelayerRealizeError(
+        "budget_unavailable",
+        "could not read the spendable-yield budget",
+        error
+      );
+    }
+    if (response.status !== 200) {
+      throw new RelayerRealizeError(
+        "budget_unavailable",
+        `budget endpoint returned ${response.status}`
+      );
+    }
+    const body = await response.json();
+    const spendable = BigInt(body.budget?.spendableYieldRawUsdc ?? "0");
+    if (spendable < shortfallRawUsdc) {
+      throw new RelayerRealizeError(
+        "insufficient_yield",
+        `spendable yield ${spendable} cannot cover ${shortfallRawUsdc} raw USDC; the principal is never spent \u2014 wait for more yield`,
+        { spendableYieldRawUsdc: spendable.toString() }
+      );
+    }
+  }
+  async postJson(path, body) {
+    const url = `${this.config.facilitatorBaseUrl}${path}`;
+    const serialized = JSON.stringify(body);
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...await walletAuthHeaders({
+          signer: this.signer,
+          method: "POST",
+          url,
+          body: serialized
+        }),
+        "content-type": "application/json"
+      },
+      body: serialized
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      throw new RelayerRealizeError(
+        path.endsWith("/submit") ? "submit_failed" : "prepare_failed",
+        `${path} failed with ${response.status}: ${text}`
+      );
+    }
+    return JSON.parse(text);
+  }
+  async readTokenBalance(ata) {
+    try {
+      const response = await this.rpc.getTokenAccountBalance(address2(ata), { commitment: "confirmed" }).send();
+      return BigInt(response.value.amount);
+    } catch {
+      return 0n;
+    }
+  }
+};
+
+// src/x402/headers.ts
 import { z } from "zod";
 var PAYMENT_REQUIRED_HEADER = "payment-required";
-var PAYMENT_SIGNATURE_HEADER = "payment-signature";
-var PAYMENT_RESPONSE_HEADER = "payment-response";
-var X402_VERSION = 2;
 var MAX_HEADER_JSON_BYTES = 16384;
 var X402HeaderError = class extends Error {
   reason;
@@ -1047,16 +1273,6 @@ var sublyPaymentPayloadSchema = z.object({
     temporarySettlementSignature: z.string().min(1).max(128)
   })
 }).loose();
-function encodeX402Header(value) {
-  const json = JSON.stringify(value);
-  if (Buffer.byteLength(json, "utf8") > MAX_HEADER_JSON_BYTES) {
-    throw new X402HeaderError(
-      "header_too_large",
-      `x402 header JSON exceeds ${MAX_HEADER_JSON_BYTES} bytes`
-    );
-  }
-  return Buffer.from(json, "utf8").toString("base64");
-}
 function decodeX402Header(headerValue) {
   if (headerValue.length > Math.ceil(MAX_HEADER_JSON_BYTES * 4 / 3) + 4) {
     throw new X402HeaderError(
@@ -1074,375 +1290,249 @@ function decodeX402Header(headerValue) {
     );
   }
 }
-function decodePaymentRequiredHeader(headerValue) {
-  const parsed = paymentRequiredSchema.safeParse(decodeX402Header(headerValue));
+
+// src/x402/standard-requirements.ts
+import { z as z2 } from "zod";
+var STANDARD_EXACT_SCHEME = "exact";
+var standardExactRequirementSchema = z2.object({
+  scheme: z2.literal(STANDARD_EXACT_SCHEME),
+  /** CAIP-2 chain id, e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp". */
+  network: z2.string().min(1),
+  /** SPL mint (Solana) or token contract (EVM); Subly only pays USDC/Solana. */
+  asset: z2.string().min(1),
+  /** Exact price in the asset's atomic units, as a decimal string. */
+  amount: z2.string().regex(/^[1-9]\d*$/),
+  /** Recipient wallet; the transfer destination ATA is derived from it. */
+  payTo: z2.string().min(1),
+  maxTimeoutSeconds: z2.number().int().positive().optional(),
+  extra: z2.object({
+    /** Facilitator address that pays the tx fee (gas sponsorship). */
+    feePayer: z2.string().min(1).optional()
+  }).loose().optional()
+}).loose();
+var standardPaymentRequiredSchema = z2.object({
+  x402Version: z2.number().int(),
+  accepts: z2.array(z2.unknown()),
+  error: z2.string().optional(),
+  resource: z2.object({ url: z2.string().optional() }).loose().optional()
+}).loose();
+var StandardX402ChallengeError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "StandardX402ChallengeError";
+    this.reason = reason;
+  }
+};
+function parseStandardChallenge(challenge) {
+  const parsed = standardPaymentRequiredSchema.safeParse(challenge);
   if (!parsed.success) {
-    throw new X402HeaderError(
+    throw new StandardX402ChallengeError(
       "invalid_payment_required",
-      "PAYMENT-REQUIRED header is not a valid x402 PaymentRequired object"
+      "Response is not a valid x402 PaymentRequired object"
     );
   }
-  const sublyRequirements = parsed.data.accepts.flatMap((candidate) => {
-    const requirement = sublyPaymentRequirementsSchema.safeParse(candidate);
-    return requirement.success ? [requirement.data] : [];
+  const solanaExactRequirements = parsed.data.accepts.flatMap((candidate) => {
+    const requirement = standardExactRequirementSchema.safeParse(candidate);
+    if (!requirement.success) {
+      return [];
+    }
+    return requirement.data.network.startsWith("solana:") ? [requirement.data] : [];
   });
-  return { paymentRequired: parsed.data, sublyRequirements };
+  return { paymentRequired: parsed.data, solanaExactRequirements };
 }
-function requestBodyHashFor(body) {
-  if (body === null || body === void 0 || body.length === 0) {
-    return EMPTY_BODY_HASH;
+function decodeStandardPaymentRequiredHeader(headerValue) {
+  let decoded;
+  try {
+    decoded = decodeX402Header(headerValue);
+  } catch (error) {
+    throw new StandardX402ChallengeError(
+      error instanceof X402HeaderError ? error.reason : "invalid_header",
+      "Cannot decode the payment-required header"
+    );
   }
-  return sha256TaggedHex(
-    typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body)
-  );
+  return parseStandardChallenge(decoded);
+}
+function selectPayableSolanaRequirement(requirements, options) {
+  const network = options?.network ?? SOLANA_MAINNET_NETWORK;
+  const usdcMint = options?.usdcMint ?? SUBLY_VAULT.usdcMint;
+  const requirement = requirements.find(
+    (candidate) => candidate.network === network && candidate.asset === usdcMint
+  ) ?? null;
+  if (requirement === null) {
+    throw new StandardX402ChallengeError(
+      "no_payable_requirement",
+      `The challenge has no Solana exact requirement on ${network} paying ${usdcMint}`
+    );
+  }
+  return {
+    requirement,
+    amountRawUsdc: BigInt(requirement.amount),
+    payTo: requirement.payTo,
+    feePayer: requirement.extra?.feePayer ?? null
+  };
 }
 
-// ../../src/client/paid-fetch.ts
-var PaidFetchError = class extends Error {
+// src/client/standard-x402-payer.ts
+var StandardX402PayError = class extends Error {
   constructor(reason, message, detail = null) {
     super(message);
     this.reason = reason;
     this.detail = detail;
-    this.name = "PaidFetchError";
+    this.name = "StandardX402PayError";
   }
   reason;
   detail;
 };
-var DEFAULT_PENDING_TTL_MS = 11e4;
-var DEFAULT_MAX_TRACKED_URLS = 1e3;
-var DEFAULT_MAX_BODY_CHARS = 2e4;
-function formatRawUsdcAmount(raw) {
-  const value = BigInt(raw);
-  const negative = value < 0n;
-  const abs = negative ? -value : value;
-  const whole = abs / 1000000n;
-  const frac = (abs % 1000000n).toString().padStart(6, "0");
-  return `${negative ? "-" : ""}${whole}.${frac}`;
-}
-var PaidFetchService = class {
-  signatureBuilder;
-  fetchImpl;
-  fetchBudget;
-  paymentStatusFor;
+var StandardX402Payer = class {
+  realizer;
+  x402Fetch;
+  probeFetch;
   defaultMaxAmountRawUsdc;
-  pendingTtlMs;
-  maxTrackedUrls;
-  maxBodyChars;
-  nowMs;
-  stateStore;
-  pending = /* @__PURE__ */ new Map();
-  inFlight = /* @__PURE__ */ new Map();
+  network;
+  usdcMint;
   constructor(config) {
-    this.signatureBuilder = config.signatureBuilder;
-    this.fetchImpl = config.fetchImpl ?? fetch;
-    this.fetchBudget = config.fetchBudget ?? (async () => null);
-    this.paymentStatusFor = config.paymentStatusFor ?? (async () => "indeterminate");
+    this.realizer = config.realizer;
+    this.x402Fetch = config.x402Fetch;
+    this.probeFetch = config.probeFetch ?? fetch;
     this.defaultMaxAmountRawUsdc = config.defaultMaxAmountRawUsdc;
-    this.pendingTtlMs = config.pendingTtlMs ?? DEFAULT_PENDING_TTL_MS;
-    this.maxTrackedUrls = config.maxTrackedUrls ?? DEFAULT_MAX_TRACKED_URLS;
-    this.maxBodyChars = config.maxBodyChars ?? DEFAULT_MAX_BODY_CHARS;
-    this.nowMs = config.nowMs ?? (() => Date.now());
-    this.stateStore = config.stateStore ?? null;
-    if (this.stateStore !== null) {
-      for (const record of this.stateStore.load()) {
-        const { url, ...entry } = record;
-        this.pending.set(url, entry);
-      }
-    }
-  }
-  /**
-   * GET the URL, paying a 402 challenge when needed. Concurrent calls for the
-   * same URL share one flow and one result.
-   */
-  paidFetch(params) {
-    const existing = this.inFlight.get(params.url);
-    if (existing !== void 0) {
-      return existing;
-    }
-    const flow = this.run(params).finally(() => {
-      this.inFlight.delete(params.url);
-    });
-    this.inFlight.set(params.url, flow);
-    return flow;
-  }
-  async run(params) {
-    const { url } = params;
-    const pending = this.pending.get(url);
-    if (pending !== void 0) {
-      const expired = this.nowMs() - pending.challengeAtMs > this.pendingTtlMs;
-      if (pending.unresolved || expired) {
-        if (params.forceNewPayment === true) {
-          this.untrack(url);
-        } else {
-          const outcome = await this.paymentStatusFor(pending.paymentId);
-          if (outcome === "not_settled") {
-            this.untrack(url);
-          } else if (outcome === "settled") {
-            throw new PaidFetchError(
-              "payment_already_settled",
-              `the previous payment for this URL settled (paymentId=${pending.paymentId}) but the content delivery was lost, and the signature can no longer be retried. Calling again with forceNewPayment=true will PAY A SECOND TIME for the same resource.`,
-              { paymentId: pending.paymentId }
-            );
-          } else {
-            throw new PaidFetchError(
-              "payment_outcome_unknown",
-              `a previously signed payment for this URL (paymentId=${pending.paymentId}) has an unknown outcome. Verify whether it settled before purchasing again; to pay again anyway, call this tool with forceNewPayment=true.`,
-              { paymentId: pending.paymentId }
-            );
-          }
-        }
-      } else {
-        return this.deliver(url, pending, {
-          retried: true,
-          budgetBefore: null
-        });
-      }
-    }
-    const challengeAtMs = this.nowMs();
-    const first = await this.fetchImpl(url);
-    const firstText = await first.text();
-    if (first.status !== 402) {
-      return {
-        paid: false,
-        status: first.status,
-        body: this.truncated(firstText)
-      };
-    }
-    const challengeHeader = first.headers.get(PAYMENT_REQUIRED_HEADER);
-    if (challengeHeader === null) {
-      throw new PaidFetchError(
-        "invalid_challenge",
-        "402 response is missing the PAYMENT-REQUIRED header"
-      );
-    }
-    const requirement = decodePaymentRequiredHeader(challengeHeader).sublyRequirements[0];
-    if (requirement === void 0) {
-      throw new PaidFetchError(
-        "invalid_challenge",
-        "402 challenge contains no subly-yield-exact requirement"
-      );
+    this.network = config.network ?? SOLANA_MAINNET_NETWORK;
+    this.usdcMint = config.usdcMint ?? SUBLY_VAULT.usdcMint;
+  }
+  async pay(input) {
+    const init = {
+      method: input.method ?? "GET",
+      ...input.body === void 0 ? {} : { body: input.body },
+      ...input.headers === void 0 ? {} : { headers: input.headers }
+    };
+    const probe = await this.probeFetch(input.url, init);
+    if (probe.status !== 402) {
+      return { paid: false, status: probe.status, body: await probe.text() };
     }
-    const amountRawUsdc = BigInt(requirement.amountRawUsdc);
-    const maxAmountRawUsdc = params.maxAmountRawUsdc ?? this.defaultMaxAmountRawUsdc;
-    if (amountRawUsdc > maxAmountRawUsdc) {
-      throw new PaidFetchError(
+    const selected = await this.selectRequirement(probe);
+    const cap = input.maxAmountRawUsdc ?? this.defaultMaxAmountRawUsdc;
+    if (selected.amountRawUsdc > cap) {
+      throw new StandardX402PayError(
         "amount_exceeds_client_cap",
-        `the challenge demands ${formatRawUsdcAmount(amountRawUsdc)} USDC, above this tool call's cap of ${formatRawUsdcAmount(maxAmountRawUsdc)} USDC; nothing was paid. Raise maxAmountRawUsdc only if this price is expected.`,
-        {
-          amountRawUsdc: requirement.amountRawUsdc,
-          maxAmountRawUsdc: maxAmountRawUsdc.toString(),
-          payTo: requirement.payTo
-        }
+        `the challenge demands ${selected.amountRawUsdc} raw USDC, above the client cap of ${cap}; nothing was paid`,
+        { amountRawUsdc: selected.amountRawUsdc.toString(), payTo: selected.payTo }
       );
     }
-    const budgetBefore = await this.fetchBudget();
-    const { headerValue, paymentId } = await this.signatureBuilder.buildPaymentSignatureHeader({
-      paymentRequiredHeader: challengeHeader,
-      httpMethod: "GET",
-      url
-    });
-    const entry = {
-      headerValue,
-      paymentId,
-      amountUsdc: formatRawUsdcAmount(amountRawUsdc),
-      payTo: requirement.payTo,
-      challengeAtMs,
-      unresolved: false
-    };
-    this.track(url, entry);
-    return this.deliver(url, entry, { retried: false, budgetBefore });
-  }
-  /**
-   * Sends the signed PAYMENT-SIGNATURE retry. The tracked entry is removed
-   * only on confirmed delivery (200). A fresh 402 proves the signature can no
-   * longer settle, so the entry is kept as an unresolved marker; every other
-   * failure keeps it retryable so the next call reuses the same signature.
-   */
-  async deliver(url, entry, params) {
-    let second;
-    let secondText;
+    let realized;
     try {
-      second = await this.fetchImpl(url, {
-        headers: { [PAYMENT_SIGNATURE_HEADER]: entry.headerValue }
+      realized = await this.realizer.ensureUsdcAvailable({
+        amountRawUsdc: selected.amountRawUsdc
       });
-      secondText = await second.text();
     } catch (error) {
-      throw new PaidFetchError(
-        "delivery_failed_payment_pending",
-        `delivery request failed in flight (${error instanceof Error ? error.message : String(error)}); the payment (paymentId=${entry.paymentId}) is already signed and may settle. Call this tool again with the same URL to retry delivery with the same payment signature \u2014 do NOT treat this as unpaid.`,
-        { paymentId: entry.paymentId }
+      throw new StandardX402PayError(
+        "realize_failed",
+        `could not realize yield to cover ${selected.amountRawUsdc} raw USDC: ${error instanceof Error ? error.message : String(error)}`,
+        error
       );
     }
-    if (second.status === 200) {
-      this.untrack(url);
-      const transaction = receiptTransaction(second.headers);
-      return {
-        paid: true,
-        status: second.status,
-        body: this.truncated(secondText),
-        ...params.retried ? { retriedPendingPayment: true } : {},
-        payment: {
-          amountUsdc: entry.amountUsdc,
-          payTo: entry.payTo,
-          paymentId: entry.paymentId,
-          transaction,
-          solscanUrl: transaction === null ? null : `https://solscan.io/tx/${transaction}`,
-          budgetBefore: params.budgetBefore,
-          budgetAfter: await this.fetchBudget()
-        }
-      };
-    }
-    if (second.status === 402) {
-      entry.unresolved = true;
-      this.persist();
-      throw new PaidFetchError(
-        "payment_outcome_unknown",
-        `the seller no longer accepts the signed payment (paymentId=${entry.paymentId}); it may or may not have settled. Verify the payment before purchasing again; to pay again anyway, call this tool with forceNewPayment=true.`,
-        { paymentId: entry.paymentId }
+    const response = await this.x402Fetch(input.url, init);
+    const bodyText = await response.text();
+    if (response.status !== 200) {
+      throw new StandardX402PayError(
+        "delivery_failed",
+        `the x402 payment did not deliver (status ${response.status})`,
+        { status: response.status, body: bodyText }
       );
     }
-    throw new PaidFetchError(
-      "delivery_failed_payment_pending",
-      `paid delivery failed with ${second.status} (paymentId=${entry.paymentId}); the payment may already have settled. Call this tool again with the same URL to retry delivery with the same payment signature \u2014 do NOT treat this as unpaid.`,
-      {
-        paymentId: entry.paymentId,
-        status: second.status,
-        body: this.truncated(secondText)
+    return {
+      paid: true,
+      status: response.status,
+      body: bodyText,
+      payment: {
+        amountRawUsdc: selected.amountRawUsdc.toString(),
+        payTo: selected.payTo,
+        feePayer: selected.feePayer,
+        realizedRawUsdc: realized.realizedRawUsdc.toString(),
+        realizeTxSignature: realized.txSignature
       }
-    );
+    };
   }
-  track(url, entry) {
-    if (!this.pending.has(url) && this.pending.size >= this.maxTrackedUrls) {
-      const oldest = this.pending.keys().next();
-      if (!oldest.done) {
-        this.pending.delete(oldest.value);
+  /** Reads the challenge from the header (preferred) or the JSON body. */
+  async selectRequirement(probe) {
+    const header = probe.headers.get(PAYMENT_REQUIRED_HEADER);
+    let requirements;
+    try {
+      if (header !== null) {
+        requirements = decodeStandardPaymentRequiredHeader(header).solanaExactRequirements;
+      } else {
+        requirements = parseStandardChallenge(
+          await probe.json()
+        ).solanaExactRequirements;
       }
+    } catch (error) {
+      throw new StandardX402PayError(
+        error instanceof StandardX402ChallengeError ? error.reason : "invalid_challenge",
+        "could not parse the x402 402 challenge",
+        error
+      );
     }
-    this.pending.set(url, entry);
-    this.persist();
-  }
-  untrack(url) {
-    this.pending.delete(url);
-    this.persist();
-  }
-  persist() {
-    if (this.stateStore === null) {
-      return;
+    try {
+      return selectPayableSolanaRequirement(requirements, {
+        network: this.network,
+        usdcMint: this.usdcMint
+      });
+    } catch (error) {
+      throw new StandardX402PayError(
+        "no_payable_requirement",
+        error instanceof Error ? error.message : String(error),
+        error
+      );
     }
-    this.stateStore.save(
-      [...this.pending.entries()].map(([url, entry]) => ({ url, ...entry }))
-    );
-  }
-  truncated(text) {
-    return text.length > this.maxBodyChars ? `${text.slice(0, this.maxBodyChars)}
-... (truncated)` : text;
   }
 };
-function receiptTransaction(headers) {
-  try {
-    const receiptHeader = headers.get(PAYMENT_RESPONSE_HEADER);
-    if (receiptHeader === null) {
-      return null;
-    }
-    const receipt = decodeX402Header(receiptHeader);
-    return typeof receipt.transaction === "string" && receipt.transaction.length > 0 ? receipt.transaction : null;
-  } catch {
-    return null;
-  }
-}
 
-// ../../src/api/wallet-auth.ts
-import { createHash as createHash3 } from "node:crypto";
-import bs585 from "bs58";
-import nacl from "tweetnacl";
-var WALLET_AUTH_WALLET_HEADER = "x-subly-wallet";
-var WALLET_AUTH_SIGNED_AT_HEADER = "x-subly-signed-at";
-var WALLET_AUTH_SIGNATURE_HEADER = "x-subly-signature";
-function sha256Hex(data) {
-  return createHash3("sha256").update(data, "utf8").digest("hex");
-}
-function walletAuthMessage(params) {
-  return new TextEncoder().encode(
-    `subly-api:${params.method.toUpperCase()}:${params.path}:${sha256Hex(
-      params.rawBody
-    )}:${params.signedAtMs}`
-  );
-}
-
-// ../../src/client/wallet-auth-headers.ts
-async function walletAuthHeaders(params) {
-  const signedAtMs = String(Date.now());
-  const message = walletAuthMessage({
-    method: params.method,
-    path: new URL(params.url).pathname,
-    rawBody: params.body ?? "",
-    signedAtMs
-  });
+// src/client/web3-wallet-adapter.ts
+import { Keypair } from "@solana/web3.js";
+function createX402WalletAdapter(secretKey) {
+  if (secretKey.length !== 64) {
+    throw new Error("agent secret key must be 64 bytes");
+  }
+  const keypair = Keypair.fromSecretKey(secretKey);
   return {
-    [WALLET_AUTH_WALLET_HEADER]: params.signer.walletAddress,
-    [WALLET_AUTH_SIGNED_AT_HEADER]: signedAtMs,
-    [WALLET_AUTH_SIGNATURE_HEADER]: await params.signer.signApiMessage(message)
+    address: keypair.publicKey.toBase58(),
+    signTransaction: async (tx) => {
+      tx.sign([keypair]);
+      return tx;
+    }
   };
 }
 
-// ../../src/client/onboarding.ts
-var SELF_SERVE_POLICY_ID = "self-serve";
-var OnboardingError = class extends Error {
-  constructor(step, message, detail = null) {
-    super(message);
-    this.step = step;
-    this.detail = detail;
-    this.name = "OnboardingError";
-  }
-  step;
-  detail;
-};
-async function ensureWalletOnboarded(params) {
-  const fetchImpl = params.fetchImpl ?? fetch;
-  const baseUrl = params.facilitatorBaseUrl.replace(/\/$/, "");
-  const post = async (step, path, body) => {
-    const url = `${baseUrl}${path}`;
-    const serialized = JSON.stringify(body);
-    const response = await fetchImpl(url, {
-      method: "POST",
-      headers: {
-        ...await walletAuthHeaders({
-          signer: params.signer,
-          method: "POST",
-          url,
-          body: serialized
-        }),
-        "content-type": "application/json"
-      },
-      body: serialized
-    });
-    if (response.status !== 200) {
-      let detail = null;
-      try {
-        detail = await response.json();
-      } catch {
-        detail = null;
-      }
-      throw new OnboardingError(
-        step,
-        `wallet onboarding ${step} failed with ${response.status}`,
-        detail
-      );
-    }
-  };
-  const wallet = params.signer.walletAddress;
-  await post("register", "/v1/wallets/agent", {
-    wallet,
-    signingPolicyId: SELF_SERVE_POLICY_ID,
-    signingMode: "non_interactive",
-    signerValidationMode: params.signer.validationMode,
-    signerProvider: "local-keypair",
-    activateForPayments: true
+// src/client/standard-x402-factory.ts
+function createStandardX402Payer(config) {
+  const realizer = new RelayerYieldRealizer({
+    facilitatorBaseUrl: config.facilitatorBaseUrl,
+    signer: config.signer,
+    rpc: config.rpc
+  });
+  const client = createX402Client({
+    wallet: createX402WalletAdapter(config.agentSecretKey),
+    network: config.network ?? "solana",
+    rpcUrl: config.rpcUrl
+  });
+  const x402Fetch = (url, init) => client.fetch(url, init);
+  return new StandardX402Payer({
+    realizer,
+    x402Fetch,
+    defaultMaxAmountRawUsdc: config.defaultMaxAmountRawUsdc
   });
-  await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain" });
 }
 
-// ../../src/solana/keys.ts
+// src/client/paid-fetch.ts
+function formatRawUsdcAmount(raw) {
+  const value = BigInt(raw);
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const whole = abs / 1000000n;
+  const frac = (abs % 1000000n).toString().padStart(6, "0");
+  return `${negative ? "-" : ""}${whole}.${frac}`;
+}
+
+// src/solana/keys.ts
 import { readFileSync } from "node:fs";
 import bs586 from "bs58";
 import {
@@ -1466,314 +1556,76 @@ async function loadKeyPairSigner(params) {
   }
   throw new Error(`${label} keypair is not configured`);
 }
-
-// ../../src/solana/rpc.ts
-import { createSolanaRpc } from "@solana/kit";
-function createRpcFromEnv(env = process.env) {
-  const url = env.SOLANA_RPC_URL;
-  if (url === void 0 || url.length === 0) {
-    throw new Error("SOLANA_RPC_URL must be configured");
-  }
-  return createSolanaRpc(url);
-}
-
-// ../../src/x402/client.ts
-var X402ClientError = class extends Error {
-  reason;
-  detail;
-  constructor(reason, message, detail) {
-    super(message);
-    this.name = "X402ClientError";
-    this.reason = reason;
-    this.detail = detail;
-  }
-};
-var SublyX402Client = class {
-  config;
-  signer;
-  lookupTablesFor;
-  fetchImpl;
-  constructor(config) {
-    this.config = {
-      facilitatorBaseUrl: config.facilitatorBaseUrl.replace(/\/$/, ""),
-      network: config.network ?? SOLANA_MAINNET_NETWORK
-    };
-    this.signer = config.signer;
-    this.lookupTablesFor = config.lookupTablesFor ?? null;
-    this.fetchImpl = config.fetchImpl ?? fetch;
-  }
-  /**
-   * Builds the PAYMENT-SIGNATURE header for a 402 challenge. The request
-   * method, URL, and body must be exactly the request being retried; they are
-   * bound into the payment and verified again by the seller and facilitator.
-   */
-  async buildPaymentSignatureHeader(input) {
-    const requirement = this.selectRequirement(input.paymentRequiredHeader);
-    if (requirement.resource !== input.url) {
-      throw new X402ClientError(
-        "resource_mismatch",
-        "PAYMENT-REQUIRED resource does not match the request URL"
-      );
-    }
-    const requestBodyHash = requestBodyHashFor(input.body);
-    const prepared = await this.preparePayment({
-      requirement,
-      httpMethod: input.httpMethod.toUpperCase(),
-      requestBodyHash
-    });
-    const lookupTables = this.lookupTablesFor === null ? void 0 : await this.lookupTablesFor(prepared.intentJson.serializedTransaction);
-    const signed = await this.signer.signPayment({
-      intent: prepared.intentJson.signingIntent,
-      serializedTransaction: prepared.intentJson.serializedTransaction,
-      lookupTables
-    });
-    const payload = {
-      x402Version: X402_VERSION,
-      scheme: requirement.scheme,
-      network: requirement.network,
-      payload: {
-        paymentId: prepared.paymentId,
-        requestBindingHash: prepared.requestBindingHash,
-        preparedMessageHash: prepared.preparedMessageHash,
-        serializedTransaction: signed.serializedTransaction,
-        agentSignature: signed.agentSignature,
-        temporarySettlementSignature: prepared.temporarySettlementSignature
-      }
-    };
-    return {
-      headerValue: encodeX402Header(payload),
-      paymentId: prepared.paymentId
-    };
-  }
-  /**
-   * Convenience wrapper: performs the request, and on a 402 with a Subly
-   * requirement pays from vault yield and retries once.
-   */
-  async fetchWithPayment(url, init) {
-    const first = await this.fetchImpl(url, init);
-    if (first.status !== 402) {
-      return first;
-    }
-    const challenge = first.headers.get(PAYMENT_REQUIRED_HEADER);
-    if (challenge === null) {
-      return first;
+function loadSecretKeyBytes(params) {
+  const { base58Secret, jsonFilePath, label } = params;
+  if (base58Secret !== void 0 && base58Secret.length > 0) {
+    const bytes = bs586.decode(base58Secret);
+    if (bytes.length !== 64) {
+      throw new Error(`${label} base58 secret must decode to 64 bytes`);
     }
-    const { headerValue } = await this.buildPaymentSignatureHeader({
-      paymentRequiredHeader: challenge,
-      httpMethod: init?.method ?? "GET",
-      url,
-      body: init?.body ?? null
-    });
-    return this.fetchImpl(url, {
-      ...init,
-      headers: {
-        ...init?.headers,
-        [PAYMENT_SIGNATURE_HEADER]: headerValue
-      }
-    });
+    return bytes;
   }
-  selectRequirement(paymentRequiredHeader) {
-    let sublyRequirements;
-    try {
-      sublyRequirements = decodePaymentRequiredHeader(
-        paymentRequiredHeader
-      ).sublyRequirements;
-    } catch (error) {
-      throw new X402ClientError(
-        error instanceof X402HeaderError ? error.reason : "invalid_challenge",
-        "Cannot decode the PAYMENT-REQUIRED header"
-      );
-    }
-    const selected = sublyRequirements.find(
-      (candidate) => candidate.network === this.config.network && candidate.extra.vault === SUBLY_VAULT.address && candidate.extra.shareMint === SUBLY_VAULT.shareMint && candidate.asset === SUBLY_VAULT.usdcMint
-    ) ?? null;
-    if (selected === null) {
-      throw new X402ClientError(
-        "no_supported_requirement",
-        "The 402 challenge contains no supported subly-yield-exact requirement"
-      );
-    }
-    return selected;
-  }
-  async preparePayment(input) {
-    const { requirement } = input;
-    const wallet = this.signer.walletAddress;
-    const prepareUrl = `${this.config.facilitatorBaseUrl}/v1/payments/prepare`;
-    const prepareBody = JSON.stringify({
-      wallet,
-      scheme: requirement.scheme,
-      network: requirement.network,
-      vault: requirement.extra.vault,
-      shareMint: requirement.extra.shareMint,
-      asset: requirement.asset,
-      seller: requirement.extra.seller,
-      sellerRequestId: requirement.extra.sellerRequestId,
-      httpMethod: input.httpMethod,
-      canonicalResourceUrl: requirement.resource,
-      requestBodyHash: input.requestBodyHash,
-      amountRawUsdc: requirement.amountRawUsdc,
-      payTo: requirement.payTo,
-      sellerUsdcAta: requirement.extra.sellerUsdcAta,
-      dustRecipientUsdcAta: deriveAssociatedTokenAddress({
-        owner: wallet,
-        mint: SUBLY_VAULT.usdcMint
-      })
-    });
-    const response = await this.fetchImpl(prepareUrl, {
-      method: "POST",
-      headers: {
-        ...await walletAuthHeaders({
-          signer: this.signer,
-          method: "POST",
-          url: prepareUrl,
-          body: prepareBody
-        }),
-        "content-type": "application/json"
-      },
-      body: prepareBody
-    });
-    const body = await response.json();
-    if (response.status !== 200) {
-      const error = body.error;
-      throw new X402ClientError(
-        typeof error?.code === "string" ? error.code : "prepare_failed",
-        "Payment preparation failed at the facilitator",
-        body
-      );
-    }
-    const prepared = body;
-    if (typeof prepared.paymentId !== "string" || typeof prepared.preparedMessageHash !== "string" || typeof prepared.intentJson?.serializedTransaction !== "string" || typeof prepared.intentJson?.signingIntent !== "object") {
-      throw new X402ClientError(
-        "invalid_prepare_response",
-        "Facilitator prepare response is missing required fields"
-      );
+  if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
+    const raw = JSON.parse(readFileSync(jsonFilePath, "utf8"));
+    if (!Array.isArray(raw) || raw.length !== 64) {
+      throw new Error(`${label} keypair file must be a 64-byte JSON array`);
     }
-    return prepared;
+    return Uint8Array.from(raw);
   }
-};
-
-// ../../demo/shared.ts
-function fail(message) {
-  console.error(message);
-  process.exit(1);
+  throw new Error(`${label} keypair is not configured`);
 }
-function requireEnv(name) {
-  const value = process.env[name];
-  if (value === void 0 || value.length === 0) {
-    fail(`Missing required environment variable: ${name}`);
-  }
-  return value;
+
+// src/solana/rpc.ts
+import { createSolanaRpc } from "@solana/kit";
+function createRpc(url) {
+  return createSolanaRpc(url);
 }
 
-// ../../demo/mcp-server.ts
+// demo/mcp-server.ts
 var TOOL_NAME = "fetch_with_subly_payment";
 var DEFAULT_MAX_AMOUNT_RAW_USDC = 10000n;
-requireEnv("SOLANA_RPC_URL");
-var facilitatorBaseUrl = process.env.SUBLY_FACILITATOR_URL ?? "http://localhost:3000";
+var facilitatorBaseUrl = process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
+var rpcUrl = process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com";
 var defaultMaxAmountRawUsdc = process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC === void 0 ? DEFAULT_MAX_AMOUNT_RAW_USDC : BigInt(process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC);
 var keyPairSigner = await loadKeyPairSigner({
   base58Secret: process.env.SUBLY_DEMO_AGENT_KEYPAIR,
   jsonFilePath: process.env.SUBLY_DEMO_AGENT_KEYPAIR_PATH,
   label: "SUBLY_DEMO_AGENT_KEYPAIR"
 });
+var agentSecretKey = loadSecretKeyBytes({
+  base58Secret: process.env.SUBLY_DEMO_AGENT_KEYPAIR,
+  jsonFilePath: process.env.SUBLY_DEMO_AGENT_KEYPAIR_PATH,
+  label: "SUBLY_DEMO_AGENT_KEYPAIR"
+});
 var signer = new LocalKeypairAgentWalletSigner(keyPairSigner);
-var rpc = createRpcFromEnv();
-async function fetchBudget() {
-  try {
-    const url = `${facilitatorBaseUrl}/v1/wallets/${signer.walletAddress}/budget`;
-    const response = await fetch(url, {
-      headers: await walletAuthHeaders({ signer, method: "GET", url })
-    });
-    if (response.status !== 200) {
-      return null;
-    }
-    const body = await response.json();
-    if (body.budget === void 0) {
-      return null;
-    }
-    return {
-      positionValueUsdc: formatRawUsdcAmount(body.budget.positionValueRawUsdc),
-      spendableYieldUsdc: formatRawUsdcAmount(
-        body.budget.spendableYieldRawUsdc
-      )
-    };
-  } catch {
-    return null;
-  }
-}
-async function paymentStatusFor(paymentId) {
-  try {
-    const url = `${facilitatorBaseUrl}/v1/payments/${paymentId}`;
-    const response = await fetch(url, {
-      headers: await walletAuthHeaders({ signer, method: "GET", url })
-    });
-    if (response.status !== 200) {
-      return "indeterminate";
-    }
-    const body = await response.json();
-    if (body.status === "settled") {
-      return "settled";
-    }
-    if (body.status === "expired" || body.status === "failed" || body.status === "failed_not_submitted") {
-      return "not_settled";
-    }
-    return "indeterminate";
-  } catch {
-    return "indeterminate";
-  }
-}
-function fileStateStore(path) {
-  return {
-    load() {
-      try {
-        const parsed = JSON.parse(readFileSync2(path, "utf8"));
-        return Array.isArray(parsed) ? parsed : [];
-      } catch {
-        return [];
-      }
-    },
-    save(records) {
-      try {
-        writeFileSync(path, JSON.stringify(records));
-      } catch (error) {
-        console.error(
-          `[subly-mcp] failed to persist pending payments: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
-  };
-}
-var pendingStatePath = process.env.SUBLY_MCP_STATE_PATH ?? "demo/env/mcp-pending-payments.json";
-var paidFetchService = new PaidFetchService({
-  signatureBuilder: new SublyX402Client({
-    facilitatorBaseUrl,
-    signer,
-    lookupTablesFor: (serializedTransaction) => fetchLookupTablesForTransaction(rpc, serializedTransaction)
-  }),
-  defaultMaxAmountRawUsdc,
-  fetchBudget,
-  paymentStatusFor,
-  stateStore: fileStateStore(pendingStatePath)
+var rpc = createRpc(rpcUrl);
+var payer = createStandardX402Payer({
+  facilitatorBaseUrl,
+  signer,
+  agentSecretKey,
+  rpc,
+  rpcUrl,
+  defaultMaxAmountRawUsdc
 });
-var SERVER_INSTRUCTIONS = `Subly lets an agent pay for HTTP 402 (subly-yield-exact) resources from its wallet's Kamino vault YIELD \u2014 the deposited principal is never spent.
+var SERVER_INSTRUCTIONS = `Subly lets an agent pay for ANY standard x402 (HTTP 402) paid API from its wallet's Kamino vault YIELD \u2014 the deposited principal is never spent, and the seller needs no Subly integration.
 
 Before payments can succeed the operator of this server must have, once:
 1. A Solana keypair for the agent wallet. Subly does NOT create wallets; make one with \`solana-keygen new -o agent.json\` (or export a keypair from an existing wallet) and point SUBLY_DEMO_AGENT_KEYPAIR_PATH at it. The private key never leaves that file; this server only signs locally with it.
-2. Funded that wallet with USDC on Solana mainnet (no SOL needed \u2014 fees are sponsored) and deposited into the vault (see the project's deposit command). The vault minimum deposit is 1 USDC.
-3. Waited for yield to accrue; a payment needs the price plus a fixed overhead (~0.0024 USDC) of spendable yield.
+2. Funded that wallet with USDC on Solana mainnet (no SOL needed \u2014 realize fees are sponsored) and deposited into the vault (see the project's deposit command). The vault minimum deposit is 1 USDC.
+3. Waited for yield to accrue; a payment needs the seller's price of spendable yield.
 
-Then use fetch_with_subly_payment(url) to GET a paid resource: it pays the 402 from yield and returns the body plus an on-chain receipt. If it returns insufficient_yield, that is expected \u2014 wait for yield, do not loop. If it returns delivery_failed_payment_pending, call the SAME url again (it retries the same payment, never double-pays).`;
+Then use fetch_with_subly_payment(url) to GET a paid resource from any x402 seller (e.g. Nansen): it realizes just enough yield to the agent's USDC ATA and pays the seller's standard x402 challenge, returning the body plus the payment details. If it returns insufficient_yield, that is expected \u2014 wait for yield, do not loop.`;
 var server = new Server(
-  { name: "subly-payments", version: "0.1.0" },
+  { name: "subly-payments", version: "0.2.0" },
   { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
 );
 server.setRequestHandler(ListToolsRequestSchema, () => ({
   tools: [
     {
       name: TOOL_NAME,
-      description: `GET a URL, automatically paying a Subly x402 (subly-yield-exact) 402 challenge from the agent wallet's Kamino vault yield. Returns the response body; when a payment was made, also returns the settlement receipt (amount, payee, paymentId, Solscan link). Challenges above maxAmountRawUsdc (default ${defaultMaxAmountRawUsdc} raw = ${formatRawUsdcAmount(
+      description: `GET a URL, automatically paying a standard x402 (HTTP 402) challenge from any x402-compatible seller (Nansen, etc.) out of the agent wallet's Kamino vault yield. Subly realizes just enough yield to the agent's USDC ATA (sponsored) and pays the seller's Solana USDC \`exact\` challenge; the seller needs no Subly integration. Returns the response body and, when a payment was made, the payment details (amount, payee, realize tx). Challenges above maxAmountRawUsdc (default ${defaultMaxAmountRawUsdc} raw = ${formatRawUsdcAmount(
         defaultMaxAmountRawUsdc
-      )} USDC) are refused without paying. If delivery fails after the payment was signed, the signature is kept and calling again with the same URL retries the same payment instead of paying twice. Payments are refused by the facilitator when the spendable yield budget cannot cover them \u2014 the principal is never spent. Use only for URLs you intend to purchase access to.`,
+      )} USDC) are refused without paying. Payments are refused when the spendable yield budget cannot cover them \u2014 the principal is never spent. Use only for URLs you intend to purchase access to.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -1784,10 +1636,6 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
           maxAmountRawUsdc: {
             type: "string",
             description: 'Refuse (without paying) any challenge above this amount in raw USDC units (6 decimals, e.g. "10000" = 0.01 USDC). Defaults to the server-side cap.'
-          },
-          forceNewPayment: {
-            type: "boolean",
-            description: "Pay again even though a previous payment for this URL settled or has an unknown outcome. Only set deliberately: combined with payment_already_settled this means paying twice for the same resource. Ignored while the previous payment is still retryable (the same signature is retried instead)."
           }
         },
         required: ["url"]
@@ -1840,16 +1688,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
   }
   try {
-    const result = await paidFetchService.paidFetch({
+    const result = await payer.pay({
       url,
-      ...maxAmountRawUsdc === void 0 ? {} : { maxAmountRawUsdc },
-      forceNewPayment: args.forceNewPayment === true
+      ...maxAmountRawUsdc === void 0 ? {} : { maxAmountRawUsdc }
     });
     return {
       content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
     };
   } catch (error) {
-    if (error instanceof PaidFetchError) {
+    if (error instanceof StandardX402PayError) {
       return {
         content: [
           {
@@ -1870,26 +1717,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         isError: true
       };
     }
-    if (error instanceof X402ClientError) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                paid: false,
-                refused: true,
-                reason: error.reason,
-                detail: error.detail ?? null
-              },
-              null,
-              2
-            )
-          }
-        ],
-        isError: true
-      };
-    }
     return {
       content: [
         {
@@ -1903,7 +1730,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 try {
   await ensureWalletOnboarded({ facilitatorBaseUrl, signer });
-  console.error("[subly-mcp] wallet registered and synced at the facilitator");
+  console.error("[subly-mcp] wallet registered and synced at the relayer");
 } catch (error) {
   console.error(
     `[subly-mcp] wallet onboarding failed (will still serve tools): ${error instanceof Error ? error.message : String(error)}`
@@ -1912,5 +1739,5 @@ try {
 var transport = new StdioServerTransport();
 await server.connect(transport);
 console.error(
-  `[subly-mcp] ready: agent wallet ${signer.walletAddress}, facilitator ${facilitatorBaseUrl}, default cap ${formatRawUsdcAmount(defaultMaxAmountRawUsdc)} USDC`
+  `[subly-mcp] ready: agent wallet ${signer.walletAddress}, relayer ${facilitatorBaseUrl}, default cap ${formatRawUsdcAmount(defaultMaxAmountRawUsdc)} USDC`
 );