@oracle-agent/oracle 0.1.0

package/src/data/providers/morpho.mjs

@@ -0,0 +1,173 @@
+// Morpho public GraphQL API — markets/vaults, no key. ERC-4626 vault
+// prepare returns a guarded intent only; dynamic vault tx signing/submission is a
+// later, separately gated execution step.
+
+import { Interface, getAddress, isAddress, keccak256, toUtf8Bytes } from "ethers";
+import { httpJson } from "../http.mjs";
+import { rpcCall as defaultRpcCall } from "./evm-rpc.mjs";
+
+export const MORPHO_API = "https://api.morpho.org/graphql";
+
+const ERC4626 = new Interface([
+  "function asset() view returns (address)",
+  "function maxDeposit(address owner) view returns (uint256)",
+  "function previewDeposit(uint256 assets) view returns (uint256)",
+  "function deposit(uint256 assets,address receiver) returns (uint256)",
+  "function maxWithdraw(address owner) view returns (uint256)",
+  "function previewWithdraw(uint256 assets) view returns (uint256)",
+  "function withdraw(uint256 assets,address receiver,address owner) returns (uint256)",
+]);
+
+const endpoint = (o = {}) => o.baseUrl || process.env.MORPHO_API_URL || MORPHO_API;
+
+async function gql(query, variables, opts = {}) {
+  return httpJson(endpoint(opts), {
+    method: "POST",
+    body: { query, variables },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+}
+
+const MARKET_QUERY = `query Markets($first: Int, $where: MarketFilters) { markets(first: $first, where: $where) { items { marketId lltv listed loanAsset { address symbol decimals } collateralAsset { address symbol decimals } state { supplyAssetsUsd borrowAssetsUsd } } } }`;
+const VAULT_QUERY = `query Vaults($first: Int, $where: VaultFilters) { vaults(first: $first, where: $where) { items { address name symbol listed asset { address symbol decimals } state { totalAssets totalAssetsUsd apy } } } }`;
+
+function normalAddress(value, label) {
+  const text = String(value || "").trim();
+  if (!isAddress(text)) throw new Error(`morpho: ${label} must be an address`);
+  return getAddress(text).toLowerCase();
+}
+
+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(`morpho: ${label} must be a positive integer string`);
+  }
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+async function callVault(chainId, vault, fn, args, opts = {}) {
+  const data = ERC4626.encodeFunctionData(fn, args);
+  const call = opts.rpcCall || defaultRpcCall;
+  const result = await call(Number(chainId), "eth_call", [{ to: vault, data }, "latest"], opts);
+  return ERC4626.decodeFunctionResult(fn, result);
+}
+
+function listedVault(items, vault) {
+  const target = vault.toLowerCase();
+  return (items || []).find((item) => String(item?.address || "").toLowerCase() === target) || null;
+}
+
+export async function morphoMarkets(args = {}, opts = {}) {
+  const first = Math.min(100, Math.max(1, Number(args.first || 20)));
+  const chainIds = (args.chainIds || [args.chainId || 1]).map(Number);
+  return gql(MARKET_QUERY, { first, chainIds, where: { chainId_in: chainIds } }, opts);
+}
+
+export async function morphoVaults(args = {}, opts = {}) {
+  const first = Math.min(100, Math.max(1, Number(args.first || 20)));
+  const chainIds = (args.chainIds || [args.chainId || 1]).map(Number);
+  return gql(VAULT_QUERY, { first, chainIds, where: { chainId_in: chainIds } }, opts);
+}
+
+export async function morphoHealth(opts = {}) {
+  const data = await gql("query { __typename }", {}, opts);
+  return { ok: data?.data?.__typename === "Query" };
+}
+
+export async function morphoPrepareVault(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? 8453);
+  const action = String(args.action || "deposit").toLowerCase();
+  if (!["deposit", "withdraw"].includes(action)) throw new Error("morpho: action must be deposit or withdraw");
+  const vault = normalAddress(args.vault || args.vaultAddress, "vault");
+  const owner = normalAddress(args.owner || args.from || args.sender, "owner");
+  const receiver = normalAddress(args.receiver || owner, "receiver");
+  const amount = amountString(args.amount || args.assets, "amount");
+  const minTotalAssetsUsd = Number(args.minTotalAssetsUsd ?? 100_000);
+
+  const vaults = await morphoVaults({ chainId, first: 100 }, opts);
+  const info = listedVault(vaults?.data?.vaults?.items, vault);
+  if (!info) throw new Error("morpho: vault not found in public Morpho vault registry");
+  if (info.listed === false) throw new Error("morpho: vault is not listed");
+  const totalAssetsUsd = Number(info?.state?.totalAssetsUsd ?? 0);
+  if (Number.isFinite(minTotalAssetsUsd) && totalAssetsUsd < minTotalAssetsUsd) {
+    throw new Error(`morpho: vault totalAssetsUsd ${totalAssetsUsd} below minimum ${minTotalAssetsUsd}`);
+  }
+
+  const [assetOnchain] = await callVault(chainId, vault, "asset", [], opts);
+  const asset = normalAddress(assetOnchain, "vault asset");
+  const apiAsset = info?.asset?.address ? normalAddress(info.asset.address, "api vault asset") : asset;
+  if (apiAsset !== asset) throw new Error("morpho: API asset and on-chain asset mismatch");
+
+  let data;
+  let floor;
+  if (action === "deposit") {
+    const [maxDeposit] = await callVault(chainId, vault, "maxDeposit", [owner], opts);
+    if (BigInt(amount) > BigInt(maxDeposit.toString())) throw new Error("morpho: amount exceeds maxDeposit");
+    const [sharesOut] = await callVault(chainId, vault, "previewDeposit", [amount], opts);
+    if (BigInt(sharesOut.toString()) <= 0n) throw new Error("morpho: previewDeposit returned zero shares");
+    floor = { minSharesOut: sharesOut.toString() };
+    data = ERC4626.encodeFunctionData("deposit", [amount, receiver]);
+  } else {
+    const [maxWithdraw] = await callVault(chainId, vault, "maxWithdraw", [owner], opts);
+    if (BigInt(amount) > BigInt(maxWithdraw.toString())) throw new Error("morpho: amount exceeds maxWithdraw");
+    const [sharesIn] = await callVault(chainId, vault, "previewWithdraw", [amount], opts);
+    if (BigInt(sharesIn.toString()) <= 0n) throw new Error("morpho: previewWithdraw returned zero shares");
+    floor = { maxSharesIn: sharesIn.toString() };
+    data = ERC4626.encodeFunctionData("withdraw", [amount, receiver, owner]);
+  }
+
+  const vaultGuard = {
+    mode: "erc4626-vault",
+    version: 1,
+    provider: "morpho",
+    chainId,
+    action,
+    vault,
+    asset,
+    owner,
+    receiver,
+    amount,
+    totalAssetsUsd,
+    ...floor,
+    calldataHash: keccak256(toUtf8Bytes(data)),
+    issuedAtMs: Date.now(),
+    expiresAtMs: Date.now() + 20_000,
+  };
+  vaultGuard.guardHash = keccak256(toUtf8Bytes(canonicalJson(vaultGuard)));
+
+  return {
+    provider: "morpho",
+    protocol: "erc4626-vault",
+    vaultReady: true,
+    executionReady: false,
+    chainId,
+    action,
+    vault,
+    asset,
+    owner,
+    receiver,
+    amount,
+    vaultInfo: info,
+    vaultGuard,
+    requiresApproval: action === "deposit" ? { token: asset, spender: vault, amount } : null,
+    transaction: {
+      chainId,
+      from: owner,
+      to: vault,
+      data,
+      value: "0x0",
+      madVault: vaultGuard,
+    },
+  };
+}

