@lendwise/mcp 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @lendwise/mcp
+
+MCP server for [Lendwise](https://lendwise.fi) — compare DeFi supply markets across **Aave V3**, **Morpho** and **Compound V3** on 27 standardized chains (~700 products, ~120 assets).
+
+It answers questions like *"I have $1,000 to place in DeFi for the next 6 months — what are the best markets?"* against real yield data, in about four tool calls.
+
+Read-only. It recommends; it never signs a transaction.
+
+## Install
+
+```jsonc
+// claude_desktop_config.json / .mcp.json
+{
+  "mcpServers": {
+    "lendwise": {
+      "command": "npx",
+      "args": ["-y", "@lendwise/mcp"]
+    }
+  }
+}
+```
+
+No API key. The server holds no secrets — it speaks only HTTPS to the public Lendwise API.
+
+## Tools
+
+| tool | what it's for |
+| --- | --- |
+| `list_market_universe` | Every asset, chain and protocol that actually exists, with counts. **Call this first** — it's what stops an agent guessing a filter value that isn't there. |
+| `find_best_markets` | Current supply markets ranked by net APY. Filtering and sorting happen server-side. Defaults to ≥ $1M TVL. |
+| `get_market_details` | One market in full: protocol metadata, collaterals, APY split into base / rewards / fees. |
+| `get_market_history` | Daily net-APY series **plus mean / stddev / min / max** — the stability signal a long horizon needs. |
+| `optimize_allocation` | Split an amount across markets at a target diversification. Returns per-market amounts, blended APY, projected 6-month yield. |
+
+### Why the TVL floor exists
+
+`find_best_markets` defaults to `minTvlUsd: 1_000_000`. In a thin market a headline APY is mostly noise, and steering someone with $1k into one is the most plausible real-world harm this server can do. Lower it deliberately, not by accident.
+
+### Why `get_market_history` returns statistics, not just a series
+
+A snapshot cannot tell a durable 6% from a 12% that is a reward programme ending next week. A 180-day standard deviation can. That is the number a 6-month decision actually turns on.
+
+## Configuration
+
+| env var | default | purpose |
+| --- | --- | --- |
+| `LENDWISE_API_URL` | `https://lendwise.fi` | Point at `http://localhost:3000` to develop against a local `lendwise/web`. |
+| `LENDWISE_INTEGRATION` | unset | Set to `1` to run the network integration tests. |
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test                                   # unit tests, hermetic
+LENDWISE_INTEGRATION=1 pnpm test            # + live API tests
+pnpm build
+```
+
+### The one invariant to not break
+
+The optimizer's contract is **positional**: we send `apy: number[]`, it returns `vault_index` — an offset into the array we sent, not an id. If the array we build and the array we map back through ever disagree, the server confidently attributes a real allocation to the *wrong market*, and every number still looks plausible.
+
+Order is therefore established exactly once, from the caller's `productIds`, and both directions run off that single array (`buildApyVector` → `mapAllocations` in `src/core/optimizer.ts`). It is pinned by unit tests in both directions. Do not "simplify" it into a lookup by APY value.
+
+## Rate limits
+
+The upstream API allows 60 GraphQL req/min/IP and 10 optimizer req/min/IP. A 429 is surfaced as an explicitly **retryable** error carrying `retryAfterSeconds` — back off, don't retry-storm.
+
+## Not financial advice
+
+Informational only. APYs are variable and historical yields do not predict future returns.
+
+## License
+
+MIT

package/dist/bin/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/stdio.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from '../core/server.js';
+/**
+ * stdio entrypoint — what `npx lendwise-mcp` runs.
+ *
+ * Nothing may be written to stdout except MCP protocol frames: stdout IS the
+ * transport. Diagnostics go to stderr.
+ */
+async function main() {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    console.error('lendwise-mcp ready on stdio');
+}
+main().catch((error) => {
+    console.error('lendwise-mcp failed to start:', error);
+    process.exit(1);
+});

package/dist/core/config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The MCP server holds no secrets. It speaks only HTTPS to the Lendwise public
+ * API, which is what makes this repo safe to be public — there is nothing here
+ * to leak. `LENDWISE_API_URL` is overridable so a local web checkout can be
+ * developed against.
+ */
+export declare const LENDWISE_API_URL: string;
+export declare const GRAPHQL_ENDPOINT: string;
+export declare const OPTIMIZER_ENDPOINT: string;
+/** Upstream is public and rate-limited; don't hang an agent on a slow request. */
+export declare const FETCH_TIMEOUT_MS = 15000;
+/**
+ * Below this TVL a headline APY is mostly noise. Steering someone with $1k into
+ * a thin market is the most plausible real-world harm this server can do, so the
+ * floor is on by default and must be lowered deliberately.
+ */
+export declare const DEFAULT_MIN_TVL_USD = 1000000;
+export declare const NOT_ADVICE: string;

package/dist/core/config.js

@@ -0,0 +1,19 @@
+/**
+ * The MCP server holds no secrets. It speaks only HTTPS to the Lendwise public
+ * API, which is what makes this repo safe to be public — there is nothing here
+ * to leak. `LENDWISE_API_URL` is overridable so a local web checkout can be
+ * developed against.
+ */
+export const LENDWISE_API_URL = (process.env.LENDWISE_API_URL ?? 'https://lendwise.fi').replace(/\/$/, '');
+export const GRAPHQL_ENDPOINT = `${LENDWISE_API_URL}/api/graphql`;
+export const OPTIMIZER_ENDPOINT = `${LENDWISE_API_URL}/api/optimizer`;
+/** Upstream is public and rate-limited; don't hang an agent on a slow request. */
+export const FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Below this TVL a headline APY is mostly noise. Steering someone with $1k into
+ * a thin market is the most plausible real-world harm this server can do, so the
+ * floor is on by default and must be lowered deliberately.
+ */
+export const DEFAULT_MIN_TVL_USD = 1_000_000;
+export const NOT_ADVICE = 'Informational only, not financial advice. APYs are variable and historical ' +
+    'yields do not predict future returns. Verify on-chain before committing funds.';

package/dist/core/graphql/client.d.ts

@@ -0,0 +1,3 @@
+export { ApiError, RateLimitedError } from '../http.js';
+/** POST a GraphQL document and return `data`, or throw a typed error. */
+export declare function gql<T>(query: string, variables?: Record<string, unknown>): Promise<T>;

package/dist/core/graphql/client.js

@@ -0,0 +1,14 @@
+import { GRAPHQL_ENDPOINT } from '../config.js';
+import { ApiError, postJson } from '../http.js';
+export { ApiError, RateLimitedError } from '../http.js';
+/** POST a GraphQL document and return `data`, or throw a typed error. */
+export async function gql(query, variables = {}) {
+    const body = await postJson(GRAPHQL_ENDPOINT, { query, variables }, 'The Lendwise API');
+    // GraphQL reports errors in a 200 body, so this is the real error path.
+    if (body.errors?.length) {
+        throw new ApiError(body.errors.map((e) => e.message).join('; '));
+    }
+    if (!body.data)
+        throw new ApiError('Lendwise API returned no data.');
+    return body.data;
+}

package/dist/core/graphql/queries.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The four documents the tools need.
+ *
+ * Written by hand rather than generated. The spec called for graphql-codegen
+ * against LENDWISE_API_URL introspection, but that makes a live endpoint a
+ * *build-time* dependency of a public package — and the queries these five tools
+ * need are a fixed, small set. `pnpm build` here needs no network.
+ *
+ * Selection sets are kept tight on purpose: the API enforces a query cost limit
+ * that scales with `first`, so asking for fields we won't render can push a
+ * large page over the ceiling.
+ */
+export interface ApyBreakdown {
+    base: number;
+    rewards: number;
+    fees: number;
+    net: number;
+    rewardItems?: RewardItem[];
+}
+export interface RewardItem {
+    token: {
+        symbol: string;
+    };
+    apy: number;
+    source: string;
+    program: string | null;
+}
+export interface MarketState {
+    supplyAssetsUsd: number | null;
+    utilizationRate: number | null;
+}
+export interface Quality {
+    status: string;
+    count: number;
+    expectedCount: number;
+}
+export interface SnapshotRow {
+    hour: string;
+    productId: string;
+    asset: string;
+    chainId: number;
+    apy: ApyBreakdown;
+    market: MarketState;
+    quality: Quality;
+    product: {
+        protocol: {
+            provider: string;
+            name: string;
+            chain: {
+                id: number;
+                name: string;
+            };
+        };
+    } | null;
+}
+export interface SnapshotResponse {
+    items: SnapshotRow[];
+    pagination: {
+        count: number;
+        countTotal: number;
+        limit: number;
+        skip: number;
+    };
+}
+export interface DailyRow {
+    date: string;
+    apy: {
+        net: number;
+        base: number;
+        rewards: number;
+    };
+}
+export interface FacetsResponse {
+    assets: {
+        symbol: string;
+        count: number;
+    }[];
+    chains: {
+        id: number;
+        name: string;
+        count: number;
+    }[];
+    protocols: {
+        name: string;
+        count: number;
+    }[];
+}
+export interface ProductRow {
+    id: string;
+    kind: string;
+    asset: {
+        symbol: string;
+        name: string;
+        address: string;
+        decimals: number;
+    };
+    protocol: {
+        provider: string;
+        type: string;
+        version: string;
+        name: string;
+        chain: {
+            id: number;
+            name: string;
+        };
+        address: string;
+        meta: unknown;
+    };
+    collaterals: {
+        symbol: string;
+        name: string;
+        ltv: number | null;
+        lltv: number;
+        canBeCollateral: boolean;
+    }[] | null;
+}
+export declare const PRODUCT_FACETS = "\n  query ProductFacets($filters: ProductFilters) {\n    productFacets(filters: $filters) {\n      assets {\n        symbol\n        count\n      }\n      chains {\n        id\n        name\n        count\n      }\n      protocols {\n        name\n        count\n      }\n    }\n  }\n";
+export declare const LATEST_SUPPLY_APY = "\n  query LatestSupplyApy($filters: LatestFilters, $first: Int) {\n    latestSupplyApy(\n      filters: $filters\n      first: $first\n      orderBy: apyNet\n      orderDirection: desc\n    ) {\n      \n  items {\n    hour\n    productId\n    asset\n    chainId\n    apy {\n      base\n      rewards\n      fees\n      net\n    }\n    market {\n      supplyAssetsUsd\n      utilizationRate\n    }\n    quality {\n      status\n      count\n      expectedCount\n    }\n    product {\n      protocol {\n        provider\n        name\n        chain {\n          id\n          name\n        }\n      }\n    }\n  }\n  pagination {\n    count\n    countTotal\n    limit\n    skip\n  }\n\n    }\n  }\n";
+/**
+ * Latest snapshot for an explicit set of products — the optimizer's APY source.
+ *
+ * One request for the whole batch via the server-side `productIds` filter. One
+ * request per product would burn up to 20 of the 60 req/min budget on a single
+ * optimize_allocation call.
+ */
+export declare const LATEST_SUPPLY_BY_PRODUCTS = "\n  query LatestSupplyByProducts($productIds: [String!], $first: Int) {\n    latestSupplyApy(filters: { productIds: $productIds }, first: $first) {\n      \n  items {\n    hour\n    productId\n    asset\n    chainId\n    apy {\n      base\n      rewards\n      fees\n      net\n    }\n    market {\n      supplyAssetsUsd\n      utilizationRate\n    }\n    quality {\n      status\n      count\n      expectedCount\n    }\n    product {\n      protocol {\n        provider\n        name\n        chain {\n          id\n          name\n        }\n      }\n    }\n  }\n  pagination {\n    count\n    countTotal\n    limit\n    skip\n  }\n\n    }\n  }\n";
+/**
+ * A productId identifies a supply OR a borrow product, and the two live in
+ * different snapshot queries. Ask both and take whichever answers: querying only
+ * the supply side would report every healthy borrow market as a stalled pipeline.
+ */
+export declare const MARKET_DETAILS = "\n  query MarketDetails($productId: String!) {\n    products(filters: { productId: $productId }, first: 1) {\n      items {\n        id\n        kind\n        asset {\n          symbol\n          name\n          address\n          decimals\n        }\n        protocol {\n          provider\n          type\n          version\n          name\n          chain {\n            id\n            name\n          }\n          address\n          meta\n        }\n        collaterals {\n          symbol\n          name\n          ltv\n          lltv\n          canBeCollateral\n        }\n      }\n    }\n    latestSupplyApy(filters: { productId: $productId }, first: 1) {\n      \n  items {\n    hour\n    productId\n    asset\n    chainId\n    apy {\n      base\n      rewards\n      fees\n      net\n      rewardItems {\n        token {\n          symbol\n        }\n        apy\n        source\n        program\n      }\n    }\n    market {\n      supplyAssetsUsd\n      utilizationRate\n    }\n    quality {\n      status\n      count\n      expectedCount\n    }\n    product {\n      protocol {\n        provider\n        name\n        chain {\n          id\n          name\n        }\n      }\n    }\n  }\n\n    }\n    latestBorrowApy(filters: { productId: $productId }, first: 1) {\n      \n  items {\n    hour\n    productId\n    asset\n    chainId\n    apy {\n      base\n      rewards\n      fees\n      net\n      rewardItems {\n        token {\n          symbol\n        }\n        apy\n        source\n        program\n      }\n    }\n    market {\n      supplyAssetsUsd\n      utilizationRate\n    }\n    quality {\n      status\n      count\n      expectedCount\n    }\n    product {\n      protocol {\n        provider\n        name\n        chain {\n          id\n          name\n        }\n      }\n    }\n  }\n\n    }\n  }\n";
+export declare const MARKET_HISTORY = "\n  query MarketHistory($productId: String!, $range: String!) {\n    supplyApyDaily(\n      filters: { productId: $productId, range: $range }\n      first: 500\n      orderBy: time\n      orderDirection: asc\n    ) {\n      items {\n        date\n        apy {\n          net\n          base\n          rewards\n        }\n      }\n      pagination {\n        count\n        countTotal\n      }\n    }\n  }\n";

package/dist/core/graphql/queries.js

@@ -0,0 +1,207 @@
+/**
+ * The four documents the tools need.
+ *
+ * Written by hand rather than generated. The spec called for graphql-codegen
+ * against LENDWISE_API_URL introspection, but that makes a live endpoint a
+ * *build-time* dependency of a public package — and the queries these five tools
+ * need are a fixed, small set. `pnpm build` here needs no network.
+ *
+ * Selection sets are kept tight on purpose: the API enforces a query cost limit
+ * that scales with `first`, so asking for fields we won't render can push a
+ * large page over the ceiling.
+ */
+// ─── Documents ───────────────────────────────────────────────────────────────
+export const PRODUCT_FACETS = /* GraphQL */ `
+  query ProductFacets($filters: ProductFilters) {
+    productFacets(filters: $filters) {
+      assets {
+        symbol
+        count
+      }
+      chains {
+        id
+        name
+        count
+      }
+      protocols {
+        name
+        count
+      }
+    }
+  }
+`;
+const SNAPSHOT_FIELDS = /* GraphQL */ `
+  items {
+    hour
+    productId
+    asset
+    chainId
+    apy {
+      base
+      rewards
+      fees
+      net
+    }
+    market {
+      supplyAssetsUsd
+      utilizationRate
+    }
+    quality {
+      status
+      count
+      expectedCount
+    }
+    product {
+      protocol {
+        provider
+        name
+        chain {
+          id
+          name
+        }
+      }
+    }
+  }
+  pagination {
+    count
+    countTotal
+    limit
+    skip
+  }
+`;
+export const LATEST_SUPPLY_APY = /* GraphQL */ `
+  query LatestSupplyApy($filters: LatestFilters, $first: Int) {
+    latestSupplyApy(
+      filters: $filters
+      first: $first
+      orderBy: apyNet
+      orderDirection: desc
+    ) {
+      ${SNAPSHOT_FIELDS}
+    }
+  }
+`;
+/**
+ * Latest snapshot for an explicit set of products — the optimizer's APY source.
+ *
+ * One request for the whole batch via the server-side `productIds` filter. One
+ * request per product would burn up to 20 of the 60 req/min budget on a single
+ * optimize_allocation call.
+ */
+export const LATEST_SUPPLY_BY_PRODUCTS = /* GraphQL */ `
+  query LatestSupplyByProducts($productIds: [String!], $first: Int) {
+    latestSupplyApy(filters: { productIds: $productIds }, first: $first) {
+      ${SNAPSHOT_FIELDS}
+    }
+  }
+`;
+const DETAIL_SNAPSHOT_FIELDS = /* GraphQL */ `
+  items {
+    hour
+    productId
+    asset
+    chainId
+    apy {
+      base
+      rewards
+      fees
+      net
+      rewardItems {
+        token {
+          symbol
+        }
+        apy
+        source
+        program
+      }
+    }
+    market {
+      supplyAssetsUsd
+      utilizationRate
+    }
+    quality {
+      status
+      count
+      expectedCount
+    }
+    product {
+      protocol {
+        provider
+        name
+        chain {
+          id
+          name
+        }
+      }
+    }
+  }
+`;
+/**
+ * A productId identifies a supply OR a borrow product, and the two live in
+ * different snapshot queries. Ask both and take whichever answers: querying only
+ * the supply side would report every healthy borrow market as a stalled pipeline.
+ */
+export const MARKET_DETAILS = /* GraphQL */ `
+  query MarketDetails($productId: String!) {
+    products(filters: { productId: $productId }, first: 1) {
+      items {
+        id
+        kind
+        asset {
+          symbol
+          name
+          address
+          decimals
+        }
+        protocol {
+          provider
+          type
+          version
+          name
+          chain {
+            id
+            name
+          }
+          address
+          meta
+        }
+        collaterals {
+          symbol
+          name
+          ltv
+          lltv
+          canBeCollateral
+        }
+      }
+    }
+    latestSupplyApy(filters: { productId: $productId }, first: 1) {
+      ${DETAIL_SNAPSHOT_FIELDS}
+    }
+    latestBorrowApy(filters: { productId: $productId }, first: 1) {
+      ${DETAIL_SNAPSHOT_FIELDS}
+    }
+  }
+`;
+export const MARKET_HISTORY = /* GraphQL */ `
+  query MarketHistory($productId: String!, $range: String!) {
+    supplyApyDaily(
+      filters: { productId: $productId, range: $range }
+      first: 500
+      orderBy: time
+      orderDirection: asc
+    ) {
+      items {
+        date
+        apy {
+          net
+          base
+          rewards
+        }
+      }
+      pagination {
+        count
+        countTotal
+      }
+    }
+  }
+`;

package/dist/core/http.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A 429 from upstream. Surfaced as its own error type rather than swallowed:
+ * the agent must back off, not retry-storm the endpoint the rate limit exists to
+ * protect.
+ */
+export declare class RateLimitedError extends Error {
+    readonly retryAfterSeconds: number;
+    constructor(retryAfterSeconds: number);
+}
+export declare class ApiError extends Error {
+    constructor(message: string);
+}
+/**
+ * POST JSON and return the parsed body.
+ *
+ * The single network path for this server: the GraphQL client and the optimizer
+ * client both go through it, so timeout handling, 429 semantics and error
+ * shaping cannot drift apart between them.
+ */
+export declare function postJson<T>(url: string, body: unknown, label: string): Promise<T>;

package/dist/core/http.js

@@ -0,0 +1,72 @@
+import { FETCH_TIMEOUT_MS } from './config.js';
+/**
+ * A 429 from upstream. Surfaced as its own error type rather than swallowed:
+ * the agent must back off, not retry-storm the endpoint the rate limit exists to
+ * protect.
+ */
+export class RateLimitedError extends Error {
+    retryAfterSeconds;
+    constructor(retryAfterSeconds) {
+        super(`Lendwise API rate limit exceeded. Retryable: wait ${retryAfterSeconds}s ` +
+            `before trying again. Do not retry immediately.`);
+        this.name = 'RateLimitedError';
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class ApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApiError';
+    }
+}
+/** Default back-off when upstream sends a 429 without a usable Retry-After. */
+const DEFAULT_RETRY_AFTER_SECONDS = 60;
+/**
+ * POST JSON and return the parsed body.
+ *
+ * The single network path for this server: the GraphQL client and the optimizer
+ * client both go through it, so timeout handling, 429 semantics and error
+ * shaping cannot drift apart between them.
+ */
+export async function postJson(url, body, label) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new ApiError(`${label} did not respond within ${FETCH_TIMEOUT_MS / 1000}s.`);
+        }
+        throw new ApiError(`Could not reach ${label}: ${error.message}`);
+    }
+    if (response.status === 429) {
+        const header = Number(response.headers.get('retry-after'));
+        throw new RateLimitedError(Number.isFinite(header) && header > 0 ? header : DEFAULT_RETRY_AFTER_SECONDS);
+    }
+    const raw = await response.text();
+    if (!response.ok) {
+        // A dead or misrouted upstream answers with HTML, not JSON. Parse only if it
+        // parses, so the real status is never masked by a JSON SyntaxError.
+        let detail = raw.slice(0, 200);
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.error)
+                detail = parsed.error;
+        }
+        catch {
+            /* not JSON — fall back to the raw text */
+        }
+        throw new ApiError(`${label} returned HTTP ${response.status}: ${detail}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new ApiError(`${label} returned a non-JSON response.`);
+    }
+}

