nebula-ai-plugin-onchain 0.1.0

package/src/defillama.ts

@@ -0,0 +1,127 @@
+/**
+ * DeFiLlama yield discovery for Mantle.
+ *
+ * Per the project rule (CLAUDE.md), DeFiLlama is used for ANALYTICS and
+ * DISCOVERY only — never for execution. This module fetches the public yields
+ * feed, filters to Mantle, and annotates each pool with the risk signals a
+ * treasury assistant needs: stablecoin / impermanent-loss / single-vs-multi
+ * exposure, and whether the asset is a RESTRICTED product (MI4, USDY, mUSD)
+ * that must not be entered without explicit eligibility confirmation.
+ *
+ * No API key. The endpoint is GET-only and unauthenticated.
+ */
+
+export const DEFILLAMA_YIELDS_URL = 'https://yields.llama.fi/pools'
+
+/** Assets the project treats as restricted (CLAUDE.md). Discovery surfaces them but flags them. */
+const RESTRICTED_PATTERNS: ReadonlyArray<RegExp> = [/\bUSDY\b/i, /\bMI4\b/i, /\bmUSD\b/i]
+
+export function isRestrictedAsset(symbol: string, project: string): boolean {
+  const hay = `${symbol} ${project}`
+  return RESTRICTED_PATTERNS.some(re => re.test(hay))
+}
+
+export interface YieldPool {
+  /** DeFiLlama protocol slug, e.g. "aave-v3", "agni", "merchant-moe". */
+  project: string
+  /** Pool asset symbol, e.g. "USDC", "WMNT-USDC". */
+  symbol: string
+  /** DeFiLlama pool id (opaque). */
+  pool: string
+  tvlUsd: number
+  /** Total APY (base + reward), percent. */
+  apy: number
+  apyBase: number | null
+  apyReward: number | null
+  /** 7-day APY change in percentage points (momentum signal). */
+  apyPct7D: number | null
+  /** True when both legs are stablecoins. */
+  stablecoin: boolean
+  /** "no" | "yes" — impermanent-loss risk per DeFiLlama. */
+  ilRisk: string
+  /** "single" | "multi" — token exposure. */
+  exposure: string
+  poolMeta: string | null
+  /** CLAUDE.md restricted product (USDY/MI4/mUSD) — needs eligibility confirmation. */
+  restricted: boolean
+}
+
+interface RawPool {
+  chain?: string
+  project?: string
+  symbol?: string
+  pool?: string
+  tvlUsd?: number
+  apy?: number
+  apyBase?: number | null
+  apyReward?: number | null
+  apyPct7D?: number | null
+  stablecoin?: boolean
+  ilRisk?: string
+  exposure?: string
+  poolMeta?: string | null
+}
+
+function toYieldPool(p: RawPool): YieldPool {
+  const symbol = p.symbol ?? '?'
+  const project = p.project ?? '?'
+  return {
+    project,
+    symbol,
+    pool: p.pool ?? '',
+    tvlUsd: p.tvlUsd ?? 0,
+    apy: p.apy ?? 0,
+    apyBase: p.apyBase ?? null,
+    apyReward: p.apyReward ?? null,
+    apyPct7D: p.apyPct7D ?? null,
+    stablecoin: p.stablecoin ?? false,
+    ilRisk: p.ilRisk ?? 'unknown',
+    exposure: p.exposure ?? 'unknown',
+    poolMeta: p.poolMeta ?? null,
+    restricted: isRestrictedAsset(symbol, project),
+  }
+}
+
+export interface FetchYieldsOpts {
+  /** Minimum pool TVL in USD (filters dust). Default 50_000. */
+  minTvlUsd?: number
+  /** Only stablecoin pools (lower-risk treasury parking). */
+  stableOnly?: boolean
+  /** Exclude pools with impermanent-loss risk. */
+  noIlRisk?: boolean
+  /** Filter to a single protocol slug substring (e.g. "aave"). */
+  project?: string
+  /** Sort key. Default "apy". */
+  sortBy?: 'apy' | 'tvl'
+  /** Max rows. Default 10, hard-capped at 50. */
+  limit?: number
+  /** Injected fetch for tests. */
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * Fetch + filter + rank Mantle yield pools. Pure aside from the single GET.
+ */
+export async function fetchMantleYields(opts: FetchYieldsOpts = {}): Promise<YieldPool[]> {
+  const f = opts.fetchImpl ?? fetch
+  const res = await f(DEFILLAMA_YIELDS_URL)
+  if (!res.ok) throw new Error(`DeFiLlama yields API ${res.status}`)
+  const json = (await res.json()) as { status?: string; data?: RawPool[] }
+  const all = json.data ?? []
+  let pools = all.filter(p => p.chain === 'Mantle').map(toYieldPool)
+
+  const minTvl = opts.minTvlUsd ?? 50_000
+  pools = pools.filter(p => p.tvlUsd >= minTvl)
+  if (opts.stableOnly) pools = pools.filter(p => p.stablecoin)
+  if (opts.noIlRisk) pools = pools.filter(p => p.ilRisk !== 'yes')
+  if (opts.project) {
+    const needle = opts.project.toLowerCase()
+    pools = pools.filter(p => p.project.toLowerCase().includes(needle))
+  }
+
+  const key = opts.sortBy === 'tvl' ? (p: YieldPool) => p.tvlUsd : (p: YieldPool) => p.apy
+  pools.sort((a, b) => key(b) - key(a))
+
+  const limit = Math.min(Math.max(opts.limit ?? 10, 1), 50)
+  return pools.slice(0, limit)
+}

package/src/guidance.ts

@@ -0,0 +1,23 @@
+/**
+ * Always-on guidance contributed to the frozen prefix when plugin-onchain is
+ * loaded.
+ */
+
+export const ONCHAIN_GUIDANCE = `On-chain wallet + chain ops (Mantle; gas token MNT):
+
+- Limits + guardrails: call \`policy.show\` to report the active fund-control policy (caps, allowlists, slippage cap, autonomy tier, approval threshold) for "what are my limits" / "what can you spend" / "show the policy", and before explaining why an action was blocked or needs approval.
+- Your agent EOA pays gas; the operator funds it. Value-moving tools (\`chain.send\`, \`swap.execute\`, \`aave.supply\`/\`aave.withdraw\`, \`chain.wrap\`/\`chain.unwrap\`, \`chain.write\` w/ value) run through a deterministic policy: hard caps and allowlists can BLOCK an action outright, and material-risk actions REQUIRE operator approval before broadcast even in \`yolo\` mode. Every write is also dry-run simulated first; a failing simulation aborts before any gas is spent. The AI is advisory — the controls are enforced in code, not by you. Do not try to bypass a block or approval gate.
+- Balance + identity: \`chain.balance\` with no args returns native MNT + every ERC-20 the agent has ever held (Transfer-event discovery, no curated list). Pass \`token\` for a single asset or \`address\` to inspect another wallet. \`account.info\` bundles wallet + (optional) iNFT + brain provider + recent activity. Call it before answering identity / "who are you" questions instead of guessing.
+- Tokens: \`tokens.info\` resolves a symbol or address to {address, decimals, symbol}. The Agni pool list is bundled; unknown tokens fall back to on-chain reads (cached after).
+- Transfers: \`chain.send\` auto-detects native vs ERC-20 by token symbol; recipients are 0x addresses. \`chain.wrap\`/\`chain.unwrap\` move between native MNT and WMNT.
+- Trading: two DEX venues, Agni Finance (Uniswap-V3-style) and Merchant Moe (Liquidity Book). EASIEST: \`swap.best\` quotes both and executes on the better venue in one call; \`swap.compare\` does the same read-only. For a specific venue use \`swap.quote\`/\`swap.execute\` (Agni) or \`moe.quote\`/\`moe.swap\` (Moe). Slippage default 0.5%. ERC-20 input swaps auto-approve the venue's router on first use. A token with no pool on a venue can't trade there (chain.balance still shows it).
+- Lending: \`aave.markets\` lists every Aave V3 reserve with its live supply + variable-borrow APR (compare rates before supplying/borrowing). \`aave.position\` reads the agent's Aave V3 supplied/borrowed/health-factor; \`aave.supply\`/\`aave.withdraw\` move collateral in/out; \`aave.borrow\`/\`aave.repay\` open/close variable-rate debt against that collateral. Borrowing is leverage: the borrow/repay receipts report the resulting health factor (lower = closer to liquidation), and the pre-flight simulation rejects an over-borrow. Surface the health factor when proposing a borrow.
+- CEX balance: \`cex.balance\` reads the Bybit Unified account balance (read-only) so you can show a combined CEX + on-chain treasury picture. Needs BYBIT_API_KEY/SECRET in the env (read-only key). You CANNOT trade or transfer on the CEX — those bypass the on-chain safety pipeline and are intentionally not exposed.
+- Counterparty intel: \`nansen.labels\` returns Nansen entity labels for an address (exchange / fund / smart-money / contract / red-flags like scam, hack, sanctioned, mixer). Call it to vet a transfer recipient or a contract before interacting; if it returns \`flagged: true\`, do NOT transact without operator confirmation. Needs NANSEN_API_KEY in the env — if unset it reports so and you proceed without the intel.
+- Token risk: \`risk.token\` vets a token before you hold or buy it — can-you-exit (live quote on Agni/Moe), liquidity depth, restricted-RWA flag, real-contract check — returning a low/elevated/high verdict. Call it before proposing a buy/supply into an unfamiliar token; if it returns high (untradeable / no contract) do NOT trade, and treat restricted/elevated as needing operator confirmation.
+- Yield discovery: \`defi.yields\` lists Mantle lending/LP opportunities (via DeFiLlama) ranked by APY or TVL, with risk signals (stablecoin, IL risk, exposure, 7d trend). Use it for "best yield on Mantle" / "where to park USDC". It is ANALYTICS ONLY — it never moves funds; to act on a result, use \`aave.supply\` or \`swap.execute\`. Rows flagged \`restricted: true\` (USDY/MI4/mUSD) need eligibility confirmation before you propose entering them.
+- Analysis: \`chain.tx\` decodes any tx hash. \`chain.contract\` introspects code/proxy/ERC standards. \`chain.activity\` shows recent transfers.
+- Generic: \`chain.read\`/\`chain.write\` for any contract not covered above; takes \`signature\` + \`args\` like cast.
+- Dry-run: \`tx.simulate\` previews ANY call (\`to\` + \`signature\`/\`args\` or raw \`data\`, + optional \`value\`/\`from\`) without broadcasting — returns would-succeed + gas, or the decoded revert reason. Use it to preview an action before \`chain.write\`, debug a revert, or sanity-check a call you're unsure about.
+- Blockchain: \`chain.block\` for current head/timestamp/gasUsed. \`chain.gas\` for current gas price.
+`

package/src/index.ts

@@ -0,0 +1,139 @@
+/**
+ * nebula-ai-plugin-onchain
+ *
+ * Brain limbs for on-chain operations on Mantle:
+ *
+ *   Wallet/account:  account.info, account.balance
+ *   Balance:         chain.balance
+ *   Tokens:          tokens.info
+ *   Transfers:       chain.send, chain.wrap, chain.unwrap
+ *   Trading:         swap.quote, swap.execute  (Agni V3, 3-tier scan)
+ *                    moe.quote, moe.swap        (Merchant Moe Liquidity Book)
+ *                    swap.compare, swap.best    (multi-venue best execution)
+ *   Lending:         aave.position, aave.markets, aave.supply, aave.withdraw,
+ *                    aave.borrow, aave.repay  (Aave V3)
+ *   Discovery:       defi.yields  (DeFiLlama, read-only analytics)
+ *   Risk:            risk.token   (pre-trade token risk assessment, read-only)
+ *                    nansen.labels  (Nansen counterparty intel, env NANSEN_API_KEY)
+ *   Controls:        policy.show  (active fund-control policy, read-only)
+ *   Blockchain:      chain.block, chain.gas
+ *   Analysis:        chain.tx, chain.contract, chain.activity
+ *   Generic:         chain.read, chain.write, tx.simulate
+ *
+ * Value-moving tools run through policy -> simulate -> (approval) -> execute.
+ *
+ * Side-band runtime ctx attached to PluginContext under `.onchain` (see
+ * `OnchainRuntimeContext` in `./types.ts`). Without it, the plugin registers
+ * nothing — graceful no-op for unit-test loaders.
+ */
+
+import type { NativePlugin, ToolDef } from 'nebula-ai-core'
+export {
+  simulateNativeSend,
+  simulateContractWrite,
+  simulateRawTx,
+  type SimResult,
+} from './simulate'
+export {
+  evaluatePolicy,
+  policyFromEnv,
+  type OnchainPolicy,
+  type PolicyAction,
+  type PolicyVerdict,
+} from './policy'
+export { policyRequiresApprovalForCall } from './approval'
+import {
+  makeAaveBorrow,
+  makeAaveMarkets,
+  makeAavePosition,
+  makeAaveRepay,
+  makeAaveSupply,
+  makeAaveWithdraw,
+} from './tools/aave'
+import { makeAccountInfo } from './tools/account'
+import { makeAccountBalance } from './tools/account-balance'
+import { makeChainActivity, makeChainContract, makeChainTx } from './tools/analysis'
+import { makeChainBalance } from './tools/balance'
+import { makeChainBlock, makeChainGas } from './tools/blockchain'
+import { makeCexBalance } from './tools/cex'
+import { makeDefiYields } from './tools/defillama'
+import { makeChainRead, makeChainWrite } from './tools/generic'
+import { makeIdentityRegister, makeIdentityResolve } from './tools/identity'
+import { makeMoeQuote, makeMoeSwap } from './tools/moe'
+import { makeNansenLabels } from './tools/nansen'
+import { makePolicyShow } from './tools/policy-show'
+import { makeRiskToken } from './tools/risk'
+import { makeTxSimulate } from './tools/simulate-tx'
+import { makeSwapExecute, makeSwapQuote } from './tools/swap'
+import { makeSwapBest, makeSwapCompare } from './tools/swap-best'
+import { makeTokensInfo } from './tools/tokens-info'
+import { makeChainSend } from './tools/transfer'
+import { makeChainUnwrap, makeChainWrap } from './tools/wrap'
+import type { OnchainRuntimeContext } from './types'
+
+export { ONCHAIN_GUIDANCE } from './guidance'
+export { discoverMintBlock } from './mint-block'
+export type { OnchainRuntimeContext } from './types'
+export {
+  AGNI_BY_NETWORK,
+  AAVE_POOL_BY_NETWORK,
+  MULTICALL3,
+  FEE_TIERS,
+  DEFAULT_DEADLINE_SECS,
+  DEFAULT_SLIPPAGE_BPS,
+} from './constants'
+
+const plugin: NativePlugin = {
+  name: 'onchain',
+  register: ctx => {
+    const onchain = (ctx as unknown as { onchain?: OnchainRuntimeContext }).onchain
+    if (!onchain) return // soft-init for tests/non-onchain contexts
+
+    ctx.registerTool(makeAccountInfo(onchain) as ToolDef)
+    ctx.registerTool(makeAccountBalance(onchain) as ToolDef)
+    ctx.registerTool(makeChainBalance(onchain) as ToolDef)
+    ctx.registerTool(makeTokensInfo(onchain) as ToolDef)
+
+    ctx.registerTool(makeChainSend(onchain) as ToolDef)
+    ctx.registerTool(makeChainWrap(onchain) as ToolDef)
+    ctx.registerTool(makeChainUnwrap(onchain) as ToolDef)
+
+    ctx.registerTool(makeSwapQuote(onchain) as ToolDef)
+    ctx.registerTool(makeSwapExecute(onchain) as ToolDef)
+
+    ctx.registerTool(makeMoeQuote(onchain) as ToolDef)
+    ctx.registerTool(makeMoeSwap(onchain) as ToolDef)
+
+    ctx.registerTool(makeSwapCompare(onchain) as ToolDef)
+    ctx.registerTool(makeSwapBest(onchain) as ToolDef)
+
+    ctx.registerTool(makeAavePosition(onchain) as ToolDef)
+    ctx.registerTool(makeAaveMarkets(onchain) as ToolDef)
+    ctx.registerTool(makeAaveSupply(onchain) as ToolDef)
+    ctx.registerTool(makeAaveWithdraw(onchain) as ToolDef)
+    ctx.registerTool(makeAaveBorrow(onchain) as ToolDef)
+    ctx.registerTool(makeAaveRepay(onchain) as ToolDef)
+
+    ctx.registerTool(makeDefiYields(onchain) as ToolDef)
+    ctx.registerTool(makeRiskToken(onchain) as ToolDef)
+    ctx.registerTool(makeNansenLabels(onchain) as ToolDef)
+    ctx.registerTool(makeCexBalance(onchain) as ToolDef)
+    ctx.registerTool(makePolicyShow(onchain) as ToolDef)
+
+    ctx.registerTool(makeIdentityResolve(onchain) as ToolDef)
+    ctx.registerTool(makeIdentityRegister(onchain) as ToolDef)
+
+    ctx.registerTool(makeChainBlock(onchain) as ToolDef)
+    ctx.registerTool(makeChainGas(onchain) as ToolDef)
+
+    ctx.registerTool(makeChainTx(onchain) as ToolDef)
+    ctx.registerTool(makeChainContract(onchain) as ToolDef)
+    ctx.registerTool(makeChainActivity(onchain) as ToolDef)
+
+    ctx.registerTool(makeChainRead(onchain) as ToolDef)
+    ctx.registerTool(makeChainWrite(onchain) as ToolDef)
+    ctx.registerTool(makeTxSimulate(onchain) as ToolDef)
+  },
+}
+
+export default plugin

package/src/mint-block.ts

@@ -0,0 +1,53 @@
+/**
+ * One-shot iNFT mint block discovery for the Transfer-event scan floor.
+ *
+ * Uses `rawGetLogs` to bypass viem's `getLogs` topic-stripping (verified May
+ * 1 2026; without raw, the call falls through to "topics:[]" and the Mantle RPC
+ * rejects with "result set exceeds 10000 logs"). Walks recent → old in
+ * 50k-block chunks, capped at LOG_SCAN_MAX_CHUNKS, and returns the first
+ * (newest) match. iNFT mint Transfers have `from = 0x0` and `tokenId` in
+ * topic3, so the filter is precise.
+ */
+
+import type { Address, PublicClient } from 'viem'
+import { LOG_SCAN_CHUNK_BLOCKS, LOG_SCAN_MAX_CHUNKS, TRANSFER_TOPIC0 } from './constants'
+import { rawGetLogs } from './raw-logs'
+
+function pad32(hex: string): `0x${string}` {
+  const stripped = hex.startsWith('0x') ? hex.slice(2) : hex
+  return `0x${stripped.padStart(64, '0')}` as `0x${string}`
+}
+
+export async function discoverMintBlock(
+  client: PublicClient,
+  contract: Address,
+  tokenId: bigint,
+): Promise<bigint | null> {
+  const head = await client.getBlockNumber()
+  const tokenIdTopic = pad32(tokenId.toString(16))
+  const fromZeroTopic = pad32('0')
+  let cursor = head
+  for (let chunks = 0; chunks < LOG_SCAN_MAX_CHUNKS && cursor > 0n; chunks++) {
+    const start = cursor - LOG_SCAN_CHUNK_BLOCKS + 1n
+    const from = start > 0n ? start : 0n
+    try {
+      const logs = await rawGetLogs({
+        client,
+        address: contract,
+        topics: [TRANSFER_TOPIC0, fromZeroTopic, null, tokenIdTopic],
+        fromBlock: from,
+        toBlock: cursor,
+      })
+      if (logs.length > 0) {
+        const earliest = logs.reduce((acc, l) =>
+          BigInt(l.blockNumber) < BigInt(acc.blockNumber) ? l : acc,
+        )
+        return BigInt(earliest.blockNumber)
+      }
+    } catch {
+      // RPC chunk failure; keep walking.
+    }
+    cursor = from - 1n
+  }
+  return null
+}

package/src/moe.ts

@@ -0,0 +1,111 @@
+/**
+ * Merchant Moe Liquidity Book quote + swap-calldata builder.
+ *
+ * The LBQuoter's `findBestPathFromAmountIn(route, amountIn)` returns the best
+ * route across LB pairs as parallel arrays (route, binSteps, versions, amounts).
+ * The last `amounts` element is the output. Those arrays feed directly into the
+ * router's `Path` struct, so the executed swap uses exactly the quoted route.
+ *
+ * Native handling: the quoter/router treat native MNT via WNATIVE (WMNT), so a
+ * native leg uses the WMNT address in the token path plus the native-specific
+ * router entrypoint (swapExactNATIVEForTokens / swapExactTokensForNATIVE).
+ */
+
+import { type Address, type PublicClient, encodeFunctionData } from 'viem'
+import { LB_QUOTER_ABI, LB_ROUTER_ABI } from './abis'
+
+export interface MoeQuote {
+  /** Token path the router will use (== quoter route). */
+  route: readonly Address[]
+  /** Per-hop bin steps for the Path struct. */
+  binSteps: readonly bigint[]
+  /** Per-hop pair versions (0=V1, 1=V2, 2=V2_1, 3=V2_2). */
+  versions: readonly number[]
+  /** Quoted output amount (raw units of the last route token). */
+  amountOut: bigint
+}
+
+/**
+ * Quote `amountIn` of `route[0]` to `route[route.length-1]` via Merchant Moe LB.
+ * Returns null when no route has liquidity (amountOut == 0).
+ */
+export async function quoteMoe(opts: {
+  client: PublicClient
+  quoter: Address
+  route: readonly Address[]
+  amountIn: bigint
+}): Promise<MoeQuote | null> {
+  const { client, quoter, route, amountIn } = opts
+  const q = (await client.readContract({
+    address: quoter,
+    abi: LB_QUOTER_ABI,
+    functionName: 'findBestPathFromAmountIn',
+    args: [route as readonly Address[], amountIn],
+  })) as {
+    route: readonly Address[]
+    binSteps: readonly bigint[]
+    versions: readonly number[]
+    amounts: readonly bigint[]
+  }
+  const amounts = q.amounts
+  const amountOut = amounts.length > 0 ? amounts[amounts.length - 1]! : 0n
+  if (amountOut === 0n) return null
+  return { route: q.route, binSteps: q.binSteps, versions: q.versions, amountOut }
+}
+
+export interface MoeSwapCalldata {
+  data: `0x${string}`
+  /** msg.value (native input only). */
+  value: bigint
+}
+
+/**
+ * Encode the LB router swap call. Picks the entrypoint by native in/out:
+ *  - native IN  -> swapExactNATIVEForTokens (msg.value = amountIn)
+ *  - native OUT -> swapExactTokensForNATIVE
+ *  - ERC-20 ↔ ERC-20 -> swapExactTokensForTokens
+ */
+export function encodeMoeSwap(opts: {
+  quote: MoeQuote
+  amountIn: bigint
+  amountOutMin: bigint
+  to: Address
+  deadline: bigint
+  nativeIn: boolean
+  nativeOut: boolean
+}): MoeSwapCalldata {
+  const { quote, amountIn, amountOutMin, to, deadline, nativeIn, nativeOut } = opts
+  const path = {
+    pairBinSteps: quote.binSteps as readonly bigint[],
+    versions: quote.versions as readonly number[],
+    tokenPath: quote.route as readonly Address[],
+  }
+  if (nativeIn) {
+    return {
+      data: encodeFunctionData({
+        abi: LB_ROUTER_ABI,
+        functionName: 'swapExactNATIVEForTokens',
+        args: [amountOutMin, path, to, deadline],
+      }),
+      value: amountIn,
+    }
+  }
+  if (nativeOut) {
+    return {
+      data: encodeFunctionData({
+        abi: LB_ROUTER_ABI,
+        functionName: 'swapExactTokensForNATIVE',
+        args: [amountIn, amountOutMin, path, to, deadline],
+      }),
+      value: 0n,
+    }
+  }
+  return {
+    data: encodeFunctionData({
+      abi: LB_ROUTER_ABI,
+      functionName: 'swapExactTokensForTokens',
+      args: [amountIn, amountOutMin, path, to, deadline],
+    }),
+    value: 0n,
+  }
+}

package/src/nansen.ts

@@ -0,0 +1,85 @@
+/**
+ * Nansen address-intelligence (read-only). Returns the entity labels Nansen
+ * has for an address — exchange / fund / smart-money / contract / and red-flag
+ * categories (scam, hack, sanctioned, mixer) — so the agent can vet a
+ * counterparty before transacting. Fits the "unified risk analysis" thesis.
+ *
+ * Auth: `apiKey` header (NANSEN_API_KEY, env only — never committed). Endpoints
+ * are credit-metered on Nansen's side; the tool surfaces a clear message when
+ * the key is unset or out of credits rather than failing hard.
+ */
+
+export const NANSEN_BASE = 'https://api.nansen.ai/api/v1'
+
+/** Label categories that should raise a counterparty flag. */
+const RED_FLAG_CATEGORIES = ['scam', 'hack', 'exploit', 'sanctioned', 'mixer', 'phish', 'fraud']
+
+export interface NansenLabel {
+  label: string
+  category: string
+}
+
+export interface NansenLabelsResult {
+  ok: boolean
+  /** Set when the call failed (missing key, no credits, HTTP error). */
+  error?: string
+  labels: NansenLabel[]
+}
+
+export async function fetchNansenLabels(opts: {
+  address: string
+  chain: string
+  apiKey: string
+  fetchImpl?: typeof fetch
+}): Promise<NansenLabelsResult> {
+  const { address, chain, apiKey, fetchImpl } = opts
+  const f = fetchImpl ?? fetch
+  let res: Response
+  try {
+    res = await f(`${NANSEN_BASE}/profiler/address/labels`, {
+      method: 'POST',
+      headers: { apiKey, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ address, chain }),
+    })
+  } catch (e) {
+    return {
+      ok: false,
+      error: `Nansen request failed: ${(e as Error).message.slice(0, 120)}`,
+      labels: [],
+    }
+  }
+  if (res.status === 403) {
+    const j = (await res.json().catch(() => ({}))) as { error?: string }
+    return {
+      ok: false,
+      error: j.error ?? 'Nansen 403 (out of credits or unauthorized)',
+      labels: [],
+    }
+  }
+  if (!res.ok) return { ok: false, error: `Nansen API ${res.status}`, labels: [] }
+  const j = (await res.json().catch(() => ({}))) as {
+    data?: Array<{ label?: string; category?: string }>
+  }
+  const labels = (j.data ?? []).map(l => ({
+    label: l.label ?? '?',
+    category: l.category ?? 'unknown',
+  }))
+  return { ok: true, labels }
+}
+
+/** Red-flag category names present in a label set (for a counterparty warning). */
+export function redFlags(labels: NansenLabel[]): string[] {
+  const cats = new Set<string>()
+  for (const l of labels) {
+    const c = l.category.toLowerCase()
+    if (RED_FLAG_CATEGORIES.some(rf => c.includes(rf))) cats.add(l.category)
+  }
+  return [...cats]
+}
+
+/** Distinct label categories, with counts, for a compact summary. */
+export function categorySummary(labels: NansenLabel[]): Record<string, number> {
+  const out: Record<string, number> = {}
+  for (const l of labels) out[l.category] = (out[l.category] ?? 0) + 1
+  return out
+}