@dexterai/x402 2.0.0 → 3.0.0

package/dist/client/index.d.cts

@@ -1,9 +1,9 @@
-export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-BgEDLg_H.cjs';
-import { A as AccessPassClientConfig, P as PaymentAccept } from '../types-CjLMR7qs.cjs';
-export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-CjLMR7qs.cjs';
+export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-CE7WpV5b.cjs';
+import { A as AccessPassClientConfig, P as PaymentAccept } from '../types-_iT11DL0.cjs';
+export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-_iT11DL0.cjs';
 import { Keypair } from '@solana/web3.js';
-import { S as SolanaWallet, E as EvmWallet } from '../types-DWhpiOBD.cjs';
-export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-DWhpiOBD.cjs';
+import { S as SolanaWallet, E as EvmWallet } from '../types-C_aQh02s.cjs';
+export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-C_aQh02s.cjs';
 export { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
 
 /**
@@ -238,105 +238,226 @@ declare function createEvmKeypairWallet(privateKey: string): Promise<EvmWallet>;
 declare function isEvmKeypairWallet(wallet: unknown): wallet is EvmWallet;
 
 /**
- * API Discovery — Find x402 Paid APIs
+ * API Discovery — Semantic Capability Search
  *
- * Search the Dexter marketplace for x402-enabled APIs. Discover endpoints
- * by category, price range, network, and quality score — then pay for them
- * with the same SDK.
+ * Search the Dexter x402 marketplace for paid APIs using semantic capability
+ * search. Queries are embedded with a vector model, filtered by a similarity
+ * floor, split into strong and related tiers, and the top strong results are
+ * reordered by an LLM cross-encoder. Synonym expansion and alternate phrasing
+ * handling happen automatically inside the search backend — pass a natural-
+ * language query and let the ranker do the work.
  *
  * @example
  * ```typescript
- * import { searchAPIs } from '@dexterai/x402/client';
+ * import { capabilitySearch } from '@dexterai/x402/client';
  *
- * const results = await searchAPIs({ query: 'sentiment analysis', maxPrice: 0.10 });
- * for (const api of results) {
- *   console.log(`${api.name}: ${api.price} — ${api.description}`);
+ * const result = await capabilitySearch({ query: 'get ETH spot price' });
+ *
+ * // Strong matches: high-confidence capability hits
+ * for (const api of result.strongResults) {
+ *   console.log(`${api.name} (${api.tier}, similarity ${api.similarity}): ${api.why}`);
+ * }
+ *
+ * // Related matches: adjacent services that cleared the similarity floor
+ * // but not the strong threshold. Useful as a fallback when strongResults
+ * // is empty or sparse.
+ * for (const api of result.relatedResults) {
+ *   console.log(`${api.name} (related): ${api.description}`);
  * }
  *
  * // Then call one with wrapFetch:
- * const response = await x402Fetch(results[0].url);
+ * const response = await x402Fetch(result.strongResults[0].url);
  * ```
+ *
+ * @breaking 3.0.0
+ * This module was rewritten to target the capability search endpoint at
+ * `/api/x402gle/capability` instead of the legacy substring ranker at
+ * `/api/facilitator/marketplace/resources`. The old `searchAPIs()` function
+ * and `DiscoveredAPI` type have been removed — replaced by `capabilitySearch()`
+ * and `CapabilityAPI`. The response is now tiered (strongResults/relatedResults)
+ * and each result carries `tier`, `similarity`, and `why` explainers. Filter
+ * parameters like `category`, `network`, `maxPrice`, `verifiedOnly`, and `sort`
+ * are gone — the ranker handles these semantically rather than as hard filters.
  */
 /**
- * Search options for discovering x402 APIs
+ * Options for semantic capability search.
+ *
+ * The new pipeline does NOT accept the old hard-filter params (`category`,
+ * `network`, `maxPrice`, `verifiedOnly`, `sort`). Those were removed in 3.0.0
+ * because they were the source of silent false-empties: e.g. a query for
+ * "ETH price" on `network: 'ethereum'` would return zero results because
+ * every ETH-price resource accepts payment on Base (Ethereum gas is too
+ * expensive). Search ranks by capability relevance; payment rail is a
+ * checkout-time concern the caller handles separately.
  */
-interface SearchAPIsOptions {
-    /** Search query (e.g., 'sentiment analysis', 'token price', 'image generation') */
-    query?: string;
-    /** Filter by category (e.g., 'defi', 'ai', 'data', 'social') */
-    category?: string;
-    /** Filter by payment network (e.g., 'solana', 'base', 'polygon') */
-    network?: string;
-    /** Maximum price per call in USDC */
-    maxPrice?: number;
-    /** Only return verified endpoints (quality score 75+) */
-    verifiedOnly?: boolean;
-    /** Sort order */
-    sort?: 'marketplace' | 'relevance' | 'quality_score' | 'settlements' | 'volume' | 'recent';
-    /** Maximum results to return (default 20, max 50) */
+interface CapabilitySearchOptions {
+    /** Natural-language description of the capability you want. Required. */
+    query: string;
+    /** Max results across strong + related tiers combined (1-50, default 20) */
     limit?: number;
-    /** Marketplace API URL (default: Dexter marketplace) */
-    marketplaceUrl?: string;
+    /** Include unverified resources (default false) */
+    unverified?: boolean;
+    /** Include testnet-only resources (default false) */
+    testnets?: boolean;
+    /**
+     * Cross-encoder LLM rerank of the top strong results. Default true.
+     * Adds ~1s of latency in exchange for meaningfully better top-of-list
+     * ordering on ambiguous queries. Set to false for deterministic order
+     * or lowest-latency path.
+     */
+    rerank?: boolean;
+    /**
+     * Override the capability search endpoint. Defaults to the Dexter-hosted
+     * endpoint. Useful for testing against a local dexter-api instance.
+     */
+    endpoint?: string;
 }
 /**
- * A discovered x402 API endpoint
+ * A single result from capability search.
+ *
+ * Fields are flat-ish and designed to round-trip cleanly through LLM tool
+ * outputs and UI renderers. `tier`, `similarity`, and `why` are the three
+ * new fields that the ranker produces: use them to distinguish high-confidence
+ * matches from related suggestions.
  */
-interface DiscoveredAPI {
-    /** API name */
+interface CapabilityAPI {
+    /** Internal resource UUID in the Dexter catalog */
+    resourceId: string;
+    /** Display name (falls back to the URL if the resource is unnamed) */
     name: string;
     /** Full resource URL — pass directly to wrapFetch or createX402Client.fetch */
     url: string;
-    /** HTTP method */
+    /** HTTP method the endpoint expects */
     method: string;
-    /** Price per call (formatted, e.g., '$0.05') */
+    /**
+     * Formatted price label ("$0.05", "$0.0011", "free", or "price on request"
+     * when the resource has no advertised price).
+     */
     price: string;
-    /** Price per call in USDC (raw number, null if free) */
+    /** Raw price in USDC as a number (null when the resource has no advertised price) */
     priceUsdc: number | null;
-    /** Payment network */
+    /** Payment network the price is quoted on (CAIP-2 or canonical name) */
     network: string | null;
     /** Human-readable description */
     description: string;
-    /** Category (e.g., 'defi', 'ai', 'data') */
+    /** Category assigned by the catalog */
     category: string;
-    /** Quality score (0-100, null if unscored) */
+    /** Quality score 0-100 (null if unscored) */
     qualityScore: number | null;
-    /** Whether the endpoint has been verified */
+    /** Whether the endpoint passed AI verification (alias for verificationStatus === 'pass') */
     verified: boolean;
-    /** Total number of settlements (calls) */
+    /** Full verification status: 'pass' | 'fail' | 'inconclusive' | 'skipped' | 'unverified' */
+    verificationStatus: string;
+    /** Total number of settlements (calls) observed against this resource */
     totalCalls: number;
-    /** Total volume in USDC (formatted, e.g., '$1,234.56') */
-    totalVolume: string | null;
-    /** Seller name */
-    seller: string | null;
-    /** Seller reputation score */
-    sellerReputation: number | null;
-    /** Whether authentication is required beyond payment */
-    authRequired: boolean;
-    /** Last time someone called this API */
-    lastActive: string | null;
+    /** Total settled volume in USDC */
+    totalVolumeUsdc: number;
+    /** Icon URL (favicon or seller logo) */
+    iconUrl: string | null;
+    /** Host label derived from the URL */
+    host: string | null;
+    /** Gaming/wash-trading flags — non-empty array means the resource is suspicious */
+    gamingFlags: string[];
+    /** True when any gaming flag is set */
+    gamingSuspicious: boolean;
+    /** Which tier this result fell into — 'strong' (high confidence) or 'related' (adjacent) */
+    tier: 'strong' | 'related';
+    /** Raw cosine similarity 0-1 between the query embedding and the resource embedding */
+    similarity: number;
+    /**
+     * One-sentence explanation of why this result ranked where it did. Built
+     * from the modular ranking factors (semantic similarity, trust, activity,
+     * gaming penalty).
+     */
+    why: string;
+    /** Final combined ranking score in [0, 1] */
+    score: number;
 }
 /**
- * Search the Dexter marketplace for x402 paid APIs.
+ * Why a response has no strong matches.
+ * - 'below_similarity_threshold': no candidates cleared the similarity floor at all
+ * - 'below_strong_threshold': candidates cleared the floor but none reached strong
+ * - null: strongResults is non-empty
+ */
+type NoMatchReason = 'below_similarity_threshold' | 'below_strong_threshold' | null;
+/**
+ * Full response from capability search. Tiered shape with telemetry about
+ * the ranking pipeline.
+ */
+interface CapabilitySearchResult {
+    /** The original query string the caller passed */
+    query: string;
+    /**
+     * Strong matches — high-confidence capability hits (similarity >= strong
+     * threshold). These are the primary results the caller should surface.
+     */
+    strongResults: CapabilityAPI[];
+    /**
+     * Related matches — candidates that cleared the similarity floor but did
+     * not reach the strong threshold. Useful as a secondary section when
+     * strongResults is empty or sparse.
+     */
+    relatedResults: CapabilityAPI[];
+    /** Count of strong results returned */
+    strongCount: number;
+    /** Count of related results returned */
+    relatedCount: number;
+    /** Highest cosine similarity observed across all candidates (null when no candidates) */
+    topSimilarity: number | null;
+    /** Reason the response has no strong matches (null when strong matches exist) */
+    noMatchReason: NoMatchReason;
+    /**
+     * Cross-encoder rerank telemetry. `applied` is true when the LLM actually
+     * reordered the top strong results; `reason` explains any skip.
+     */
+    rerank: {
+        enabled: boolean;
+        applied: boolean;
+        reason?: string;
+    };
+    /**
+     * The parsed intent the backend extracted. `capabilityText` is the bare
+     * capability; `expandedCapabilityText` is the synonym-expanded version that
+     * was actually embedded for the vector search.
+     */
+    intent: {
+        capabilityText: string;
+        expandedCapabilityText?: string;
+    };
+    /** Total wall-clock duration of the capability search request in milliseconds */
+    durationMs: number;
+}
+/**
+ * Search the Dexter x402 marketplace using semantic capability search.
  *
- * Returns a list of discovered endpoints that can be called directly
- * with `wrapFetch` or `createX402Client.fetch`.
+ * Returns tiered results (strongResults + relatedResults) plus ranking
+ * telemetry. Handles synonym expansion and cross-encoder LLM rerank
+ * internally — pass the user's natural-language intent directly.
  *
- * @example Find AI APIs under $0.10
+ * @example Find an ETH price feed
  * ```typescript
- * const apis = await searchAPIs({ query: 'ai', maxPrice: 0.10 });
+ * const result = await capabilitySearch({ query: 'get current ETH spot price' });
+ * if (result.strongCount > 0) {
+ *   const best = result.strongResults[0];
+ *   console.log(`${best.name}: ${best.price} — ${best.why}`);
+ * } else if (result.relatedCount > 0) {
+ *   console.log(`No exact match. Closest related: ${result.relatedResults[0].name}`);
+ * } else {
+ *   console.log(`No match. Reason: ${result.noMatchReason}`);
+ * }
  * ```
  *
- * @example Browse all verified DeFi tools
+ * @example Skip the LLM rerank for lowest latency
  * ```typescript
- * const apis = await searchAPIs({ category: 'defi', verifiedOnly: true });
+ * const result = await capabilitySearch({ query: 'token price', rerank: false });
  * ```
  *
- * @example Find cheapest APIs on Solana
+ * @example Include unverified resources (usually omitted)
  * ```typescript
- * const apis = await searchAPIs({ network: 'solana', sort: 'quality_score' });
+ * const result = await capabilitySearch({ query: 'image generation', unverified: true });
  * ```
  */
-declare function searchAPIs(options?: SearchAPIsOptions): Promise<DiscoveredAPI[]>;
+declare function capabilitySearch(options: CapabilitySearchOptions): Promise<CapabilitySearchResult>;
 
 /**
  * Budget Account — Autonomous Agent Spending Controls
@@ -423,4 +544,4 @@ interface BudgetAccount {
  */
 declare function createBudgetAccount(config: BudgetAccountConfig): BudgetAccount;
 
-export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type DiscoveredAPI, KEYPAIR_SYMBOL, type KeypairWallet, type PaymentRecord, type SearchAPIsOptions, type WrapFetchOptions, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, searchAPIs, wrapFetch };
+export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type CapabilityAPI, type CapabilitySearchOptions, type CapabilitySearchResult, KEYPAIR_SYMBOL, type KeypairWallet, type NoMatchReason, type PaymentRecord, type WrapFetchOptions, capabilitySearch, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };

package/dist/client/index.d.ts

@@ -1,9 +1,9 @@
-export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-DjLEKhOV.js';
-import { A as AccessPassClientConfig, P as PaymentAccept } from '../types-CjLMR7qs.js';
-export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-CjLMR7qs.js';
+export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-BVoucsEW.js';
+import { A as AccessPassClientConfig, P as PaymentAccept } from '../types-_iT11DL0.js';
+export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-_iT11DL0.js';
 import { Keypair } from '@solana/web3.js';
-import { S as SolanaWallet, E as EvmWallet } from '../types-D1TGACsL.js';
-export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-D1TGACsL.js';
+import { S as SolanaWallet, E as EvmWallet } from '../types-DBS0XOsH.js';
+export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-DBS0XOsH.js';
 export { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
 
 /**
@@ -238,105 +238,226 @@ declare function createEvmKeypairWallet(privateKey: string): Promise<EvmWallet>;
 declare function isEvmKeypairWallet(wallet: unknown): wallet is EvmWallet;
 
 /**
- * API Discovery — Find x402 Paid APIs
+ * API Discovery — Semantic Capability Search
  *
- * Search the Dexter marketplace for x402-enabled APIs. Discover endpoints
- * by category, price range, network, and quality score — then pay for them
- * with the same SDK.
+ * Search the Dexter x402 marketplace for paid APIs using semantic capability
+ * search. Queries are embedded with a vector model, filtered by a similarity
+ * floor, split into strong and related tiers, and the top strong results are
+ * reordered by an LLM cross-encoder. Synonym expansion and alternate phrasing
+ * handling happen automatically inside the search backend — pass a natural-
+ * language query and let the ranker do the work.
  *
  * @example
  * ```typescript
- * import { searchAPIs } from '@dexterai/x402/client';
+ * import { capabilitySearch } from '@dexterai/x402/client';
  *
- * const results = await searchAPIs({ query: 'sentiment analysis', maxPrice: 0.10 });
- * for (const api of results) {
- *   console.log(`${api.name}: ${api.price} — ${api.description}`);
+ * const result = await capabilitySearch({ query: 'get ETH spot price' });
+ *
+ * // Strong matches: high-confidence capability hits
+ * for (const api of result.strongResults) {
+ *   console.log(`${api.name} (${api.tier}, similarity ${api.similarity}): ${api.why}`);
+ * }
+ *
+ * // Related matches: adjacent services that cleared the similarity floor
+ * // but not the strong threshold. Useful as a fallback when strongResults
+ * // is empty or sparse.
+ * for (const api of result.relatedResults) {
+ *   console.log(`${api.name} (related): ${api.description}`);
  * }
  *
  * // Then call one with wrapFetch:
- * const response = await x402Fetch(results[0].url);
+ * const response = await x402Fetch(result.strongResults[0].url);
  * ```
+ *
+ * @breaking 3.0.0
+ * This module was rewritten to target the capability search endpoint at
+ * `/api/x402gle/capability` instead of the legacy substring ranker at
+ * `/api/facilitator/marketplace/resources`. The old `searchAPIs()` function
+ * and `DiscoveredAPI` type have been removed — replaced by `capabilitySearch()`
+ * and `CapabilityAPI`. The response is now tiered (strongResults/relatedResults)
+ * and each result carries `tier`, `similarity`, and `why` explainers. Filter
+ * parameters like `category`, `network`, `maxPrice`, `verifiedOnly`, and `sort`
+ * are gone — the ranker handles these semantically rather than as hard filters.
  */
 /**
- * Search options for discovering x402 APIs
+ * Options for semantic capability search.
+ *
+ * The new pipeline does NOT accept the old hard-filter params (`category`,
+ * `network`, `maxPrice`, `verifiedOnly`, `sort`). Those were removed in 3.0.0
+ * because they were the source of silent false-empties: e.g. a query for
+ * "ETH price" on `network: 'ethereum'` would return zero results because
+ * every ETH-price resource accepts payment on Base (Ethereum gas is too
+ * expensive). Search ranks by capability relevance; payment rail is a
+ * checkout-time concern the caller handles separately.
  */
-interface SearchAPIsOptions {
-    /** Search query (e.g., 'sentiment analysis', 'token price', 'image generation') */
-    query?: string;
-    /** Filter by category (e.g., 'defi', 'ai', 'data', 'social') */
-    category?: string;
-    /** Filter by payment network (e.g., 'solana', 'base', 'polygon') */
-    network?: string;
-    /** Maximum price per call in USDC */
-    maxPrice?: number;
-    /** Only return verified endpoints (quality score 75+) */
-    verifiedOnly?: boolean;
-    /** Sort order */
-    sort?: 'marketplace' | 'relevance' | 'quality_score' | 'settlements' | 'volume' | 'recent';
-    /** Maximum results to return (default 20, max 50) */
+interface CapabilitySearchOptions {
+    /** Natural-language description of the capability you want. Required. */
+    query: string;
+    /** Max results across strong + related tiers combined (1-50, default 20) */
     limit?: number;
-    /** Marketplace API URL (default: Dexter marketplace) */
-    marketplaceUrl?: string;
+    /** Include unverified resources (default false) */
+    unverified?: boolean;
+    /** Include testnet-only resources (default false) */
+    testnets?: boolean;
+    /**
+     * Cross-encoder LLM rerank of the top strong results. Default true.
+     * Adds ~1s of latency in exchange for meaningfully better top-of-list
+     * ordering on ambiguous queries. Set to false for deterministic order
+     * or lowest-latency path.
+     */
+    rerank?: boolean;
+    /**
+     * Override the capability search endpoint. Defaults to the Dexter-hosted
+     * endpoint. Useful for testing against a local dexter-api instance.
+     */
+    endpoint?: string;
 }
 /**
- * A discovered x402 API endpoint
+ * A single result from capability search.
+ *
+ * Fields are flat-ish and designed to round-trip cleanly through LLM tool
+ * outputs and UI renderers. `tier`, `similarity`, and `why` are the three
+ * new fields that the ranker produces: use them to distinguish high-confidence
+ * matches from related suggestions.
  */
-interface DiscoveredAPI {
-    /** API name */
+interface CapabilityAPI {
+    /** Internal resource UUID in the Dexter catalog */
+    resourceId: string;
+    /** Display name (falls back to the URL if the resource is unnamed) */
     name: string;
     /** Full resource URL — pass directly to wrapFetch or createX402Client.fetch */
     url: string;
-    /** HTTP method */
+    /** HTTP method the endpoint expects */
     method: string;
-    /** Price per call (formatted, e.g., '$0.05') */
+    /**
+     * Formatted price label ("$0.05", "$0.0011", "free", or "price on request"
+     * when the resource has no advertised price).
+     */
     price: string;
-    /** Price per call in USDC (raw number, null if free) */
+    /** Raw price in USDC as a number (null when the resource has no advertised price) */
     priceUsdc: number | null;
-    /** Payment network */
+    /** Payment network the price is quoted on (CAIP-2 or canonical name) */
     network: string | null;
     /** Human-readable description */
     description: string;
-    /** Category (e.g., 'defi', 'ai', 'data') */
+    /** Category assigned by the catalog */
     category: string;
-    /** Quality score (0-100, null if unscored) */
+    /** Quality score 0-100 (null if unscored) */
     qualityScore: number | null;
-    /** Whether the endpoint has been verified */
+    /** Whether the endpoint passed AI verification (alias for verificationStatus === 'pass') */
     verified: boolean;
-    /** Total number of settlements (calls) */
+    /** Full verification status: 'pass' | 'fail' | 'inconclusive' | 'skipped' | 'unverified' */
+    verificationStatus: string;
+    /** Total number of settlements (calls) observed against this resource */
     totalCalls: number;
-    /** Total volume in USDC (formatted, e.g., '$1,234.56') */
-    totalVolume: string | null;
-    /** Seller name */
-    seller: string | null;
-    /** Seller reputation score */
-    sellerReputation: number | null;
-    /** Whether authentication is required beyond payment */
-    authRequired: boolean;
-    /** Last time someone called this API */
-    lastActive: string | null;
+    /** Total settled volume in USDC */
+    totalVolumeUsdc: number;
+    /** Icon URL (favicon or seller logo) */
+    iconUrl: string | null;
+    /** Host label derived from the URL */
+    host: string | null;
+    /** Gaming/wash-trading flags — non-empty array means the resource is suspicious */
+    gamingFlags: string[];
+    /** True when any gaming flag is set */
+    gamingSuspicious: boolean;
+    /** Which tier this result fell into — 'strong' (high confidence) or 'related' (adjacent) */
+    tier: 'strong' | 'related';
+    /** Raw cosine similarity 0-1 between the query embedding and the resource embedding */
+    similarity: number;
+    /**
+     * One-sentence explanation of why this result ranked where it did. Built
+     * from the modular ranking factors (semantic similarity, trust, activity,
+     * gaming penalty).
+     */
+    why: string;
+    /** Final combined ranking score in [0, 1] */
+    score: number;
 }
 /**
- * Search the Dexter marketplace for x402 paid APIs.
+ * Why a response has no strong matches.
+ * - 'below_similarity_threshold': no candidates cleared the similarity floor at all
+ * - 'below_strong_threshold': candidates cleared the floor but none reached strong
+ * - null: strongResults is non-empty
+ */
+type NoMatchReason = 'below_similarity_threshold' | 'below_strong_threshold' | null;
+/**
+ * Full response from capability search. Tiered shape with telemetry about
+ * the ranking pipeline.
+ */
+interface CapabilitySearchResult {
+    /** The original query string the caller passed */
+    query: string;
+    /**
+     * Strong matches — high-confidence capability hits (similarity >= strong
+     * threshold). These are the primary results the caller should surface.
+     */
+    strongResults: CapabilityAPI[];
+    /**
+     * Related matches — candidates that cleared the similarity floor but did
+     * not reach the strong threshold. Useful as a secondary section when
+     * strongResults is empty or sparse.
+     */
+    relatedResults: CapabilityAPI[];
+    /** Count of strong results returned */
+    strongCount: number;
+    /** Count of related results returned */
+    relatedCount: number;
+    /** Highest cosine similarity observed across all candidates (null when no candidates) */
+    topSimilarity: number | null;
+    /** Reason the response has no strong matches (null when strong matches exist) */
+    noMatchReason: NoMatchReason;
+    /**
+     * Cross-encoder rerank telemetry. `applied` is true when the LLM actually
+     * reordered the top strong results; `reason` explains any skip.
+     */
+    rerank: {
+        enabled: boolean;
+        applied: boolean;
+        reason?: string;
+    };
+    /**
+     * The parsed intent the backend extracted. `capabilityText` is the bare
+     * capability; `expandedCapabilityText` is the synonym-expanded version that
+     * was actually embedded for the vector search.
+     */
+    intent: {
+        capabilityText: string;
+        expandedCapabilityText?: string;
+    };
+    /** Total wall-clock duration of the capability search request in milliseconds */
+    durationMs: number;
+}
+/**
+ * Search the Dexter x402 marketplace using semantic capability search.
  *
- * Returns a list of discovered endpoints that can be called directly
- * with `wrapFetch` or `createX402Client.fetch`.
+ * Returns tiered results (strongResults + relatedResults) plus ranking
+ * telemetry. Handles synonym expansion and cross-encoder LLM rerank
+ * internally — pass the user's natural-language intent directly.
  *
- * @example Find AI APIs under $0.10
+ * @example Find an ETH price feed
  * ```typescript
- * const apis = await searchAPIs({ query: 'ai', maxPrice: 0.10 });
+ * const result = await capabilitySearch({ query: 'get current ETH spot price' });
+ * if (result.strongCount > 0) {
+ *   const best = result.strongResults[0];
+ *   console.log(`${best.name}: ${best.price} — ${best.why}`);
+ * } else if (result.relatedCount > 0) {
+ *   console.log(`No exact match. Closest related: ${result.relatedResults[0].name}`);
+ * } else {
+ *   console.log(`No match. Reason: ${result.noMatchReason}`);
+ * }
  * ```
  *
- * @example Browse all verified DeFi tools
+ * @example Skip the LLM rerank for lowest latency
  * ```typescript
- * const apis = await searchAPIs({ category: 'defi', verifiedOnly: true });
+ * const result = await capabilitySearch({ query: 'token price', rerank: false });
  * ```
  *
- * @example Find cheapest APIs on Solana
+ * @example Include unverified resources (usually omitted)
  * ```typescript
- * const apis = await searchAPIs({ network: 'solana', sort: 'quality_score' });
+ * const result = await capabilitySearch({ query: 'image generation', unverified: true });
  * ```
  */
-declare function searchAPIs(options?: SearchAPIsOptions): Promise<DiscoveredAPI[]>;
+declare function capabilitySearch(options: CapabilitySearchOptions): Promise<CapabilitySearchResult>;
 
 /**
  * Budget Account — Autonomous Agent Spending Controls
@@ -423,4 +544,4 @@ interface BudgetAccount {
  */
 declare function createBudgetAccount(config: BudgetAccountConfig): BudgetAccount;
 
-export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type DiscoveredAPI, KEYPAIR_SYMBOL, type KeypairWallet, type PaymentRecord, type SearchAPIsOptions, type WrapFetchOptions, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, searchAPIs, wrapFetch };
+export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type CapabilityAPI, type CapabilitySearchOptions, type CapabilitySearchResult, KEYPAIR_SYMBOL, type KeypairWallet, type NoMatchReason, type PaymentRecord, type WrapFetchOptions, capabilitySearch, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };