{"openapi":"3.1.0","info":{"title":"Luxe Oracle API","version":"1.1.0","summary":"Real-time Hermès inventory oracle for AI agents — pay $0.001 USDC per call on Base via x402.","description":"Luxe Oracle is the first x402-powered data oracle for luxury handbag stocks. AI agents discover available models from a free inventory endpoint, then pay $0.001 USDC per stock-status query (or $0.01 for a 10-credit session). All settlement happens on Base mainnet through the x402 protocol — no API keys, no signups.","contact":{"name":"Luxe Oracle","url":"https://luxe-oracle.com"},"x-guidance":"Step 1: GET /api/v1/inventory?brand=hermes&region=sg to list available models. Step 2: GET /api/v1/monitor/{region}/{brand}/{model} (paid) to retrieve real-time stock status. For high-volume use, POST /api/v1/sessions to buy 10 pre-paid queries and pass them via X-Session-Key.","x-agent-tags":["oracle","inventory","real-time","luxury","hermes","x402","pay-per-call","usdc","base","ai-agent"],"x-categories":["data-oracle","commerce","inventory"],"x-payment-protocols":["x402"],"x-network":"base","x-currency":"USDC"},"servers":[{"url":"https://api.luxe-oracle.com","description":"Production server (Base mainnet, x402)"}],"paths":{"/api/v1/inventory":{"get":{"summary":"List available Hermès products in a region (free)","description":"Free discovery endpoint. Returns the catalog of product IDs and display names available for monitoring in a given region. Use the returned `id` values as the `model` path parameter for /api/v1/monitor.","tags":["discovery"],"parameters":[{"name":"brand","in":"query","required":false,"schema":{"type":"string","default":"hermes","enum":["hermes"]},"description":"Brand name (currently only hermes supported)."},{"name":"region","in":"query","required":false,"schema":{"type":"string","enum":["tw","sg","jp","uk","us","ca"]},"description":"Region code: tw (Taiwan), sg (Singapore), jp (Japan), uk (United Kingdom), us (United States), ca (Canada). Omit to list all supported regions for the brand."}],"responses":{"200":{"description":"List of items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"H086962CK0G"},"name":{"type":"string","example":"Birkin 25"},"link":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v1/monitor/{region}/{brand}/{model}":{"get":{"summary":"Check real-time stock status of a specific product (paid)","description":"Paid x402 endpoint. Returns whether the model is currently in stock, plus structured metadata and last-update timestamp. Settlement: $0.001 USDC on Base. The first call returns HTTP 402 with payment instructions; replay with the X-PAYMENT header.","tags":["monitor","paid"],"parameters":[{"name":"region","in":"path","required":true,"schema":{"type":"string","enum":["tw","sg","jp","uk","us","ca"]}},{"name":"brand","in":"path","required":true,"schema":{"type":"string","enum":["hermes"]}},{"name":"model","in":"path","required":true,"schema":{"type":"string"},"description":"Product ID returned by /api/v1/inventory (e.g. H086962CK0G)."}],"x-payment-info":{"price":{"mode":"fixed","currency":"USDC","amount":"0.001"},"protocols":["x402"],"network":"base"},"responses":{"200":{"description":"Stock status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","unsupported","unavailable"]},"brand":{"type":"string"},"region":{"type":"string"},"model":{"type":"string"},"in_stock":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true},"last_update":{"type":"string","format":"date-time"}}}}}},"402":{"description":"Payment Required (x402)"}}}},"/api/v1/sessions":{"get":{"summary":"Buy a session OR look up an existing one","description":"Without query params: equivalent to POST — returns 402 with an x402 quote, or settles and creates a 10-credit session if X-PAYMENT is supplied. With ?id= or ?token=: free status lookup for an existing session. The paid GET form exists so x402 indexers (x402scan, Bazaar crawlers) can probe and register this resource — most agents should use POST as the canonical buy path.","tags":["session","paid","lookup"],"parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string"},"description":"Session ID (public) — return remaining credits and expiry."},{"name":"token","in":"query","required":false,"schema":{"type":"string"},"description":"Session token (private) — return remaining credits and expiry."}],"x-payment-info":{"price":{"mode":"fixed","currency":"USDC","amount":"0.01"},"protocols":["x402"],"network":"base","note":"Only applies when no id/token query params are present."},"responses":{"200":{"description":"Session status (lookup mode, free)","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string","enum":["active","expired","exhausted"]},"totalCredits":{"type":"number"},"usedCredits":{"type":"number"},"remainingCredits":{"type":"number"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"201":{"description":"Session created (buy mode, after settlement)"},"402":{"description":"Payment Required (x402, buy mode)"},"404":{"description":"Session not found (lookup mode)"}}},"post":{"summary":"Create a 10-query pre-paid session ($0.01 USDC) — canonical buy path","description":"Canonical purchase endpoint. Buy a session token good for 10 monitor queries, billed at $0.01 USDC up front via x402. Pass the returned sessionToken as the X-Session-Key header on subsequent /api/v1/monitor requests to skip per-call x402 settlement. Functionally equivalent to GET /api/v1/sessions (no query params) — POST is preferred for HTTP semantic correctness.","tags":["session","paid"],"x-payment-info":{"price":{"mode":"fixed","currency":"USDC","amount":"0.01"},"protocols":["x402"],"network":"base"},"responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"sessionToken":{"type":"string"},"credits":{"type":"number","example":10},"expiresAt":{"type":"string","format":"date-time"},"pricePerQuery":{"type":"string","example":"$0.001 USDC"},"usage":{"type":"string"}}}}}},"402":{"description":"Payment Required (x402)"}}}}}}