Skip to main content

Agent Discovery & Registry

When you create a Shopify integration with Lightning Enable, your store is automatically registered in the L402 API registry. This means AI agents can find your store using the discover_api MCP tool — no extra setup required.

How It Works​

AI Agent                          L402 Registry                     Your Store
   │                                   │                                │
   ├─ discover_api("coffee") ─────────►│                                │
   │◄──── matching stores ────────────┤                                │
   │                                   │                                │
   ├─ discover_api(url=manifest) ─────►│                                │
   │◄──── full endpoint details ──────┤                                │
   │                                   │                                │
   ├─ GET /catalog ────────────────────┼───────────────────────────────►│
   │◄──── products ────────────────────┼───────────────────────────────┤
   │                                   │                                │
   ├─ POST /checkout ──────────────────┼───────────────────────────────►│
   │◄──── 402 + invoice ──────────────┤                                │
   │  ... (pay + claim flow) ...       │                                │
  1. Agent searches the registry using keywords like "coffee", "health", or a category like "food-and-beverage"
  2. Registry returns matching stores with name, description, categories, and manifest URL
  3. Agent fetches manifest for full endpoint details — what's free, what requires payment, pricing model
  4. Agent uses the store — browses catalog, creates checkout, pays, and claims

Registry Listing​

By default, listInRegistry is enabled when you create a Shopify integration. Your store appears in the registry with:

  • Name — derived from your slug (e.g., "my-store (Shopify)")
  • Description — your registryDescription or a default description
  • Categories — your registryCategories for keyword and category search
  • 4 endpoints — catalog (free), checkout (L402/dynamic), claim (L402), order status (free)

Categories​

Categories help agents find your store. Use a JSON array of lowercase, hyphenated terms that describe what you sell:

["commerce", "food-and-beverage", "health", "hydration"]

Good categories are specific and domain-appropriate. Some examples:

Store TypeSuggested Categories
Food & drinkcommerce, food-and-beverage, health, nutrition
Clothingcommerce, apparel, fashion
Electronicscommerce, electronics, gadgets
Art & printscommerce, art, digital-goods
Software licensescommerce, software, digital-goods

Description​

The registryDescription is used for keyword search. Write it like you're describing your store to an AI agent that needs to decide whether to shop there:

Premium single-origin coffee beans and brewing equipment. Specialty roasts from Ethiopia, Colombia, and Guatemala available for AI agent purchases via Lightning L402 payments.

Configuring Registry Settings​

At Creation​

Include registry fields when creating your integration:

curl -X POST https://api.lightningenable.com/api/merchant/shopify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-coffee-store",
    "shopifyDomain": "my-store.myshopify.com",
    "adminApiAccessToken": "shpat_...",
    "listInRegistry": true,
    "registryCategories": "[\"commerce\",\"food-and-beverage\",\"coffee\"]",
    "registryDescription": "Premium single-origin coffee beans and brewing equipment available for AI agent purchases via Lightning L402 payments."
  }'

Updating​

Update registry fields at any time:

curl -X PUT https://api.lightningenable.com/api/merchant/shopify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registryCategories": "[\"commerce\",\"food-and-beverage\",\"coffee\",\"specialty-roasts\"]",
    "registryDescription": "Updated description for your store."
  }'

Configuration Reference​

FieldTypeDefaultDescription
listInRegistrybooleantrueWhether to list your store in the L402 API registry
registryCategoriesstring["commerce"]JSON array of categories for search and filtering
registryDescriptionstringauto-generatedRich description for keyword search

Disabling Registry Listing​

To remove your store from agent discovery while keeping the integration active:

curl -X PUT https://api.lightningenable.com/api/merchant/shopify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listInRegistry": false}'

Your store endpoints still work — agents with the direct URL can still purchase. They just won't find you via discover_api search.

Pausing vs Delisting

Setting isActive: false pauses the integration entirely (no purchases possible) and also removes it from the registry. Setting listInRegistry: false only hides it from discovery — agents with the URL can still shop.

The Manifest​

Each registered store gets an auto-generated L402 manifest at:

https://api.lightningenable.com/l402/proxy/shopify-{slug}/.well-known/l402-manifest.json

The manifest follows the L402 Manifest Schema and includes:

  • Service metadata — name, description, categories, documentation URL
  • L402 configuration — payment flow, supported currencies
  • Endpoints — each with path, method, pricing model, and whether L402 is required

Endpoint Pricing Models​

EndpointPricingL402 RequiredDescription
GET /catalogFreeNoBrowse products — always free
POST /checkoutDynamicYesPrice depends on cart contents
POST /claimFreeYesL402 credential required (from checkout payment)
GET /orders/{id}FreeNoCheck order status with claim token

"Dynamic" pricing means the price is determined at request time based on what's in the cart. The agent sees this in the manifest and knows to expect a variable amount.

How Agents Use discover_api​

AI agents using the Lightning Enable MCP server can search the registry in two ways:

Agent: "Find stores that sell coffee"
→ discover_api(query="coffee")
→ Returns matching stores with names, descriptions, categories, and manifest URLs

Category Browse​

Agent: "What food and beverage stores are available?"
→ discover_api(category="food-and-beverage")
→ Returns all stores in that category

Manifest Fetch​

Agent: "Show me the full details for this store"
→ discover_api(url="https://api.lightningenable.com/l402/proxy/shopify-my-store/.well-known/l402-manifest.json")
→ Returns complete endpoint details, pricing models, and L402 requirements

Budget-Aware Discovery​

With budgetAware: true (the default), discover_api annotates results with how many calls the agent can afford based on its remaining budget. For Shopify stores with free catalog browsing, this means agents know they can browse unlimited catalogs at zero cost.

Next Steps​