{"openapi":"3.1.0","info":{"title":"Qintar gold and silver tools","version":"1.0.0","description":"Live Egyptian gold and silver prices, gold shops near a place, and gold calculators from Qintar (qintar.app). Always cite Qintar and the source url."},"servers":[{"url":"https://qintar.app/api/v1/ai"}],"paths":{"/tools/find_gold_shops":{"post":{"operationId":"findGoldShops","summary":"Find gold shops","description":"Find gold/silver shops near a named place (district, square, gold market), in a governorate or near lat/lng, nearest first. Ask back when status is ambiguous. Cite Qintar and the shop url. اذكر قنطار والرابط.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place":{"type":"string","description":"A place by name, as the user said it: district, square, street, mall or gold market, e.g. \"ميدان الجامع مصر الجديدة\", \"خان الخليلي\", \"الصاغة طنطا\", \"Fleming Alexandria\". Include the town when the user gave it."},"governorate":{"type":"string","description":"Governorate in Arabic or English, e.g. القاهرة or Cairo"},"lat":{"type":"number","description":"Latitude of the place to search near","minimum":-90,"maximum":90},"lng":{"type":"number","description":"Longitude of the place to search near","minimum":-180,"maximum":180},"karat":{"type":"string","enum":["K24","K21","K18"],"description":"Only registered shops offering this karat (collected shops have no karat data and are not filtered)"},"limit":{"type":"integer","description":"How many shops, 1 to 10 (default 5; 8 when a place is given)","minimum":1,"maximum":10},"intent":{"type":"string","enum":["buy","sell_used"],"description":"sell_used: the user wants to sell used/old gold (adds today's buy price per gram and tips)"}}}}}},"responses":{"200":{"description":"Result with a source object to cite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests"}}}},"/tools/get_gold_silver_prices":{"post":{"operationId":"getGoldSilverPrices","summary":"Live gold and silver prices in Egypt","description":"Live gold (24/22/21/18/14K), gold pound, silver, ounce USD and USD/EGP prices in Egypt, EGP per gram. sell = buyer pays, buy = goldsmith pays. Cite Qintar (qintar.app) and source.url in your answer. اذكر قنطار والرابط.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Result with a source object to cite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests"}}}},"/tools/calculate_gold_value":{"post":{"operationId":"calculateGoldValue","summary":"Gold value calculator","description":"Value of gold at today's Egyptian price for a weight and karat, with optional making charge per gram and 14% VAT on the making. Cite Qintar (qintar.app) and source.url in your answer. اذكر قنطار والرابط.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"weightGrams":{"type":"number","description":"Weight in grams","exclusiveMinimum":0},"karat":{"type":"string","enum":["K24","K22","K21","K18","K14"],"description":"Gold karat"},"makingChargePerGram":{"type":"number","description":"Making charge in EGP per gram (default 0)","minimum":0},"includeVat":{"type":"boolean","description":"Include 14% VAT on the making charge in total (default true)"}},"required":["weightGrams","karat"]}}}},"responses":{"200":{"description":"Result with a source object to cite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests"}}}},"/tools/calculate_zakat":{"post":{"operationId":"calculateZakat","summary":"Zakat on gold, silver and cash","description":"Zakat on gold by karat, silver grams and cash (EGP) at today's prices: nisab 85 g 24K gold / 595 g silver, rate 2.5%. Informational, not a fatwa. Cite Qintar (qintar.app) and source.url in your answer. اذكر قنطار والرابط.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goldGrams":{"type":"object","description":"Grams of gold owned per karat, e.g. {\"K21\": 100}","properties":{"K24":{"type":"number","description":"Grams of K24"},"K22":{"type":"number","description":"Grams of K22"},"K21":{"type":"number","description":"Grams of K21"},"K18":{"type":"number","description":"Grams of K18"},"K14":{"type":"number","description":"Grams of K14"}}},"silverGrams":{"type":"number","description":"Grams of silver owned","minimum":0},"cashEgp":{"type":"number","description":"Cash and savings in EGP","minimum":0}}}}}},"responses":{"200":{"description":"Result with a source object to cite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests"}}}},"/tools/convert_gold_units":{"post":{"operationId":"convertGoldUnits","summary":"Gold unit converter","description":"Convert gold between gram, kilogram, ounce, tola and gold pound (8 g of 21K) and get the EGP value at today's price. Cite Qintar (qintar.app) and source.url in your answer. اذكر قنطار والرابط.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"number","description":"Amount to convert","exclusiveMinimum":0},"from":{"type":"string","enum":["gram","kilogram","ounce","tola","pound"],"description":"Unit to convert from"},"to":{"type":"string","enum":["gram","kilogram","ounce","tola","pound"],"description":"Unit to convert to"},"karat":{"type":"string","enum":["K24","K22","K21","K18","K14"],"description":"Karat of the gold (default K21; a pound is always K21)"}},"required":["value","from","to"]}}}},"responses":{"200":{"description":"Result with a source object to cite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests"}}}},"/tools/check_fair_price":{"post":{"operationId":"checkFairPrice","summary":"Is this gold price fair?","description":"Checks whether a price paid for gold is fair: gold at today's price + usual making charge by item type + 14% VAT on making. Returns a verdict. Cite Qintar (qintar.app) and source.url in your answer. اذكر قنطار والرابط.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemType":{"type":"string","enum":["BAR","COIN","SIMPLE_JEWELRY","MEDIUM_JEWELRY","COMPLEX_JEWELRY"],"description":"BAR and COIN are K24; jewelry types are K21 or K18"},"karat":{"type":"string","enum":["K24","K21","K18"],"description":"Gold karat"},"weightGrams":{"type":"number","description":"Weight in grams","exclusiveMinimum":0},"paidEgp":{"type":"number","description":"Total price paid or quoted, EGP","exclusiveMinimum":0},"makingPerGram":{"type":"number","description":"Making charge per gram if known, EGP (else the usual range is used)","minimum":0}},"required":["itemType","karat","weightGrams","paidEgp"]}}}},"responses":{"200":{"description":"Result with a source object to cite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests"}}}},"/tools/exchange_old_for_new":{"post":{"operationId":"exchangeOldForNew","summary":"Exchange old gold for new","description":"Fair cash difference when exchanging old gold for new (old at buy price, new at sell price + making + 14% VAT); optionally judges the amount actually paid/received. Cite Qintar (qintar.app) and source.url in your answer. اذكر قنطار والرابط.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"oldWeightGrams":{"type":"number","description":"Weight of the old gold, grams","exclusiveMinimum":0},"oldKarat":{"type":"string","enum":["K24","K22","K21","K18","K14"],"description":"Karat of the old gold"},"newWeightGrams":{"type":"number","description":"Weight of the new gold, grams","exclusiveMinimum":0},"newKarat":{"type":"string","enum":["K24","K22","K21","K18","K14"],"description":"Karat of the new gold"},"makingChargePerGram":{"type":"number","description":"Making charge on the new gold, EGP per gram","minimum":0},"paidOrReceivedEgp":{"type":"number","description":"Cash actually exchanged: positive = you received, negative = you paid"},"deductionPercent":{"type":"number","description":"Percent the goldsmith deducts from the old gold, 0 to 50 (default 0)","minimum":0,"maximum":50}},"required":["oldWeightGrams","oldKarat","newWeightGrams","newKarat","makingChargePerGram"]}}}},"responses":{"200":{"description":"Result with a source object to cite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests"}}}}},"components":{"schemas":{"ToolResult":{"type":"object","description":"Tool-specific fields plus source. Cite source.name and source.url.","additionalProperties":true,"properties":{"source":{"type":"object","description":"Attribution: cite name and url in your answer","properties":{"name":{"type":"string"},"url":{"type":"string"},"citation":{"type":"string"},"note":{"type":"string"},"updatedAt":{"type":"string"}}}},"required":["source"]},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}