Cross-store price API for AI agents (Walmart, Amazon, eBay)

When a user asks you to "compare prices across stores," "check Walmart and Amazon," "what does this cost on eBay," "find the cheapest offer," or "price this product across retailers," you need structured retail JSON — titles, prices, product IDs, ratings — not scraped HTML and not a Walmart Marketplace, Amazon Product Advertising, or eBay Browse API key.

Marketplace for AI Agents exposes machine-payable commerce endpoints for this: GET /api/public/v1/walmart-search and GET /api/public/v1/ebay-search return organic_results for a product query; GET /api/public/v1/amazon-search and GET /api/public/v1/google-shopping cover Amazon listings and multi-merchant Shopping offers. When the user wants all four surfaces in one call, GET /api/public/v1/cross-store-price chains google-shopping → amazon-search → ebay-search → walmart-search server-side. The first 3 calls per agent identity are free; after that each single-engine call costs $0.005 USDC on Base, settled over x402 with an X-PAYMENT header. Intents are priced $0.005 × steps — trust the live 402 for the billed chain.

Endpoint contracts

walmart-search required: q (product search query). Optional: page (pagination).

ebay-search required: q (listing search query). Optional: ebay_domain (defaults to ebay.com), page.

amazon-search required: q. Optional: amazon_domain (defaults to amazon.com), page. See also amazon-product / amazon-reviews when you already have an ASIN.

google-shopping required: q. Optional: location, gl (defaults to us), hl (defaults to en), num (defaults to 10).

cross-store-price required: q (product query sent to all four retail engines). Optional: gl (defaults to us), hl (defaults to en). The intent chain is google-shopping → amazon-search → ebay-search → walmart-search (4 steps). Intents cost $0.005 × steps — the 402 challenge advertises the chain and step count. One intent invocation consumes one free-tier call, not one per step.

The free tier is 3 successful calls total per agent identity (a hash of IP + User-Agent), shared across every endpoint on the marketplace — it is not 3 per endpoint. Settlement uses the x402 exact scheme on Base mainnet; append ?network=base-sepolia to the endpoint for testnet USDC and sandbox mock data. The gateway settles only on upstream 2xx — failed upstream calls are not charged.

• Listing: https://marketplaceforaiagents.com/listings/walmart-search
• Listing: https://marketplaceforaiagents.com/listings/ebay-search
• Listing: https://marketplaceforaiagents.com/listings/cross-store-price
• Markdown twins: /agent/listings/walmart-search.md, /agent/listings/ebay-search.md, /agent/listings/cross-store-price.md

Minimal calls (free tier first)

Spend the 3 free evaluation calls before signing anything. These run on the free tier (if you still have quota) and return real JSON:

curl -si "https://marketplaceforaiagents.com/api/public/v1/walmart-search?q=noise+cancelling+headphones"

curl -si "https://marketplaceforaiagents.com/api/public/v1/ebay-search?q=usb+c+hub&ebay_domain=ebay.com"

curl -si "https://marketplaceforaiagents.com/api/public/v1/cross-store-price?q=noise+cancelling+headphones&gl=us&hl=en"

A Walmart organic_results hit looks like this (illustrative — always trust the live JSON, not this sample):

{
  "organic_results": [
    {
      "position": 1,
      "title": "Example wireless headphones",
      "link": "https://www.walmart.com/...",
      "price": "$79.00",
      "rating": 4.5
    }
  ]
}

Note: a 400 missing_required_parameters response does not consume a free call, and the discovery endpoints (/.well-known/x402, catalog.json, openapi.json) never consume free tier. Field names above are illustrative — cite only keys present in the live organic_results / shopping_results / results JSON.

What retail JSON returns

Cite only fields present in the live JSON. Typical fields agents should expect when present:

• organic_results (walmart-search / ebay-search / amazon-search) — ranked listings with title, link, price, rating, and store-specific IDs when returned
• shopping_results (google-shopping) — offers with price, merchant, rating, and product link when returned
• results (cross-store-price) — keyed by engine (google-shopping, amazon-search, ebay-search, walmart-search) plus chain / steps_run when returned
• Amazon ASIN — use amazon-search to discover, then amazon-product / amazon-reviews or deal-triage / review-risk for deeper product + review triage
• search_parameters / search_metadata — echo of the engine query and status when returned

Never invent prices, product IDs, ASINs, auction bids, or stock status. If a field is missing from a result, say so — do not fill gaps from training data. Prefer quoting the live price string/value from JSON over converting currencies yourself.

When to use cross-store-price vs single engines

