{"openapi":"3.1.0","info":{"title":"Bullion Sniper Public API","version":"1.1.0","description":"Public discovery document for Bullion Sniper market comparison endpoints, agent-friendly snapshots, and MCP discovery."},"servers":[{"url":"https://www.bullion-sniper.fr","description":"Public website surface and agent-friendly read-only endpoints"},{"url":"https://api.bullion-sniper.fr","description":"Production upstream API"}],"paths":{"/api/public/market-snapshot":{"get":{"summary":"Get a standardized market snapshot","description":"Return a normalized Bullion Sniper snapshot that is easy for agents and search systems to consume.","parameters":[{"name":"metal","in":"query","schema":{"type":"string","enum":["or","ar"]}},{"name":"minBudget","in":"query","schema":{"type":"number","minimum":0}},{"name":"maxBudget","in":"query","schema":{"type":"number","minimum":1}},{"name":"quantity","in":"query","schema":{"type":"integer","minimum":1}},{"name":"site","in":"query","schema":{"type":"string","enum":["all","traditional","ebay_europe","ebay_fr"]}},{"name":"countries","in":"query","schema":{"type":"string"}},{"name":"coins","in":"query","schema":{"type":"string"}},{"name":"lingots","in":"query","schema":{"type":"boolean"}},{"name":"fdp","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Agent-friendly market snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMarketSnapshot"}}}}}}},"/api/public/best-offers":{"get":{"summary":"Get the best visible offers","description":"Return the best visible offers according to the comparator ranking for a given filter set.","parameters":[{"name":"metal","in":"query","schema":{"type":"string","enum":["or","ar"]}},{"name":"minBudget","in":"query","schema":{"type":"number","minimum":0}},{"name":"maxBudget","in":"query","schema":{"type":"number","minimum":1}},{"name":"quantity","in":"query","schema":{"type":"integer","minimum":1}},{"name":"site","in":"query","schema":{"type":"string","enum":["all","traditional","ebay_europe","ebay_fr"]}},{"name":"countries","in":"query","schema":{"type":"string"}},{"name":"coins","in":"query","schema":{"type":"string"}},{"name":"lingots","in":"query","schema":{"type":"boolean"}},{"name":"fdp","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Agent-friendly best offers response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBestOffersResponse"}}}}}}},"/api/public/product-prime":{"get":{"summary":"Get a product prime summary","description":"Return a prime summary for a product query such as napoleon, souverain, or vreneli.","parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"metal","in":"query","schema":{"type":"string","enum":["or","ar"]}},{"name":"minBudget","in":"query","schema":{"type":"number","minimum":0}},{"name":"maxBudget","in":"query","schema":{"type":"number","minimum":1}},{"name":"quantity","in":"query","schema":{"type":"integer","minimum":1}},{"name":"site","in":"query","schema":{"type":"string","enum":["all","traditional","ebay_europe","ebay_fr"]}},{"name":"countries","in":"query","schema":{"type":"string"}},{"name":"coins","in":"query","schema":{"type":"string"}},{"name":"lingots","in":"query","schema":{"type":"boolean"}},{"name":"fdp","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Agent-friendly product prime summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProductPrimeResponse"}}}}}}},"/api/bullion/compare":{"get":{"summary":"Compare bullion offers","description":"Return a comparison snapshot for gold or silver offers using URL-friendly filter parameters.","parameters":[{"name":"metal","in":"query","required":true,"schema":{"type":"string","enum":["or","ar"]}},{"name":"maxBudget","in":"query","required":true,"schema":{"type":"number","minimum":1}},{"name":"minBudget","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"quantity","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"site","in":"query","required":false,"schema":{"type":"string","enum":["all","traditional","ebay_europe","ebay_fr"]}},{"name":"countries","in":"query","required":false,"schema":{"type":"string"}},{"name":"coins","in":"query","required":false,"schema":{"type":"string"}},{"name":"lingots","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"fdp","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Comparator snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceCalculationResponse"},"examples":{"comparatorSnapshot":{"value":{"offers":[{"id":"123","name":"20 Francs Napoleon","platform":"Bullion vendeur","country":"FR","quantity":1,"unit_price":640,"fdp":0,"total":640,"prime":3.2,"url":"https://www.bullion-sniper.fr/comparateur-achat-or-argent"}],"gold_price":{"buy_price":132.5,"sell_price":131.9,"session_id":"session-1"},"timestamp":"2026-04-25T19:00:00.000Z","coverage_count":128,"matching_offers_count":19,"data_updated_at":"2026-04-25T18:58:00.000Z"}}}}}}}}},"/api/bullion/constants":{"get":{"summary":"List canonical bullion constants","responses":{"200":{"description":"Supported coins and bullion constants"}}}},"/api/bullion/pricing":{"get":{"summary":"Return latest retained metal prices","responses":{"200":{"description":"Gold and silver pricing snapshot"}}}},"/api/bullion/get-url":{"post":{"summary":"Resolve offer URL","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["item_id","platform"],"properties":{"item_id":{"type":"string"},"platform":{"type":"string"},"track_click":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Resolved destination URL"}}}}},"components":{"schemas":{"MetalPriceData":{"type":"object","properties":{"buy_price":{"type":"number"},"sell_price":{"type":"number"},"session_id":{"type":"string"}}},"BullionOffer":{"type":"object","required":["id","name","platform","country","quantity","unit_price","fdp","total","prime"],"properties":{"id":{"oneOf":[{"type":"integer"},{"type":"string"}]},"name":{"type":"string"},"platform":{"type":"string"},"country":{"type":"string"},"quantity":{"type":"integer"},"unit_price":{"type":"number"},"fdp":{"type":"number"},"total":{"type":"number"},"prime":{"type":"number"},"url":{"type":"string"},"affiliated_url":{"type":"string"}}},"PriceCalculationResponse":{"type":"object","properties":{"offers":{"type":"array","items":{"$ref":"#/components/schemas/BullionOffer"}},"metal_price":{"$ref":"#/components/schemas/MetalPriceData"},"gold_price":{"$ref":"#/components/schemas/MetalPriceData"},"silver_price":{"$ref":"#/components/schemas/MetalPriceData"},"timestamp":{"type":"string","format":"date-time"},"total_offers_count":{"type":"integer"},"coverage_count":{"type":"integer"},"matching_offers_count":{"type":"integer"},"data_updated_at":{"type":"string","format":"date-time"}}},"AgentPublicFilters":{"type":"object","properties":{"metal":{"type":"string","enum":["or","ar"]},"minBudget":{"type":"number"},"maxBudget":{"type":"number"},"quantity":{"type":"integer"},"site":{"type":"string","enum":["all","traditional","ebay_europe","ebay_fr"]},"countries":{"type":"array","items":{"type":"string"}},"coins":{"type":"array","items":{"type":"string"}},"lingots":{"type":"boolean"},"fdp":{"type":"boolean"},"limit":{"type":"integer"}}},"AgentPublicOffer":{"type":"object","properties":{"rank":{"type":"integer"},"name":{"type":"string"},"platform":{"type":"string"},"country":{"type":"string"},"total":{"type":"number"},"prime":{"type":"number"},"quantity":{"type":"integer"},"unit_price":{"type":"number"},"shipping_cost":{"type":"number"},"url":{"type":"string"}}},"AgentMarketSnapshot":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"comparator_url":{"type":"string"},"filters":{"$ref":"#/components/schemas/AgentPublicFilters"},"coverage_count":{"type":"integer"},"matching_offers_count":{"type":"integer"},"tracked_sellers_count":{"type":["integer","null"]},"data_updated_at":{"type":["string","null"],"format":"date-time"},"retained_prices":{"type":"object","properties":{"gold":{"type":["number","null"]},"silver":{"type":["number","null"]},"active_metal":{"type":["number","null"]}}},"methodology":{"type":"object","properties":{"methodology_version":{"type":["string","null"]},"ranking_policy":{"type":["string","null"]},"affiliate_policy":{"type":["string","null"]}}},"sample_offers":{"type":"array","items":{"$ref":"#/components/schemas/AgentPublicOffer"}}}},"AgentBestOffersResponse":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"comparator_url":{"type":"string"},"filters":{"$ref":"#/components/schemas/AgentPublicFilters"},"offer_count":{"type":"integer"},"price_band":{"type":"object","properties":{"min_total":{"type":["number","null"]},"max_total":{"type":["number","null"]}}},"retained_metal_price":{"type":["number","null"]},"offers":{"type":"array","items":{"$ref":"#/components/schemas/AgentPublicOffer"}}}},"AgentProductPrimeResponse":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"comparator_url":{"type":"string"},"query":{"type":"string"},"filters":{"$ref":"#/components/schemas/AgentPublicFilters"},"matched_offer_count":{"type":"integer"},"retained_metal_price":{"type":["number","null"]},"prime_stats":{"type":"object","properties":{"min":{"type":["number","null"]},"average":{"type":["number","null"]},"median":{"type":["number","null"]},"max":{"type":["number","null"]}}},"sample_offers":{"type":"array","items":{"$ref":"#/components/schemas/AgentPublicOffer"}}}}}}}