{"openapi":"3.1.0","info":{"title":"API بازارهای نِت اَرز","version":"1.0.0","description":"انس طلا و نقره، ارزش محاسبه‌ای طلای ۱۸ عیار و سکه، و ارزها، با همان کلید API نرخ ارز.\n\n- طرح رایگان: هر عدد با 15 دقیقه تأخیر؛ تاریخچه 30 روز بسته‌شدهٔ اخیر.\n- طرح پرو: عدد زنده و همهٔ تاریخچه‌ای که ذخیره کرده‌ایم.\n- سهمیهٔ روزانه و سقف دقیقه‌ای میان API نرخ ارز و این API مشترک است.\n- ارزش محاسبه‌ای قیمت بازار نیست: ارزش محاسبه‌ای از انس جهانی طلا و دلار نِت اَرز به دست می‌آید؛ قیمت بازار تهران نیست و حباب و اجرت در آن حساب نشده است.\n- نام منبع هر عدد در meta.sources است؛ آن را کنار داده نشان دهید."},"servers":[{"url":"https://netarz.ir/api/markets/v1"}],"security":[{"bearer":[]},{"apiKey":[]}],"paths":{"/instruments":{"get":{"summary":"فهرست نمادها","description":"همهٔ نمادهایی که این API می‌دهد، بی‌قیمت. نمادهای ویژهٔ پرو هم با pro_only آمده‌اند.","parameters":[{"name":"class","in":"query","schema":{"type":"string","enum":["fiat","metal","gold_ir","coin_ir"]}}],"responses":{"200":{"description":"فهرست نمادها","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string","example":"XAU"},"asset_class":{"type":"string","enum":["fiat","metal","gold_ir","coin_ir"]},"name_fa":{"type":"string","example":"انس طلا"},"name_en":{"type":"string","example":"Gold ounce"},"unit":{"type":"string","example":"ounce","description":"ounce، gram، mesghal، coin یا currency"},"unit_amount":{"type":"integer","example":1,"description":"برای ارزها: تعداد واحدی که قیمت برای آن است"},"quote_currency":{"type":"string","enum":["USD","IRT"]},"decimals":{"type":"integer"},"source":{"type":"string","example":"goldapi"},"computed":{"type":"boolean","description":"true یعنی ارزش محاسبه‌ای است، نه قیمت بازار"},"pro_only":{"type":"boolean"},"is_market_price":{"type":"boolean","description":"فقط در ردیف‌های محاسبه‌ای، همیشه false"},"label_fa":{"type":"string"},"disclaimer_fa":{"type":"string"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"پارامتر نادرست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نیست یا نادرست است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دامنه یا IP مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف دقیقه‌ای یا سهمیهٔ روزانه پر شده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/latest":{"get":{"summary":"آخرین قیمت چند نماد","description":"بدون symbols همهٔ نمادها برمی‌گردند. نمادی که نمی‌شناسیم یا در طرح شما نیست در meta.skipped می‌آید.","parameters":[{"name":"symbols","in":"query","schema":{"type":"string","example":"XAU,XAG,USD"}}],"responses":{"200":{"description":"قیمت‌ها","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"symbol":{"type":"string","example":"XAU"},"asset_class":{"type":"string","enum":["fiat","metal","gold_ir","coin_ir"]},"name_fa":{"type":"string","example":"انس طلا"},"name_en":{"type":"string","example":"Gold ounce"},"unit":{"type":"string","example":"ounce","description":"ounce، gram، mesghal، coin یا currency"},"unit_amount":{"type":"integer","example":1,"description":"برای ارزها: تعداد واحدی که قیمت برای آن است"},"quote_currency":{"type":"string","enum":["USD","IRT"]},"decimals":{"type":"integer"},"source":{"type":"string","example":"goldapi"},"computed":{"type":"boolean","description":"true یعنی ارزش محاسبه‌ای است، نه قیمت بازار"},"pro_only":{"type":"boolean"},"is_market_price":{"type":"boolean","description":"فقط در ردیف‌های محاسبه‌ای، همیشه false"},"label_fa":{"type":"string"},"disclaimer_fa":{"type":"string"}}},{"type":"object","properties":{"price":{"type":"number","nullable":true,"description":"null یعنی هنوز قیمتی ثبت نشده است (status = no_data)"},"bid":{"type":"number","nullable":true},"ask":{"type":"number","nullable":true},"change_24h":{"type":"number","nullable":true},"change_pct_24h":{"type":"number","nullable":true},"as_of":{"type":"string","format":"date-time","nullable":true},"stale":{"type":"boolean"},"status":{"type":"string","enum":["ok","no_data"]}}}]}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"پارامتر نادرست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نیست یا نادرست است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دامنه یا IP مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف دقیقه‌ای یا سهمیهٔ روزانه پر شده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/latest/{symbol}":{"get":{"summary":"آخرین قیمت یک نماد","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","example":"XAU"}}],"responses":{"200":{"description":"قیمت","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"symbol":{"type":"string","example":"XAU"},"asset_class":{"type":"string","enum":["fiat","metal","gold_ir","coin_ir"]},"name_fa":{"type":"string","example":"انس طلا"},"name_en":{"type":"string","example":"Gold ounce"},"unit":{"type":"string","example":"ounce","description":"ounce، gram، mesghal، coin یا currency"},"unit_amount":{"type":"integer","example":1,"description":"برای ارزها: تعداد واحدی که قیمت برای آن است"},"quote_currency":{"type":"string","enum":["USD","IRT"]},"decimals":{"type":"integer"},"source":{"type":"string","example":"goldapi"},"computed":{"type":"boolean","description":"true یعنی ارزش محاسبه‌ای است، نه قیمت بازار"},"pro_only":{"type":"boolean"},"is_market_price":{"type":"boolean","description":"فقط در ردیف‌های محاسبه‌ای، همیشه false"},"label_fa":{"type":"string"},"disclaimer_fa":{"type":"string"}}},{"type":"object","properties":{"price":{"type":"number","nullable":true,"description":"null یعنی هنوز قیمتی ثبت نشده است (status = no_data)"},"bid":{"type":"number","nullable":true},"ask":{"type":"number","nullable":true},"change_24h":{"type":"number","nullable":true},"change_pct_24h":{"type":"number","nullable":true},"as_of":{"type":"string","format":"date-time","nullable":true},"stale":{"type":"boolean"},"status":{"type":"string","enum":["ok","no_data"]}}}]},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"پارامتر نادرست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نیست یا نادرست است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دامنه یا IP مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف دقیقه‌ای یا سهمیهٔ روزانه پر شده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"این نماد فقط در طرح پرو است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"نماد در این API نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/convert":{"get":{"summary":"تبدیل","description":"تبدیل میان هر دو نماد، و IRT و IRR، با نرخ میانه و از راه تومان.","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","example":"XAU"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","example":"IRT"}},{"name":"amount","in":"query","schema":{"type":"number","default":1}}],"responses":{"200":{"description":"نتیجهٔ تبدیل","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"amount":{"type":"number"},"rate":{"type":"number"},"result":{"type":"number"},"side":{"type":"string","enum":["mid"]}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"پارامتر نادرست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نیست یا نادرست است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دامنه یا IP مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف دقیقه‌ای یا سهمیهٔ روزانه پر شده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"برای این نماد هنوز قیمتی ثبت نشده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history/{symbol}":{"get":{"summary":"تاریخچهٔ روزانه","description":"فقط از داده‌ای که خودمان روزبه‌روز ذخیره کرده‌ایم. طرح رایگان: 30 روز بسته‌شدهٔ اخیر (بدون امروز)؛ پرو: همه، با شمع امروز. تاریخچهٔ ارزها در /api/fx/v1/history است.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","example":"XAU"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["1d","1w","1M"],"default":"1d"}}],"responses":{"200":{"description":"شمع‌های روزانه، هفتگی یا ماهانه","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"asset_class":{"type":"string"},"quote_currency":{"type":"string"},"computed":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"روز (به وقت تهران)؛ در 1w و 1M نخستین روز آن بازه"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"پارامتر نادرست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نیست یا نادرست است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دامنه یا IP مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف دقیقه‌ای یا سهمیهٔ روزانه پر شده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"همان کلید API نرخ ارز (fx-ntz-v1-…)"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"unknown_symbol"},"message":{"type":"string"},"status":{"type":"integer","example":404},"docs":{"type":"string","format":"uri"}}}}},"Meta":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","description":"زمان تازه‌ترین عدد این پاسخ"},"delayed_minutes":{"type":"integer","example":15,"description":"طرح رایگان: تأخیر نسبت به عدد زنده؛ پرو: ۰"},"is_delayed":{"type":"boolean"},"stale":{"type":"boolean","description":"true یعنی منبع دست‌کم یک نماد دیر به‌روز شده است؛ as_of همان زمان واقعی است"},"plan":{"type":"string","enum":["free","pro"]},"usd_irt":{"type":"integer","description":"نرخ بازار دلار به تومان که تبدیل‌ها از آن ساخته می‌شود"},"sources":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","example":"goldapi"},"name":{"type":"string","example":"gold-api.com"},"url":{"type":"string","format":"uri","nullable":true}}},"description":"منبع هر عدد. نام منبع را کنار داده نشان دهید."},"skipped":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"reason":{"type":"string","enum":["unknown","pro_required"]}}},"description":"نمادهایی که خواسته بودید و در پاسخ نیامده‌اند"},"computed_notice":{"type":"object","description":"فقط وقتی پاسخ ارزش محاسبه‌ای دارد. این برچسب و توضیح را هر جا عدد را نشان می‌دهید کنارش بیاورید.","properties":{"label_fa":{"type":"string","example":"ارزش محاسبه‌ای"},"disclaimer_fa":{"type":"string","example":"ارزش محاسبه‌ای از انس جهانی طلا و دلار نِت اَرز به دست می‌آید؛ قیمت بازار تهران نیست و حباب و اجرت در آن حساب نشده است."},"label_en":{"type":"string","example":"Computed value"},"disclaimer_en":{"type":"string"}}}}}}}}