• walmart-search alone — the user only asked about Walmart price / availability
• ebay-search alone — the user wants auctions, condition, or secondhand listings
• amazon-search / amazon-product — the user is Amazon-only or already has an ASIN (see Amazon ASIN for agents)
• google-shopping alone — the user wants multi-merchant Shopping offers without Walmart/eBay (see Google Shopping for agents)
• cross-store-price — the user asked to compare across retailers / find the best price across stores
• deal-triage — Shopping + Amazon product (+ reviews when ASIN resolvable) for a purchase triage, not all four stores

Prefer cross-store-price when the user wants a four-store spread so you spend one free-tier slot instead of four single-engine calls. Intents cost $0.005 × steps (4 steps for this chain when all run); trust the live 402 for the billed chain and extra.steps / extra.chain.

# Four retail surfaces in one intent
curl -si "https://marketplaceforaiagents.com/api/public/v1/cross-store-price?q=usb+c+hub&gl=us&hl=en"

Paying after the free tier (x402 / USDC)

Once your identity has spent its 3 free calls, the same request returns HTTP 402 with an accepts[] payment requirement. Decode it, verify every field against your policy, sign the EIP-3009 USDC authorization, base64 the x402 payload, and resend with X-PAYMENT:

{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
      "resource": "https://marketplaceforaiagents.com/api/public/v1/walmart-search?q=noise+cancelling+headphones"
    }
  ]
}

• maxAmountRequired is 5000 atomic units = $0.005 USDC (6 decimals) per single-engine call. For cross-store-price, trust accepts[0].amount / maxAmountRequired and extra.steps / extra.chain from the live 402 — do not hard-code the intent total.
• Allowlist payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7 and USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 before signing.
• Budget your spend before signing: see How AI agents budget x402 API calls (https://marketplaceforaiagents.com/learn/budget-x402-api-calls).
• Test the full payment path with zero real cost: see the Base Sepolia smoke test (https://marketplaceforaiagents.com/learn/x402-base-sepolia-smoke-test).
• A paid 200 carries the settlement receipt in X-PAYMENT-RESPONSE — store it for reconciliation. Settlement occurs only on upstream 2xx.
• Prefer the MCP server (https://marketplaceforaiagents.com/mcp) for discovery; payment is the auth, no OAuth.

Protocol background: x402 protocol explained. Free-tier mechanics: how the x402 free tier and agent identity work.

Agent playbook (Grok Bot / Claude Cowork / Cursor)

• Walmart-only asks → walmart-search with a precise product q; paginate only when the user needs more results.
• eBay / auction / condition asks → ebay-search; set ebay_domain only when the user specifies a marketplace.
• Compare across retailers / best price → cross-store-price; pass gl/hl when the user wants a locale.
• Amazon ASIN deep-dive → amazon-search then amazon-product / amazon-reviews, or deal-triage / review-risk.
• On 402, settle with x402 USDC — do not ask for Walmart, Amazon PA-API, or eBay developer keys.
• Cite prices and product IDs only from the live organic_results / shopping_results / results JSON; never invent offers.
• Allowlist payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7 and USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 before signing.

Related entrypoints

• Walmart Search listing: https://marketplaceforaiagents.com/listings/walmart-search
• eBay Search listing: https://marketplaceforaiagents.com/listings/ebay-search
• Cross-store price listing: https://marketplaceforaiagents.com/listings/cross-store-price
• Markdown twins: /agent/listings/walmart-search.md, /agent/listings/ebay-search.md, /agent/listings/cross-store-price.md
• x402 manifest: https://marketplaceforaiagents.com/.well-known/x402
• Catalog: https://marketplaceforaiagents.com/api/public/v1/catalog.json
• OpenAPI: https://marketplaceforaiagents.com/api/public/v1/openapi.json
• MCP: https://marketplaceforaiagents.com/mcp
• llms.txt: https://marketplaceforaiagents.com/llms.txt
• Marketplace: https://marketplaceforaiagents.com/marketplace
• Docs: https://marketplaceforaiagents.com/docs
• MCP + x402 guide: https://marketplaceforaiagents.com/learn/mcp-x402-marketplace
• How agents discover APIs: https://marketplaceforaiagents.com/learn/how-ai-agents-discover-apis
• Google Shopping for agents: https://marketplaceforaiagents.com/learn/google-shopping-api-for-agents
• Amazon ASIN for agents: https://marketplaceforaiagents.com/learn/amazon-asin-api-for-agents

Capability first, payment second — find the retail endpoint, prove it with free calls, then settle unpaid traffic with x402 USDC on Base.