{"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://bullion-sniper.fr","description":"Public website surface and agent-friendly read-only endpoints"}],"paths":{"/api/public/market-snapshot":{"get":{"summary":"Get a standardized market snapshot","description":"Return a normalized Bullion Sniper snapshot that is easy for compatible tools 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/public/silver-price":{"get":{"summary":"Get the global silver price snapshot","description":"Return the BullionVault Europe silver reference, Bullion Sniper boutique quote, free/delayed silver sources, and global market catalogue.","responses":{"200":{"description":"Global silver price snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SilverGlobalSnapshot"}}}}}}},"/api/public/cot-dashboard":{"get":{"summary":"Get the public COT dashboard","description":"Return normalized CFTC Commitment of Traders snapshots for gold, silver, platinum, and palladium.","parameters":[{"name":"weeks","in":"query","schema":{"type":"integer","minimum":2,"maximum":260,"default":52}}],"responses":{"200":{"description":"Public COT dashboard response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotDashboardResponse"}}}}}}},"/api/public/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://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/public/metal-prices":{"get":{"summary":"Return latest retained metal prices","responses":{"200":{"description":"Gold and silver pricing snapshot"}}}}},"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"},"optimizeQuantities":{"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"}}}},"SilverPricePack":{"type":"object","properties":{"currency":{"type":"string"},"per_gram":{"type":["number","null"]},"per_troy_ounce":{"type":["number","null"]},"per_kilo":{"type":["number","null"]}}},"SilverGlobalSnapshot":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"metal":{"type":"string","enum":["silver"]},"reference":{"type":"object","properties":{"source_key":{"type":"string"},"source_label":{"type":"string"},"status":{"type":"string"},"buy":{"$ref":"#/components/schemas/SilverPricePack"},"sell":{"$ref":"#/components/schemas/SilverPricePack"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"boutique_quote":{"type":"object","properties":{"status":{"type":"string"},"price":{"$ref":"#/components/schemas/SilverPricePack"},"applied_mean_premium_percent":{"type":["number","null"]},"offer_count":{"type":"integer"},"seller_count":{"type":"integer"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"global_markets":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"region":{"type":"string"},"venue":{"type":"string"},"api_access":{"type":"string"},"official_url":{"type":"string"},"data_status":{"type":"string"}}}}}},"CotSource":{"type":"object","properties":{"reportUrl":{"type":"string","format":"uri"},"datasetId":{"type":"string"},"datasetUrl":{"type":"string","format":"uri"}}},"CotCategoryPosition":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"long":{"type":["integer","null"]},"short":{"type":["integer","null"]},"net":{"type":["integer","null"]},"changeLong":{"type":["integer","null"]},"changeShort":{"type":["integer","null"]},"changeNet":{"type":["integer","null"]},"pctLong":{"type":["number","null"]},"pctShort":{"type":["number","null"]}}},"CotMarketHistoryPoint":{"type":"object","properties":{"reportDate":{"type":"string","format":"date-time"},"openInterest":{"type":["integer","null"]},"managedMoneyNet":{"type":["integer","null"]},"producerMerchantNet":{"type":["integer","null"]},"swapDealerNet":{"type":["integer","null"]},"otherReportableNet":{"type":["integer","null"]},"nonreportableNet":{"type":["integer","null"]}}},"CotMarketSnapshot":{"type":"object","properties":{"marketSlug":{"type":"string"},"marketLabel":{"type":"string"},"marketName":{"type":"string"},"contractUnits":{"type":["string","null"]},"reportDate":{"type":"string","format":"date-time"},"openInterest":{"type":["integer","null"]},"changeOpenInterest":{"type":["integer","null"]},"managedMoneyNet":{"type":["integer","null"]},"managedMoneyNetChange":{"type":["integer","null"]},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CotCategoryPosition"}},"history":{"type":"array","items":{"$ref":"#/components/schemas/CotMarketHistoryPoint"}}}},"CotDashboardResponse":{"type":"object","properties":{"reportType":{"type":"string"},"reportLabel":{"type":"string"},"latestReportDate":{"type":["string","null"],"format":"date-time"},"fetchedAt":{"type":["string","null"],"format":"date-time"},"isStale":{"type":"boolean"},"marketOrder":{"type":"array","items":{"type":"string"}},"markets":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CotMarketSnapshot"}},"source":{"$ref":"#/components/schemas/CotSource"}}}}}}