Developer Docs

API Reference

Read product data, discover stores, and integrate EshopListing into your AI applications.

Protocol v2.0 docs →Get API key →

For AI Systems

llms.txt, crawl policy, discovery

Authentication

API key setup

Store Endpoints

ai.json, products.json, llms.txt

Global Registry

Discover all stores

Scan API

Trigger a scan

Rate Limits

Quotas by plan

Authentication

All API requests must include your API key in the x-api-key header. Generate a key in your dashboard under Settings → API Keys.

curl -H "x-api-key: esl_live_xxxxxxxxxxxxxxxx" \
  https://eshoplisting.com/shop/example.com/ai.json

Keep your key secret. Never expose it in client-side code or public repositories. Rotate keys anytime from the dashboard.

Plan	Key prefix	Access
Free	esl_free_…	Public endpoints only (rate-limited)
Professional	esl_live_…	All endpoints, standard rate limits
Business	esl_live_…	All endpoints, higher limits, buyUrl field
Protocol Scale	esl_live_…	All endpoints, maximum limits, webhooks

Store Endpoints

Every registered store gets its own set of AI-readable endpoints under /shop/{domain}/.

GET/shop/{domain}/ai.jsonAll plans

Full store profile: metadata, scan score, trust signals, and business information. Business+ stores include a trust block with verification details.

GET https://eshoplisting.com/shop/example.com/ai.json

// Response (200 OK)
{
  "domain": "example.com",
  "name": "Example Store",
  "description": "...",
  "score": 87,
  "grade": "A",
  "siteType": "shopify",
  "categories": ["electronics"],
  "productCount": 1247,
  "checks": {
    "llmsTxt": { "found": true },
    "robotsTxt": { "found": true, "allowsAiBots": true },
    "schemaOrg": { "found": true, "hasProduct": true }
  },
  "trust": {
    // Business+ only
    "verified": true,
    "plan": "business",
    "verifiedAt": 1710000000,
    "certificateUrl": "https://eshoplisting.com/shop/example.com/certificate",
    "solanaMintAddress": "...",
    "standard": "EshopListing-v1"
  },
  "scannedAt": 1710000000
}

GET/shop/{domain}/products.jsonProfessional+

Structured product catalog. Returns up to the plan limit (500 Professional, 10,000 Business). Business+ stores include buyUrl — direct add-to-cart links for AI agents.

GET https://eshoplisting.com/shop/example.com/products.json

// Response (200 OK)
{
  "domain": "example.com",
  "productCount": 247,
  "currency": "USD",
  "products": [
    {
      "title": "Example Product",
      "price": "29.99",
      "currency": "USD",
      "image": "https://...",
      "url": "https://example.com/products/example",
      "availability": "in stock",
      "category": "accessories",
      "buyUrl": "https://example.com/cart/add?id=123"  // Business+ only
    }
  ],
  "actions": {
    "buy_now": "https://example.com/cart/add?id=123"  // Business+ only
  }
}

GET/shop/{domain}/llms.txtAll plans

Plain-text store summary in llms.txt format. Designed for direct inclusion in AI system prompts.

GET https://eshoplisting.com/shop/example.com/llms.txt

// Response (200 OK, text/plain)
# Example Store
> AI-readable product catalog

## About
Example Store sells electronics and accessories...

## Products
- Example Product: $29.99, In stock
- Another Product: $49.99, In stock
...

GET/shop/{domain}/certificateBusiness+

Public Solana blockchain certificate proof. Returns JSON with mint address, certificate ID, and verification data.

GET https://eshoplisting.com/shop/example.com/certificate

// Response (200 OK)
{
  "domain": "example.com",
  "verified": true,
  "plan": "business",
  "certId": "cert_abc123",
  "mintAddress": "SoL1abc...",
  "mintedAt": 1710000000,
  "chain": "solana",
  "network": "mainnet-beta",
  "explorerUrl": "https://explorer.solana.com/address/SoL1abc...",
  "issuer": "EshopListing",
  "standard": "EshopListing-v1",
  "productCount": 1247
}

Global Registry

Discover all registered stores in the EshopListing network.

GET/registryPublic

Returns all verified stores with their AI-readable endpoints.

GET https://eshoplisting.com/registry

// Response (200 OK)
{
  "version": "2.0",
  "generated": "2024-03-10T12:00:00Z",
  "totalStores": 140,
  "stores": [
    {
      "domain": "example.com",
      "name": "Example Store",
      "score": 87,
      "endpoints": {
        "aiJson": "https://eshoplisting.com/shop/example.com/ai.json",
        "productsJson": "https://eshoplisting.com/shop/example.com/products.json",
        "llmsTxt": "https://eshoplisting.com/shop/example.com/llms.txt"
      }
    }
  ]
}

GET/registry/llms.txtPublic

All stores in llms.txt format — for AI system prompt inclusion.

GET https://eshoplisting.com/registry/llms.txt

Scan API

POST/api/scanAll plans

Trigger a new scan for a domain. Returns the scan result synchronously (scans typically complete within 5–15 seconds).

POST https://eshoplisting.com/api/scan
Content-Type: application/json
x-api-key: esl_live_xxxxxxxxxxxxxxxx

{
  "domain": "example.com"
}

// Response (200 OK)
{
  "domain": "example.com",
  "score": 87,
  "grade": "A",
  "status": "complete",
  "scannedAt": 1710000000
}

Rate Limits

Rate limits are applied per API key. Exceeding the limit returns a 429 Too Many Requests response with a Retry-After header.

Plan	Reads / min	Scans / day	Product limit
Free	10	3	50
Professional	120	24	500
Business	600	48	10,000
Protocol Scale	Unlimited	Unlimited	Unlimited

Errors

All errors return JSON with a consistent shape:

{
  "error": "string",      // Human-readable message
  "code": "string",       // Machine-readable code
  "status": 400           // HTTP status code
}

Status	Code	Meaning
400	invalid_domain	Domain is malformed or missing
401	unauthorized	Missing or invalid API key
403	forbidden	Plan does not include this endpoint
404	not_found	Domain not registered
429	rate_limited	Too many requests — check Retry-After header
500	internal_error	Server error — retry with exponential backoff

Need more?

Protocol v2.0

Trust headers, MCP integration, llms.txt standard

Dashboard

Manage API keys, view AI hits, configure webhooks