@oracle-agent/oracle 0.1.0

package/src/data/providers/jupiter.mjs

@@ -0,0 +1,182 @@
+// Jupiter Swap API lane for Solana. Prepare-only: returns a serialized
+// transaction for the user's Solana wallet to sign. No local signer, no broadcast.
+
+import { httpJson } from "../http.mjs";
+import { solanaPubkey } from "./solana-rpc.mjs";
+
+export const JUPITER_SWAP_API = "https://lite-api.jup.ag/swap/v1";
+export const SOL_MINT = "So11111111111111111111111111111111111111112";
+export const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export const JUPITER_MAX_SLIPPAGE_BPS = 100;
+const DEFAULT_QUOTE_TTL_MS = 20_000;
+
+function baseUrl(opts = {}) {
+  return String(opts.baseUrl || process.env.JUPITER_SWAP_API_URL || JUPITER_SWAP_API).replace(/\/$/, "");
+}
+
+function amountString(value, label = "amount") {
+  try {
+    const n = BigInt(String(value));
+    if (n <= 0n) throw new Error("nonpositive");
+    return n.toString();
+  } catch {
+    throw new Error(`jupiter: ${label} must be a positive integer string`);
+  }
+}
+
+function slippageBps(value) {
+  const n = value == null ? 50 : Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new Error("jupiter: slippageBps must be a non-negative integer");
+  if (n > JUPITER_MAX_SLIPPAGE_BPS) throw new Error("jupiter: slippage exceeds hard 100 bps cap");
+  return n;
+}
+
+function boolDefault(value, fallback) {
+  return value == null ? fallback : Boolean(value);
+}
+
+function base64Tx(value) {
+  const text = String(value || "").trim();
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(text) || text.length % 4 !== 0) throw new Error("jupiter: swapTransaction must be base64");
+  return text;
+}
+
+function solanaGuard(quote = {}, { quotedAtMs = Date.now(), ttlMs = DEFAULT_QUOTE_TTL_MS } = {}) {
+  const inputMint = solanaPubkey(quote.inputMint, "inputMint");
+  const outputMint = solanaPubkey(quote.outputMint, "outputMint");
+  const inAmount = amountString(quote.inAmount, "inAmount");
+  const outAmount = amountString(quote.outAmount, "outAmount");
+  const otherAmountThreshold = amountString(quote.otherAmountThreshold ?? quote.outAmount, "otherAmountThreshold");
+  const bps = slippageBps(quote.slippageBps ?? 50);
+  return {
+    mode: "solana-jupiter-quote",
+    provider: "jupiter",
+    venue: "jupiter-swap-v1",
+    inputMint,
+    outputMint,
+    inAmount,
+    outAmount,
+    otherAmountThreshold,
+    slippageBps: bps,
+    contextSlot: quote.contextSlot ?? null,
+    quotedAtMs,
+    expiresAtMs: quotedAtMs + Math.min(Math.max(Number(ttlMs) || DEFAULT_QUOTE_TTL_MS, 1_000), 30_000),
+  };
+}
+
+export async function jupiterHealth(opts = {}) {
+  try {
+    const q = await jupiterQuote({ inputMint: SOL_MINT, outputMint: USDC_MINT, amount: "1000000", slippageBps: 50 }, opts);
+    return { ok: true, provider: "jupiter", outAmount: q.quote.outAmount, exec: false };
+  } catch (error) {
+    return { ok: false, provider: "jupiter", error: String(error?.message || error), exec: false };
+  }
+}
+
+export async function jupiterQuote(args = {}, opts = {}) {
+  const inputMint = solanaPubkey(args.inputMint || args.fromMint || SOL_MINT, "inputMint");
+  const outputMint = solanaPubkey(args.outputMint || args.toMint || USDC_MINT, "outputMint");
+  const amount = amountString(args.amount || args.inAmount, "amount");
+  const bps = slippageBps(args.slippageBps ?? args.maxSlippageBps ?? 50);
+  const url = new URL(`${baseUrl(opts)}/quote`);
+  url.searchParams.set("inputMint", inputMint);
+  url.searchParams.set("outputMint", outputMint);
+  url.searchParams.set("amount", amount);
+  url.searchParams.set("slippageBps", String(bps));
+  url.searchParams.set("swapMode", args.swapMode || "ExactIn");
+  if (args.onlyDirectRoutes != null) url.searchParams.set("onlyDirectRoutes", String(Boolean(args.onlyDirectRoutes)));
+  if (args.platformFeeBps != null) url.searchParams.set("platformFeeBps", String(args.platformFeeBps));
+  const quote = await httpJson(url.toString(), {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  const guard = solanaGuard({ ...quote, slippageBps: bps }, opts);
+  return {
+    provider: "jupiter",
+    chain: "solana-mainnet-beta",
+    quoteReady: true,
+    executionReady: false,
+    inputMint,
+    outputMint,
+    amount,
+    quote,
+    solanaGuard: guard,
+  };
+}
+
+function compactBody(body) {
+  return Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined));
+}
+
+export async function jupiterPrepareSwap(args = {}, opts = {}) {
+  const userPublicKey = solanaPubkey(args.userPublicKey || args.owner || args.wallet, "userPublicKey");
+  const quoteEnvelope = args.quoteResponse
+    ? { quote: args.quoteResponse, solanaGuard: solanaGuard(args.quoteResponse, opts) }
+    : await jupiterQuote(args, opts);
+  const quoteResponse = quoteEnvelope.quote;
+  const guard = quoteEnvelope.solanaGuard || solanaGuard(quoteResponse, opts);
+
+  // dynamicSlippage lets Jupiter widen the on-chain slippage floor at build
+  // time, which silently voids the hard bps ceiling the quote path enforced —
+  // the returned guard would still advertise the capped number. Refuse it
+  // rather than return a transaction whose real tolerance exceeds the cap.
+  if (boolDefault(args.dynamicSlippage, false) === true) {
+    throw new Error(
+      "jupiter: dynamicSlippage would override the enforced slippage ceiling — pass an explicit slippageBps instead"
+    );
+  }
+
+  const response = await httpJson(`${baseUrl(opts)}/swap`, {
+    method: "POST",
+    body: compactBody({
+      quoteResponse,
+      userPublicKey,
+      wrapAndUnwrapSol: boolDefault(args.wrapAndUnwrapSol, true),
+      dynamicComputeUnitLimit: boolDefault(args.dynamicComputeUnitLimit, true),
+      dynamicSlippage: false,
+      prioritizationFeeLamports: args.prioritizationFeeLamports,
+    }),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+  const swapTransaction = base64Tx(response?.swapTransaction);
+
+  // Bind the returned transaction to the quote it claims to implement. A
+  // compromised or impersonated endpoint can return any bytes while Oracle
+  // stamps the optimistic quote on top; the user signs the bytes, not the
+  // guard. Jupiter echoes the quote it built from — require it to match.
+  const echoed = response?.quoteResponse ?? response?.quote ?? null;
+  if (echoed) {
+    for (const field of ["inAmount", "outAmount", "otherAmountThreshold", "inputMint", "outputMint"]) {
+      const want = quoteResponse?.[field];
+      const got = echoed?.[field];
+      if (want != null && got != null && String(want) !== String(got)) {
+        throw new Error(
+          `jupiter: swap response ${field} (${got}) does not match the quoted ${field} (${want}) — refusing to prepare`
+        );
+      }
+    }
+  }
+
+  return {
+    provider: "jupiter",
+    chain: "solana-mainnet-beta",
+    prepareReady: true,
+    executionReady: false,
+    signingReady: false,
+    broadcastReady: false,
+    requiresUserSignature: true,
+    // The prepared bytes are NOT verified against the quote beyond the fields
+    // Jupiter echoes. Simulate before signing.
+    verifiedAgainstQuote: Boolean(echoed),
+    userPublicKey,
+    quote: quoteResponse,
+    solanaGuard: guard,
+    swapTransaction,
+    swapTransactionEncoding: "base64",
+    lastValidBlockHeight: response?.lastValidBlockHeight ?? null,
+    prioritizationFeeLamports: response?.prioritizationFeeLamports ?? null,
+    computeUnitLimit: response?.computeUnitLimit ?? null,
+    raw: response,
+  };
+}

package/src/data/providers/lifi.mjs

@@ -0,0 +1,150 @@
+// LI.FI public quote API — no API key required for basic quotes.
+
+import { httpJson } from "../http.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
+import { QUOTE_PLACEHOLDER_ADDRESS, quoteAddress } from "../quote-placeholder.mjs";
+
+export const LIFI_API = "https://li.quest/v1";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.LIFI_API_URL || LIFI_API).replace(/\/$/, "");
+}
+
+const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+const ZERO = "0x0000000000000000000000000000000000000000";
+
+function isNativeToken(value) {
+  const token = String(value || NATIVE).toLowerCase();
+  return token === NATIVE.toLowerCase() || token === ZERO;
+}
+
+function address(value, label) {
+  const text = String(value || "").trim();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(text)) throw new Error(`lifi: ${label} must be a 20-byte address`);
+  return text.toLowerCase();
+}
+
+export async function lifiHealth(opts = {}) {
+  // cheap chains list
+  const chains = await httpJson(`${base(opts)}/chains`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  const n = Array.isArray(chains) ? chains.length : chains?.chains?.length || 0;
+  return { ok: n > 0, chainCount: n };
+}
+
+/**
+ * @param {object} q
+ * @param {number|string} q.fromChain
+ * @param {number|string} q.toChain
+ * @param {string} q.fromToken
+ * @param {string} q.toToken
+ * @param {string} q.fromAmount  wei/base units
+ * @param {string} [q.fromAddress]
+ */
+export async function lifiQuote(q = {}, opts = {}) {
+  const {
+    fromChain,
+    toChain = fromChain,
+    fromToken = NATIVE,
+    toToken,
+    fromAmount,
+    fromAddress = QUOTE_PLACEHOLDER_ADDRESS,
+  } = q;
+  if (fromChain == null || !toToken || !fromAmount) {
+    throw new Error("lifiQuote requires fromChain, toToken, fromAmount");
+  }
+  const params = new URLSearchParams({
+    fromChain: String(fromChain),
+    toChain: String(toChain),
+    fromToken,
+    toToken,
+    fromAmount: String(fromAmount),
+    fromAddress,
+  });
+  const selected = resolveAutoSlippage({
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    crossChain: Number(toChain) !== Number(fromChain),
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  if (!selected.executable) {
+    throw new Error(`lifi: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
+  }
+  // LI.FI expects a decimal fraction: 0.005 = 50 bps.
+  params.set("slippage", String(selected.selectedBps / 10_000));
+  const result = await httpJson(`${base(opts)}/quote?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  const amountOut = result?.estimate?.toAmount || result?.toAmount;
+  if (!amountOut) return { ...result, autoSlippagePolicy: selected };
+  const venue = result?.transactionRequest?.to || result?.estimate?.approvalAddress || "lifi";
+  const guarded = attachAutoSlippage(result, {
+    chainId: Number(fromChain),
+    venue,
+    amountOut,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    crossChain: Number(toChain) !== Number(fromChain),
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  const providerMin = result?.estimate?.toAmountMin || result?.toAmountMin;
+  if (providerMin != null && BigInt(providerMin) < BigInt(guarded.amountOutMinimum)) {
+    throw new Error("lifi: provider transaction is under-protected versus bounded auto-slippage floor");
+  }
+  return guarded;
+}
+
+export async function lifiPrepare(q = {}, opts = {}) {
+  const quote = await lifiQuote(q, opts);
+  const tx = quote?.transactionRequest;
+  if (!tx?.to || !tx?.data) throw new Error("lifi: quote did not return an executable transactionRequest");
+  const chainId = Number(q.fromChain);
+  if (tx.chainId != null && Number(tx.chainId) !== chainId) throw new Error("lifi: transaction chain mismatch");
+  if (q.fromAddress && tx.from && String(tx.from).toLowerCase() !== String(q.fromAddress).toLowerCase()) {
+    throw new Error("lifi: transaction sender mismatch");
+  }
+  let requiresApproval = null;
+  if (!isNativeToken(q.fromToken)) {
+    const spender = quote?.estimate?.approvalAddress || quote?.approvalAddress;
+    if (!spender) throw new Error("lifi: ERC20 route missing approvalAddress");
+    requiresApproval = {
+      token: address(q.fromToken, "approval token"),
+      spender: address(spender, "approval spender"),
+      amount: String(q.fromAmount),
+    };
+  }
+  return {
+    provider: "lifi",
+    calldataReady: true,
+    // NOT executable authority. The bytes are assembled but nothing is signed:
+    // the user's wallet is still the only thing that can authorize this. The
+    // previous `executionReady: true` read as "cleared to execute" and trained
+    // agents to treat a quote as permission.
+    requiresUserSignature: true,
+    signingReady: false,
+    broadcastReady: false,
+    chainId,
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval,
+    transaction: {
+      chainId,
+      from: tx.from || q.fromAddress,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value ?? "0x0",
+      ...(tx.gasLimit != null ? { gasLimit: tx.gasLimit } : {}),
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
+    },
+  };
+}
+
+export async function lifiChains(opts = {}) {
+  return httpJson(`${base(opts)}/chains`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+}

package/src/data/providers/magiceden-sol.mjs

@@ -0,0 +1,355 @@
+// Magic Eden Solana NFT lane. Read + prepare only.
+//
+// Reads (collection stats, listings, activities) are keyless on the public
+// mainnet API. The instruction builders (buy_now, list, mint) require a Magic
+// Eden API key and return an UNSIGNED transaction the user's wallet signs.
+// Nothing here signs or broadcasts.
+
+import { httpJson } from "../http.mjs";
+import { solanaPubkey } from "./solana-rpc.mjs";
+import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
+
+export const MAGICEDEN_SOL_API = "https://api-mainnet.magiceden.dev/v2";
+export const LAMPORTS_PER_SOL = 1_000_000_000;
+
+function endpoint(opts = {}) {
+  return resolveProviderEndpoint({
+    provider: "magiceden",
+    defaultUrl: MAGICEDEN_SOL_API,
+    hosts: ["api-mainnet.magiceden.dev", "api-devnet.magiceden.dev"],
+    url: opts.baseUrl || process.env.MAGICEDEN_API_URL,
+  });
+}
+
+function base(opts = {}) {
+  return endpoint(opts).baseUrl;
+}
+
+function apiKey(opts = {}) {
+  return opts.apiKey || process.env.MAGICEDEN_API_KEY || "";
+}
+
+function headers(opts = {}) {
+  // Bearer token goes only to a pinned Magic Eden host.
+  const key = apiKey(opts);
+  return credentialedHeaders(
+    { accept: "application/json" },
+    { Authorization: key ? `Bearer ${key}` : "" },
+    endpoint(opts).trusted
+  );
+}
+
+function symbolArg(value) {
+  const symbol = String(value || "").trim();
+  if (!/^[a-z0-9_]{1,64}$/i.test(symbol)) throw new Error("magiceden: symbol must be a collection slug");
+  return symbol;
+}
+
+/**
+ * Number() accepts "1e2", "0x10", " 12 " and Infinity. A price that parses
+ * differently from how it reads is a spend-control bug: the UI shows one value
+ * and the wallet is asked for another. Require a plain decimal.
+ */
+function positiveNumber(value, label) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0) throw new Error(`magiceden: ${label} must be a positive number`);
+    return value;
+  }
+  const text = String(value ?? "").trim();
+  if (!/^\d+(\.\d+)?$/.test(text)) {
+    throw new Error(`magiceden: ${label} must be a plain decimal number (no hex, exponent, or sign)`);
+  }
+  const n = Number(text);
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`magiceden: ${label} must be a positive number`);
+  return n;
+}
+
+/** Pull the launchpad's quoted mint price (SOL) out of an API response. */
+function mintPriceSol(raw) {
+  const candidates = [
+    raw?.price,
+    raw?.mintPrice,
+    raw?.priceSol,
+    raw?.v0?.price,
+    raw?.launchStageInfo?.price,
+    raw?.stage?.price,
+  ];
+  for (const c of candidates) {
+    if (c == null) continue;
+    const n = Number(c);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  // A free mint legitimately quotes zero.
+  if (raw?.isFree === true) return 0;
+  return null;
+}
+
+function lamports(sol) {
+  return Math.round(positiveNumber(sol, "priceSol") * LAMPORTS_PER_SOL);
+}
+
+export async function magicEdenSolHealth(opts = {}) {
+  try {
+    const stats = await magicEdenSolStats({ symbol: "mad_lads" }, opts);
+    return {
+      ok: true,
+      provider: "magiceden-sol",
+      keyed: Boolean(apiKey(opts)),
+      readTier: "keyless",
+      prepareTier: apiKey(opts) ? "keyed" : "requires MAGICEDEN_API_KEY",
+      floorPriceSol: stats.floorPriceSol,
+      exec: false,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      provider: "magiceden-sol",
+      keyed: Boolean(apiKey(opts)),
+      error: String(error?.message || error).slice(0, 160),
+      exec: false,
+    };
+  }
+}
+
+export async function magicEdenSolStats(args = {}, opts = {}) {
+  const symbol = symbolArg(args.symbol || args.collection);
+  const raw = await httpJson(`${base(opts)}/collections/${encodeURIComponent(symbol)}/stats`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  const floorLamports = Number(raw?.floorPrice ?? 0);
+  return {
+    provider: "magiceden-sol",
+    chain: "solana-mainnet-beta",
+    symbol,
+    floorPriceLamports: floorLamports || null,
+    floorPriceSol: floorLamports ? floorLamports / LAMPORTS_PER_SOL : null,
+    listedCount: raw?.listedCount ?? null,
+    volume24hrSol: raw?.volume24hr != null ? Number(raw.volume24hr) / LAMPORTS_PER_SOL : null,
+    avgPrice24hrSol: raw?.avgPrice24hr != null ? Number(raw.avgPrice24hr) / LAMPORTS_PER_SOL : null,
+    exec: false,
+    raw,
+  };
+}
+
+function normalizeListing(item = {}) {
+  const priceSol = Number(item.price ?? 0);
+  return {
+    tokenMint: item.tokenMint ?? null,
+    tokenATA: item.tokenAddress ?? null,
+    seller: item.seller ?? null,
+    sellerReferral: item.sellerReferral ?? null,
+    auctionHouse: item.auctionHouse ?? null,
+    pdaAddress: item.pdaAddress ?? null,
+    priceSol: priceSol || null,
+    priceLamports: priceSol ? Math.round(priceSol * LAMPORTS_PER_SOL) : null,
+    tokenSize: item.tokenSize ?? 1,
+  };
+}
+
+export async function magicEdenSolListings(args = {}, opts = {}) {
+  const symbol = symbolArg(args.symbol || args.collection);
+  const limit = Math.min(Math.max(Number(args.limit ?? 20) || 20, 1), 100);
+  const offset = Math.max(Number(args.offset ?? 0) || 0, 0);
+  const url = new URL(`${base(opts)}/collections/${encodeURIComponent(symbol)}/listings`);
+  url.searchParams.set("offset", String(offset));
+  url.searchParams.set("limit", String(limit));
+  if (args.sort) url.searchParams.set("sort", String(args.sort));
+  const raw = await httpJson(url.toString(), {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  const listings = (Array.isArray(raw) ? raw : []).map(normalizeListing);
+  return {
+    provider: "magiceden-sol",
+    chain: "solana-mainnet-beta",
+    symbol,
+    count: listings.length,
+    listings,
+    exec: false,
+  };
+}
+
+export async function magicEdenSolTokenListing(args = {}, opts = {}) {
+  const mint = solanaPubkey(args.tokenMint || args.mint, "tokenMint");
+  const raw = await httpJson(`${base(opts)}/tokens/${encodeURIComponent(mint)}/listings`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  const listings = (Array.isArray(raw) ? raw : []).map(normalizeListing);
+  return { provider: "magiceden-sol", chain: "solana-mainnet-beta", tokenMint: mint, listings, exec: false };
+}
+
+/**
+ * Build an UNSIGNED buy_now transaction for a listed Solana NFT.
+ * Requires MAGICEDEN_API_KEY. Returns base64 tx for the user's wallet.
+ */
+export async function magicEdenSolPrepareBuy(args = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("magiceden: MAGICEDEN_API_KEY required to build a buy instruction");
+  const buyer = solanaPubkey(args.buyer || args.userPublicKey, "buyer");
+  const seller = solanaPubkey(args.seller, "seller");
+  const tokenMint = solanaPubkey(args.tokenMint, "tokenMint");
+  const tokenATA = solanaPubkey(args.tokenATA || args.tokenAddress, "tokenATA");
+  const auctionHouse = solanaPubkey(args.auctionHouse, "auctionHouse");
+  const priceSol = positiveNumber(args.priceSol ?? args.price, "priceSol");
+  const maxPriceSol = args.maxPriceSol == null ? priceSol : positiveNumber(args.maxPriceSol, "maxPriceSol");
+  if (priceSol > maxPriceSol) {
+    throw new Error(`magiceden: listing price ${priceSol} SOL exceeds maxPriceSol cap ${maxPriceSol} SOL`);
+  }
+  const url = new URL(`${base(opts)}/instructions/buy_now`);
+  url.searchParams.set("buyer", buyer);
+  url.searchParams.set("seller", seller);
+  url.searchParams.set("auctionHouseAddress", auctionHouse);
+  url.searchParams.set("tokenMint", tokenMint);
+  url.searchParams.set("tokenATA", tokenATA);
+  url.searchParams.set("price", String(priceSol));
+  if (args.sellerReferral) url.searchParams.set("sellerReferral", String(args.sellerReferral));
+  if (args.buyerReferral) url.searchParams.set("buyerReferral", String(args.buyerReferral));
+  const raw = await httpJson(url.toString(), {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+  const data = raw?.v0?.tx?.data ?? raw?.tx?.data ?? null;
+  // Accept ONLY the documented unsigned instruction field. A pre-signed payload
+  // (txSigned) from a compromised or impersonated API must never be laundered
+  // into a "prepare" result — the user would be signing bytes Oracle never
+  // validated against the price cap.
+  if (!Array.isArray(data)) {
+    if (raw?.txSigned) throw new Error("magiceden: refused a pre-signed transaction payload from the API");
+    throw new Error("magiceden: buy_now returned no unsigned transaction payload");
+  }
+  const transaction = Buffer.from(data).toString("base64");
+  return {
+    provider: "magiceden-sol",
+    chain: "solana-mainnet-beta",
+    kind: "nft-buy",
+    prepareReady: true,
+    executionReady: false,
+    signingReady: false,
+    broadcastReady: false,
+    requiresUserSignature: true,
+    buyer,
+    seller,
+    tokenMint,
+    priceSol,
+    maxPriceSol,
+    lamports: lamports(priceSol),
+    transaction,
+    transactionEncoding: "base64",
+    raw,
+  };
+}
+
+/**
+ * Build an UNSIGNED list instruction so a holder can list their own NFT.
+ * Requires MAGICEDEN_API_KEY. User wallet signs; Oracle never broadcasts.
+ */
+export async function magicEdenSolPrepareList(args = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("magiceden: MAGICEDEN_API_KEY required to build a list instruction");
+  const seller = solanaPubkey(args.seller || args.userPublicKey, "seller");
+  const tokenMint = solanaPubkey(args.tokenMint, "tokenMint");
+  const tokenATA = solanaPubkey(args.tokenATA || args.tokenAddress, "tokenATA");
+  const auctionHouse = solanaPubkey(args.auctionHouse, "auctionHouse");
+  const priceSol = positiveNumber(args.priceSol ?? args.price, "priceSol");
+  const url = new URL(`${base(opts)}/instructions/sell`);
+  url.searchParams.set("seller", seller);
+  url.searchParams.set("auctionHouseAddress", auctionHouse);
+  url.searchParams.set("tokenMint", tokenMint);
+  url.searchParams.set("tokenAccount", tokenATA);
+  url.searchParams.set("price", String(priceSol));
+  const raw = await httpJson(url.toString(), {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+  const data = raw?.v0?.tx?.data ?? raw?.tx?.data ?? null;
+  const transaction = Array.isArray(data) ? Buffer.from(data).toString("base64") : null;
+  if (!transaction) throw new Error("magiceden: sell returned no transaction payload");
+  return {
+    provider: "magiceden-sol",
+    chain: "solana-mainnet-beta",
+    kind: "nft-list",
+    prepareReady: true,
+    executionReady: false,
+    signingReady: false,
+    broadcastReady: false,
+    requiresUserSignature: true,
+    seller,
+    tokenMint,
+    priceSol,
+    transaction,
+    transactionEncoding: "base64",
+    raw,
+  };
+}
+
+/**
+ * Launchpad mint instruction. Requires MAGICEDEN_API_KEY. Unsigned only.
+ */
+export async function magicEdenSolPrepareMint(args = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("magiceden: MAGICEDEN_API_KEY required to build a mint instruction");
+  const buyer = solanaPubkey(args.buyer || args.userPublicKey, "buyer");
+  const symbol = symbolArg(args.symbol || args.collection);
+  // A mint debits the buyer, so the cap is mandatory. Recording it without
+  // enforcing it is worse than having none: the caller believes a ceiling held.
+  if (args.maxPriceSol == null) {
+    throw new Error("magiceden: maxPriceSol is required to prepare a mint — an uncapped mint has no spend ceiling");
+  }
+  const maxPriceSol = positiveNumber(args.maxPriceSol, "maxPriceSol");
+  const nftAmount = args.nftAmount == null ? 1 : positiveNumber(args.nftAmount, "nftAmount");
+  if (!Number.isInteger(nftAmount)) throw new Error("magiceden: nftAmount must be a whole number");
+
+  const url = new URL(`${base(opts)}/instructions/mint`);
+  url.searchParams.set("symbol", symbol);
+  url.searchParams.set("wallet", buyer);
+  url.searchParams.set("nftAmount", String(nftAmount));
+  const raw = await httpJson(url.toString(), {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+
+  // Enforce the cap against the price the launchpad actually quotes. If the
+  // price cannot be determined, fail closed rather than return an unbounded
+  // mint the caller thinks is capped.
+  const quoted = mintPriceSol(raw);
+  if (quoted == null) {
+    throw new Error("magiceden: mint price not present in the API response — refusing to prepare an unverifiable spend");
+  }
+  const totalSol = quoted * nftAmount;
+  if (totalSol > maxPriceSol) {
+    throw new Error(
+      `magiceden: mint cost ${totalSol} SOL exceeds maxPriceSol cap ${maxPriceSol} SOL`
+    );
+  }
+
+  const data = raw?.v0?.tx?.data ?? raw?.tx?.data ?? null;
+  if (!Array.isArray(data)) {
+    if (raw?.txSigned) throw new Error("magiceden: refused a pre-signed transaction payload from the API");
+    throw new Error("magiceden: mint returned no unsigned transaction payload");
+  }
+  const transaction = Buffer.from(data).toString("base64");
+  return {
+    provider: "magiceden-sol",
+    chain: "solana-mainnet-beta",
+    kind: "nft-mint",
+    prepareReady: true,
+    executionReady: false,
+    signingReady: false,
+    broadcastReady: false,
+    requiresUserSignature: true,
+    buyer,
+    symbol,
+    nftAmount,
+    priceSol: quoted,
+    totalSol,
+    maxPriceSol,
+    transaction,
+    transactionEncoding: "base64",
+    raw,
+  };
+}