package/dist/core/optimizer.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The optimizer contract is POSITIONAL, and that is the single most dangerous
+ * detail in this server.
+ *
+ * We send `apy: number[]`. It answers with `vault_index` — an offset into the
+ * array we sent, not an id. If the array we build and the array we map back
+ * through ever disagree on order, the agent confidently recommends a real
+ * allocation attached to the wrong market. Nothing downstream would catch it:
+ * the numbers all look plausible.
+ *
+ * So order is established exactly once, by the caller's productIds, and both
+ * directions are driven from that same array. See optimizer.test.ts.
+ */
+export interface VaultAllocationResult {
+    vault_index: number;
+    allocation: number;
+    allocation_percent: number;
+}
+export interface VaultAllocationResponse {
+    success: boolean;
+    allocations: VaultAllocationResult[];
+    resulting_diversification: number;
+}
+/** One market's share of the allocation, resolved back to its productId. */
+export interface Allocation {
+    productId: string;
+    apy: number;
+    allocationPercent: number;
+    amountUsd: number;
+}
+/**
+ * Map the solver's positional result back onto the productIds it was built
+ * from. `apys[i]` must be the APY of `productIds[i]` — that invariant is the
+ * caller's to hold, and `buildApyVector` is the only supported way to get it.
+ */
+export declare function mapAllocations(productIds: readonly string[], apys: readonly number[], allocations: readonly VaultAllocationResult[], amountUsd: number): Allocation[];
+/**
+ * Build the positional APY vector for `productIds`, in that exact order.
+ * Products with no finite APY in the snapshot are reported as missing rather
+ * than defaulted to 0 — a 0 would silently tell the solver "this market is
+ * worthless" instead of "we don't know".
+ */
+export declare function buildApyVector(productIds: readonly string[], latestApyByProduct: ReadonlyMap<string, number>): {
+    apys: number[];
+    found: string[];
+    missing: string[];
+};
+/** Blended APY of an allocation — the portfolio's weighted mean. */
+export declare function blendedApy(allocations: readonly Allocation[]): number;
+/**
+ * Call the solver through the Lendwise proxy — never optimizer.lendwise.fi directly.
+ *
+ * The response is VALIDATED, not cast. A solver that answers 200 with
+ * `success: false` (or without `allocations` at all) would otherwise blow up
+ * inside `mapAllocations`, or — worse — be reported to the user as a valid
+ * allocation of $0 across their markets.
+ */
+export declare function optimizeVaults(apy: readonly number[], diversification: number): Promise<VaultAllocationResponse>;