# MagicSearch

Canonical URL: https://magiccard.ai/docs/components/magicsearch
Markdown URL: https://magiccard.ai/docs/components/magicsearch.md
Summary: MagicSearch gives agents fast commerce routing data: trusted providers, scored payment methods, checkout targets, API-capable paths, and fallback search results when the index is not enough.
Description: MagicSearch is an extensible commerce provider index and query layer for personal AI agents.

## Canonical Answer

MagicSearch gives agents fast commerce routing data: trusted providers, scored payment methods, checkout targets, API-capable paths, and fallback search results when the index is not enough. MagicSearch is an extensible commerce provider index and query layer for personal AI agents. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context.

![Provider search and ranking](https://magiccard.ai/docs-assets/images/components-magicsearch-routing.svg)

## Key Points

- Extensible provider index populated by curated entries and automated discovery.
- Query interface for merchant, product, category, geography, intent, and preferred payment channels.
- Ranks payment methods such as x402, MCP, official API, reversed API, and browser checkout.
- Returns either an API-capable payment route or a checkout URL for MagicBrowse.
- Uses choice requests when the user needs to pick between several viable options.

## Provider Index

MagicSearch is a commerce provider index built for agents, not a browser search page built for humans. The index can contain human-curated providers, automatically discovered providers, trust information, supported countries, merchant domains, checkout entry points, provider tags, historical purchase signals, and payment method records. The goal is to answer the agent quickly: which provider should handle this intent, which channel should be used, and whether the workflow can continue through an API or should hand off to MagicBrowse.

```ts
// Simplified shapes — see @nuanu-ai/magicsearch for the full types.
type MagicSearchProviderRecord = {
  id: string;
  name: string;
  description: string | null;
  category: string | null;
  enabled: boolean;
  status: 'active' | 'paused' | 'deprecated';
  domains: string[];
  searchTerms: string[];
  intentTypes: string[];
  categories: string[];
  tags: string[];
  score: number;
  metadata: Record<string, unknown>;
};

type MagicSearchPurchaseMethodRecord = {
  id: string;
  providerId: string;
  type: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser';
  status: 'active' | 'experimental' | 'paused';
  metadata: Record<string, unknown>;
};
```

## Agent Query Interface

Agents query MagicSearch with the user request plus structured hints. The query can include merchant, domain, product, category, country, region, place, intent type, checkout shape, quote requirements, authentication context, and preferred method types. MagicSearch normalizes those inputs into a provider query and a discovery query, so the agent does not need to open a browser just to find the right starting point.

```ts
import { createRemoteMagicSearchClient } from '@nuanu-ai/magicsearch';

const search = createRemoteMagicSearchClient({
  apiUrl: process.env.MAGICPAY_API_URL!,
  apiKey: process.env.MAGICPAY_API_KEY!,
});

const result = await search.query({
  query: 'Book a hotel in Lisbon for May 10 to 12',
  purpose: 'checkout',
  hints: {
    merchantHint: 'Booking.com',
    category: 'hotel',
    country: 'PT',
    placeHint: 'Lisbon',
  },
  providerQuery: {
    intentType: 'booking',
    preferredMethodTypes: ['mcp', 'api', 'browser'],
    quoteRequirements: ['dates', 'room', 'refund policy'],
  },
});
```

## Payment Methods

A provider can expose multiple payment methods. MagicSearch scores the compatible methods before the workflow starts, so the agent can prefer the fastest and most agent-native channel while still falling back to legacy commerce when needed.

Method | Use when | Default rank
--- | --- | ---
x402 | The provider supports HTTP-native stablecoin payment or machine-readable paywall settlement. | Highest priority because the payment can be handled as an agent-native protocol.
MCP | The provider exposes an MCP-compatible commerce tool or MagicPay can call a provider-specific MCP facade. | Preferred after x402 because the agent can use a structured tool interface.
API | The provider has an official API or MagicPay backend can complete the checkout programmatically. | Preferred when it avoids browser work and keeps the payment process server-side.
Reversed API | MagicPay has learned a provider flow that can be called without ordinary browser interaction. | Useful when there is no official API but the flow is reliable enough to automate.
Browser | The provider only supports a normal website checkout or account flow. | Fallback method that hands a start URL to MagicBrowse.

## Scoring

Provider scoring combines evidence about the provider and evidence about the method. Exact merchant or domain matches rank highest. Vertical matches such as hotel or flight providers beat loose text matches. Intent, category, tag, country, region, and product hints help narrow the catalog. Payment method scoring then favors x402, MCP, API, reversed API, and browser in that order, with a small bonus for method types requested by the agent. Low-confidence matches fall back to discovery instead of pretending the index knows the answer.

- Only active and enabled provider entries can be selected.
- A strong provider match needs exact provider evidence, vertical evidence, intent/category evidence, or enough trusted metadata.
- If the selected provider has no compatible active payment method, MagicSearch falls back to discovery.
- Scores improve routing, but they never bypass user approval, MagicPay policy, or protected payment requests.

## Result Shape

MagicSearch returns the route and runtime method the agent should use next. Every successful beta result has methodType browser, so the runtime hands the URL to MagicBrowse. Provider capability metadata remains nested for later x402, MCP, API, or other dispatchers.

```ts
// Simplified shape — see @nuanu-ai/magicsearch for the full type.
type MagicSearchUrlResult = {
  url: string;
  source: MagicSearchResultSource;
  methodType: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser';
  title: string | null;
  query: string;
  confidence: 'high' | 'medium' | 'low';
  provider: {
    id: string;
    name: string | null;
    methodId: string | null;
    methodType: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser' | null;
    confidence: 'high' | 'medium' | 'low' | 'none';
  } | null;
  choices?: MagicSearchChoiceOption[];
};
```

## Choice Request

When MagicSearch finds several plausible items, providers, hotels, flights, products, or checkout targets, it can pause the workflow with a MagicPay choice request. The user picks the option that matches their intent instead of forcing the agent to guess. The user can also add notes, such as a preferred room type, delivery constraint, budget, or merchant preference; MagicSearch can use those notes as adjusted search input and continue the job with better context.

- Choice options can include title, subtitle, description, URL, price, images, and characteristics.
- The agent receives the selected option and can continue with the selected checkout URL.
- Choice requests are especially useful for travel, tickets, restaurants, products, and services where the phrase “best option” depends on user preference.

## Search Fallback

If the provider index has no match, has only a low-confidence match, or has a provider without a usable URL, MagicSearch falls back to agentic web discovery using web search providers. The fallback result gives MagicBrowse a better starting URL than a blank browser search, and multiple fallback results can become choice options for the user.

- Fallback is a recovery path, not the primary product model.
- The discovery query is built from the prompt plus merchant, product, domain, category, geography, and purchase-purpose hints.
- MagicBrowse starts from the returned provider, product, or checkout page instead of browsing like a human from the homepage.

## Related

- E2E Purchase Flow: https://magiccard.ai/docs/guides/e2e-purchase
- Payment Methods: https://magiccard.ai/docs/reference/payment-methods
- Trust System: https://magiccard.ai/docs/reference/trust-system