package/src/data/providers/odos.mjs

@@ -0,0 +1,155 @@
+// DEPRECATED UPSTREAM (2026-07-30).
+//
+// Odos sunset their public SOR API. Both /sor/quote/v2 and /sor/quote/v3 return
+// HTTP 410 Gone with `sunset: Thu, 30 Jul 2026 12:00:00 GMT` and a link to the
+// protocol's deprecation notice.
+//
+// The module is kept rather than deleted so that (a) an existing caller gets a
+// clear 410 instead of a missing-import crash, and (b) it re-activates if Odos
+// ships a replacement endpoint. The best-execution router already tolerates a
+// failing source, so this degrades the comparison by one source rather than
+// breaking it.
+//
+// Do NOT mark this provider as healthy in the catalog while the sunset stands.
+
+// Odos public SOR v3 quote + simulated transaction assembly.
+import { isAddress } from "ethers";
+import { httpJson } from "../http.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
+
+export const ODOS_API = "https://api.odos.xyz";
+const base = (o = {}) => (o.baseUrl || process.env.ODOS_API_URL || ODOS_API).replace(/\/$/, "");
+
+export async function odosChains(opts = {}) {
+  return httpJson(`${base(opts)}/info/chains`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs });
+}
+
+function validateQuoteArgs(args = {}) {
+  const chainId = Number(args.chainId);
+  if (!Number.isInteger(chainId)) throw new Error("odos: chainId required");
+  if (!Array.isArray(args.inputTokens) || args.inputTokens.length < 1) throw new Error("odos: inputTokens[] required");
+  if (!Array.isArray(args.outputTokens) || args.outputTokens.length !== 1) {
+    throw new Error("odos: agentic execution currently requires exactly one output token");
+  }
+  if (!isAddress(String(args.userAddr || ""))) throw new Error("odos: valid userAddr required");
+  return chainId;
+}
+
+async function rawQuote(args = {}, opts = {}) {
+  const chainId = validateQuoteArgs(args);
+  const selected = resolveAutoSlippage({
+    liquidityUsd: args.liquidityUsd,
+    priceChange5m: args.priceChange5m,
+    requestedCapBps: args.maxSlippageBps ?? args.slippageBps,
+  });
+  if (!selected.executable) {
+    throw new Error(`odos: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
+  }
+  const body = {
+    chainId,
+    inputTokens: args.inputTokens,
+    outputTokens: args.outputTokens,
+    userAddr: args.userAddr,
+    slippageLimitPercent: selected.selectedBps / 100,
+    disableRFQs: args.disableRFQs ?? true,
+    compact: args.compact ?? true,
+    simple: args.simple ?? false,
+  };
+  const quote = await httpJson(`${base(opts)}/sor/quote/v3`, {
+    method: "POST",
+    body,
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 25_000,
+  });
+  const amountOut = quote?.outAmounts?.[0];
+  if (!quote?.pathId || !amountOut) throw new Error("odos: quote missing pathId or outAmounts[0]");
+  return { chainId, selected, quote, amountOut };
+}
+
+export async function odosQuote(args = {}, opts = {}) {
+  const { chainId, quote, amountOut } = await rawQuote(args, opts);
+  return {
+    ...attachAutoSlippage(quote, {
+      chainId,
+      venue: "odos-quote",
+      amountOut,
+      liquidityUsd: args.liquidityUsd,
+      priceChange5m: args.priceChange5m,
+      requestedCapBps: args.maxSlippageBps ?? args.slippageBps,
+    }),
+    executionReady: false,
+    executionBlocker: "call prepare to assemble and simulate the path",
+  };
+}
+
+export async function odosPrepare(args = {}, opts = {}) {
+  const { chainId, quote: quoteRaw, amountOut } = await rawQuote(args, opts);
+  const assembled = await httpJson(`${base(opts)}/sor/assemble`, {
+    method: "POST",
+    body: {
+      userAddr: args.userAddr,
+      pathId: quoteRaw.pathId,
+      simulate: true,
+      ...(args.receiver ? { receiver: args.receiver } : {}),
+    },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 30_000,
+  });
+  const tx = assembled?.transaction;
+  if (!tx?.to || !tx?.data) throw new Error("odos: assemble returned no executable transaction");
+  if (Number(tx.chainId ?? chainId) !== chainId) throw new Error("odos: transaction chain mismatch");
+  if (tx.from && String(tx.from).toLowerCase() !== String(args.userAddr).toLowerCase()) {
+    throw new Error("odos: transaction sender mismatch");
+  }
+  if (assembled?.simulation?.isSuccess !== true) {
+    throw new Error(`odos: assembled transaction simulation failed: ${assembled?.simulation?.simulationError || "unknown"}`);
+  }
+  const quote = attachAutoSlippage(quoteRaw, {
+    chainId,
+    venue: tx.to,
+    amountOut,
+    liquidityUsd: args.liquidityUsd,
+    priceChange5m: args.priceChange5m,
+    requestedCapBps: args.maxSlippageBps ?? args.slippageBps,
+  });
+  const simulatedOut = assembled?.simulation?.amountsOut?.[0];
+  if (simulatedOut != null && BigInt(simulatedOut) < BigInt(quote.amountOutMinimum)) {
+    throw new Error("odos: simulation output is below the bounded automatic floor");
+  }
+  const native = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+  const zeroNative = "0x0000000000000000000000000000000000000000";
+  const approvals = args.inputTokens
+    .filter((item) => ![native, zeroNative].includes(String(item.tokenAddress).toLowerCase()))
+    .map((item) => ({ token: item.tokenAddress, spender: tx.to, amount: String(item.amount) }));
+  return {
+    provider: "odos",
+    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,
+    simulation: assembled.simulation,
+    requiresApproval: approvals,
+    autoSlippage: quote.autoSlippage,
+    transaction: {
+      chainId,
+      from: tx.from || args.userAddr,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value ?? "0x0",
+      ...(tx.gas != null ? { gasLimit: tx.gas } : {}),
+      ...(tx.nonce != null ? { nonce: tx.nonce } : {}),
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
+    },
+  };
+}
+
+export async function odosHealth(opts = {}) {
+  const data = await odosChains(opts);
+  return { ok: Array.isArray(data?.chains) && data.chains.length > 0, chainCount: data?.chains?.length || 0 };
+}

package/src/data/providers/oneinch.mjs

@@ -0,0 +1,173 @@
+// 1inch Swap API v6 — requires ONEINCH_API_KEY (Bearer).
+
+import { httpJson } from "../http.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
+import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
+
+export const ONEINCH_API = "https://api.1inch.dev/swap/v6.0";
+
+function endpoint(opts = {}) {
+  return resolveProviderEndpoint({
+    provider: "oneinch",
+    defaultUrl: ONEINCH_API,
+    hosts: ["api.1inch.dev"],
+    url: opts.baseUrl || process.env.ONEINCH_API_URL,
+  });
+}
+
+function base(opts = {}) {
+  return endpoint(opts).baseUrl;
+}
+
+function apiKey(opts = {}) {
+  return opts.apiKey || process.env.ONEINCH_API_KEY || process.env.ONE_INCH_API_KEY || "";
+}
+
+function headers(opts = {}) {
+  const k = apiKey(opts);
+  return credentialedHeaders(
+    { accept: "application/json" },
+    { Authorization: k ? `Bearer ${k}` : "" },
+    endpoint(opts).trusted
+  );
+}
+
+export async function oneinchHealth(opts = {}) {
+  if (!apiKey(opts)) {
+    return { ok: false, configured: false, error: "ONEINCH_API_KEY not set" };
+  }
+  try {
+    const q = await oneinchQuote(
+      {
+        chainId: 8453,
+        src: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+        dst: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        amount: "1000000000000000",
+      },
+      opts
+    );
+    return { ok: true, configured: true, dstAmount: q.dstAmount };
+  } catch (e) {
+    return { ok: false, configured: true, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+export async function oneinchQuote(q = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("ONEINCH_API_KEY required for 1inch");
+  const chainId = Number(q.chainId ?? 1);
+  const { src, dst, amount } = q;
+  if (!src || !dst || !amount) throw new Error("oneinchQuote requires src, dst, amount");
+  const params = new URLSearchParams({
+    src,
+    dst,
+    amount: String(amount),
+  });
+  const result = await httpJson(`${base(opts)}/${chainId}/quote?${params}`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+  if (!result?.dstAmount) return result;
+  return attachAutoSlippage(result, {
+    chainId,
+    venue: "1inch-quote",
+    amountOut: result.dstAmount,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+function isNative(value) {
+  return /^(eth|native|0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee)$/i.test(String(value || ""));
+}
+
+export async function oneinchApproveSpender(q = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("ONEINCH_API_KEY required for 1inch");
+  const chainId = Number(q.chainId ?? 1);
+  return httpJson(`${base(opts)}/${chainId}/approve/spender`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}
+
+export async function oneinchPrepare(q = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("ONEINCH_API_KEY required for 1inch");
+  const chainId = Number(q.chainId ?? 1);
+  const { src, dst, amount } = q;
+  const from = q.from || q.fromAddress || q.userAddress || q.taker;
+  if (!src || !dst || !amount || !from) throw new Error("oneinchPrepare requires src, dst, amount, from");
+  const selected = resolveAutoSlippage({
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  if (!selected.executable) {
+    throw new Error(`1inch: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
+  }
+  const params = new URLSearchParams({
+    src,
+    dst,
+    amount: String(amount),
+    from,
+    // 1inch Classic Swap API expresses slippage as percentage points.
+    slippage: String(selected.selectedBps / 100),
+  });
+  if (q.receiver) params.set("receiver", q.receiver);
+  if (q.referrer) params.set("referrer", q.referrer);
+  if (q.disableEstimate != null) params.set("disableEstimate", String(Boolean(q.disableEstimate)));
+  if (q.allowPartialFill != null) params.set("allowPartialFill", String(Boolean(q.allowPartialFill)));
+  if (q.includeProtocols) params.set("includeProtocols", String(q.includeProtocols));
+  if (q.excludeProtocols) params.set("excludeProtocols", String(q.excludeProtocols));
+  const raw = await httpJson(`${base(opts)}/${chainId}/swap?${params}`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 25_000,
+  });
+  const tx = raw?.tx;
+  if (!tx?.to || !tx?.data) throw new Error("1inch: swap returned no executable tx");
+  if (tx.from && String(tx.from).toLowerCase() !== String(from).toLowerCase()) {
+    throw new Error("1inch: transaction sender mismatch");
+  }
+  const amountOut = raw?.dstAmount || raw?.toTokenAmount || raw?.buyAmount;
+  if (!amountOut) throw new Error("1inch: swap response missing dstAmount");
+  const quote = attachAutoSlippage(raw, {
+    chainId,
+    venue: tx.to,
+    amountOut,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  let requiresApproval = null;
+  if (!isNative(src)) {
+    const spender = raw?.spender || raw?.approvalAddress || (await oneinchApproveSpender({ chainId }, opts))?.address;
+    if (!spender) throw new Error("1inch: ERC-20 route missing approval spender");
+    requiresApproval = { token: src, spender, amount: String(amount) };
+  }
+  return {
+    provider: "oneinch",
+    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 || from,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value ?? "0x0",
+      ...(tx.gas != null ? { gasLimit: tx.gas } : {}),
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
+    },
+  };
+}

package/src/data/providers/opensea-multichain.mjs

@@ -0,0 +1,136 @@
+// OpenSea multi-chain NFT scanner.
+//
+// OpenSea v2 indexes NFTs across every chain it supports, keyed by a chain slug.
+// This module is the ONE place Oracle resolves an NFT contract on ANY chain, so
+// a user can paste a bare contract address and get back what it actually is
+// before deciding to buy.
+//
+// Reads only. Nothing here signs or broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+// OpenSea chain slugs -> EVM chainId. The slug is what the v2 API wants in the
+// path; the chainId is what the rest of Oracle speaks.
+export const OPENSEA_CHAINS = Object.freeze({
+  ethereum: 1,
+  matic: 137,
+  base: 8453,
+  arbitrum: 42161,
+  arbitrum_nova: 42170,
+  optimism: 10,
+  avalanche: 43114,
+  klaytn: 8217,
+  zora: 7777777,
+  blast: 81457,
+  sei: 1329,
+  b3: 8333,
+  ape_chain: 33139,
+  ronin: 2020,
+  soneium: 1868,
+  unichain: 130,
+  berachain: 80094,
+  flow: 747,
+  abstract: 2741,
+  gravity: 1625,
+  xai: 660279,
+  bsc: 56,
+  solana: null, // non-EVM; OpenSea indexes it but there is no chainId
+});
+
+export const CHAIN_ID_TO_OPENSEA = Object.freeze(
+  Object.fromEntries(
+    Object.entries(OPENSEA_CHAINS)
+      .filter(([, id]) => id != null)
+      .map(([slug, id]) => [id, slug])
+  )
+);
+
+/** All chains Oracle can scan for NFTs. */
+export function openseaSupportedChains() {
+  return Object.entries(OPENSEA_CHAINS).map(([slug, chainId]) => ({ slug, chainId }));
+}
+
+export function openseaChainSlug(chain) {
+  if (chain == null) return null;
+  const text = String(chain).trim().toLowerCase();
+  if (OPENSEA_CHAINS[text] !== undefined) return text;
+  const asId = Number(text);
+  if (Number.isFinite(asId) && CHAIN_ID_TO_OPENSEA[asId]) return CHAIN_ID_TO_OPENSEA[asId];
+  throw new Error(`opensea: unsupported chain ${chain} — try one of: ${Object.keys(OPENSEA_CHAINS).slice(0, 8).join(", ")}…`);
+}
+
+function evmContract(value) {
+  const text = String(value ?? "").trim();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(text)) throw new Error("opensea: contract must be a 0x-prefixed 20-byte address");
+  return text.toLowerCase();
+}
+
+/**
+ * Resolve a bare contract address on ONE chain.
+ * Returns null when the chain has no such collection, so callers can fan out.
+ */
+export async function openseaContractOnChain(contract, chain, { headers, base, fetchImpl, timeoutMs } = {}) {
+  const slug = openseaChainSlug(chain);
+  const address = evmContract(contract);
+  try {
+    const raw = await httpJson(`${base}/chain/${slug}/contract/${address}`, {
+      headers,
+      fetchImpl,
+      timeoutMs: timeoutMs ?? 12_000,
+    });
+    if (!raw || !raw.collection) return null;
+    return {
+      chain: slug,
+      chainId: OPENSEA_CHAINS[slug],
+      contract: address,
+      collection: raw.collection,
+      name: raw.name ?? null,
+      tokenStandard: raw.contract_standard ?? raw.token_standard ?? null,
+      supply: raw.supply ?? null,
+    };
+  } catch (err) {
+    // 400/404 simply means "not on this chain" during a fan-out.
+    const status = err?.status;
+    if (status === 400 || status === 404) return null;
+    throw err;
+  }
+}
+
+/**
+ * Find which chain(s) a contract address lives on.
+ *
+ * Someone pasting an address rarely knows the chain, and guessing wrong is how
+ * people buy the wrong asset. Scan the supported set and report every hit.
+ */
+export async function openseaFindContract(args = {}, ctx = {}) {
+  const address = evmContract(args.contract || args.address);
+  const chains = args.chains
+    ? args.chains.map(openseaChainSlug)
+    : Object.entries(OPENSEA_CHAINS)
+        .filter(([, id]) => id != null)
+        .map(([slug]) => slug);
+
+  const results = [];
+  const concurrency = Math.max(1, Math.min(Number(args.concurrency) || 6, 12));
+  let cursor = 0;
+  async function worker() {
+    while (cursor < chains.length) {
+      const slug = chains[cursor++];
+      try {
+        const hit = await openseaContractOnChain(address, slug, ctx);
+        if (hit) results.push(hit);
+      } catch {
+        /* one chain failing must not abort the scan */
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, chains.length) }, worker));
+
+  return {
+    provider: "opensea",
+    contract: address,
+    chainsScanned: chains.length,
+    found: results.length,
+    matches: results.sort((a, b) => a.chain.localeCompare(b.chain)),
+  };
+}