مرجع stocks API للأسهم

نظرة عامة

الأسعار وسجل الأسعار وأحداث الشركات والقيمة السوقية ونسب التقييم للأسهم المُدرجة. يتطلب كل طلب مفتاح Bearer، ويخصم REST وMCP من رصيد واحد.

معرّف رمز مُدرج هو رمز البورصة من أربعة أحرف، ثم نقطتان رأسيتان، ثم رمز التداول، مثل XNAS:MSFT أو XNYS:BRK.B. ويصلح أيضًا رمز أمريكي مجرد مثل MSFT إذا كان يشير إلى رمز مُدرج أمريكي واحد، وتتضمن كل استجابة المعرّف المعتمد. الأسعار والمبالغ سلاسل نصية عشرية.

يمكن أن يحمل كل رمز مُدرج company_id. وهو يربط الرمز المُدرج بالشركة في Filings API، فيلتقي السعر والتقييم والقوائم المالية عند معرّف واحد.

عنوان URL الأساسي: https://api.narwhalapi.com. أداة MCP هي equities, with one action لكل مسار أدناه.

A company_id يربط رمزًا مُدرجًا بـ واجهة الإفصاحات (Filings API): القوائم المالية والإيداعات والمالكون.

ما يحصل عليه كل حساب

راجع التسعير لمعرفة تكلفة الاستدعاء. يُحاسَب الطلب بسعر واجهته ما لم يذكر المسار خلاف ذلك.

• يغطي التقييم الرموز المُدرجة في الولايات المتحدة وكوريا التي تطابق شركة في بياناتنا المودعة. تعرض كوريا P/E فقط حاليًا.
• تُحذف النسبة التي يتعذر حسابها بشكل صحيح، ولا تُرسل أبدًا على أنها 0.
• قيمة eps_actual في الأرباح مبنية على أساس بيانات السوق، أما ربحية السهم EPS خلف pe_ratio فمصدرها إيداعات الشركة. قد يختلف الرقمان، فلا تقارن بينهما مباشرة.
• تغطي تكلفة رأس المال الرموز المُدرجة في الولايات المتحدة وكوريا التي تطابق شركة في بياناتنا المودعة. ترسل علاوة مخاطر الأسهم الخاصة بك في erp. وقد كُتبت الطريقة مرة واحدة في منهجية تكلفة رأس المال، وتربط كل استجابة بها.
• يعيد البنك أو شركة التأمين الخطأ 422 not_applicable، لأن الفائدة تكلفة تشغيلية لديهما. ويُذكر أي مدخل يتعذر حسابه في 422 inputs_unavailable، ولا يُملأ أبدًا.
• يتضمن سجل التقييم نقطة واحدة لكل نهاية فترة مالية (نهاية ربع أو سنة)، وليس نقطة لكل يوم. تستخدم كل نقطة الإغلاق في ذلك اليوم أو قبله مباشرة، معدّلًا لتجزئات الأسهم فقط، والأرقام كما أُودعت لتلك الفترة.
• الأرباح هي النتائج السابقة فقط. مواعيد الأرباح القادمة غير متاحة بعد.
• تحمل الملفات التعريفية لليابان الاسم والبورصة والدولة والعملة وcompany_id فقط.

نقاط النهاية

كل مسار هو طلب GET ويحتاج إلى مفتاحك في: Authorization: Bearer الترويسة. تعرض الأمثلة شكل الاستجابة، وليست بيانات مباشرة.

البحث عن الأسهم برمز التداول أو الاسم

GET /v1/equities/search

الرموز المُدرجة التي يبدأ رمز تداولها أو اسمها بـ q، بأي حالة أحرف: رمز التداول المطابق تمامًا أولًا، ثم رموز التداول الأخرى، ثم الأسماء. مرشحان اختياريان هما country (ثلاثة أحرف) وtype. حتى 50 نتيجة في الصفحة، مع next_cursor. تُقرأ النتائج من قائمة الرموز لدينا، لذا فهي متاحة لكل حساب وتُحتسب كاستدعاء واحد.

MCP: الأداة equities, action search.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/search?q=micro"

{
  "results": [
    {
      "id": "XNAS:MSFT",
      "symbol": "MSFT",
      "name": "Microsoft Corporation",
      "type": "common_stock",
      "mic": "XNAS",
      "country": "USA",
      "currency": "USD",
      "company_id": "usa:0000789019"
    }
  ],
  "next_cursor": null
}

الملف التعريفي لسهم واحد

GET /v1/equities/{id}

الرمز المُدرج (الرمز والاسم والنوع والبورصة والدولة والعملة)، وقطاع الشركة ونشاطها وموقعها الإلكتروني، وcompany_id عندما يطابق الرمز المُدرج شركة في بياناتنا المودعة. متاح لكل حساب. تحمل الرموز المُدرجة في اليابان الاسم والبورصة والدولة والعملة وcompany_id فقط. تُحذف الحقول غير المعروفة.

MCP: الأداة equities, action profile.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT"

{
  "id": "XNAS:MSFT",
  "symbol": "MSFT",
  "name": "Microsoft Corporation",
  "type": "common_stock",
  "mic": "XNAS",
  "country": "USA",
  "currency": "USD",
  "sector": "Technology",
  "industry": "Software",
  "website": "https://www.microsoft.com",
  "company_id": "usa:0000789019"
}

آخر سعر لسهم واحد

GET /v1/equities/{id}/price

آخر سعر لرمز مُدرج واحد. تُعطى change_percent بالنسبة المئوية. المعرّف غير المعروف يعيد 404 not_found، والسوق الذي لا أسعار له بعد يعيد 404 not_covered.

MCP: الأداة equities, action price.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/price"

{
  "id": "XNAS:MSFT",
  "symbol": "MSFT",
  "currency": "USD",
  "price": "421.35",
  "previous_close": "418.90",
  "change": "2.45",
  "change_percent": "0.58",
  "volume": "18234100",
  "market_session": "open",
  "timestamp": "2026-10-26T15:42:00Z",
  "stale": false
}

آخر أسعار لما يصل إلى 50 سهمًا

GET /v1/equities/prices

آخر سعر لكل معرّف مذكور. يُحتسب استدعاء واحد لكل معرّف يعيد سعرًا، ويُخصم في خطوة واحدة: إذا لم يكفِ رصيدك لتغطية المعرّفات التي حُلّت، يُرفض الطلب كله مع 402 insufficient_credits. المعرّفات التي لا تعيد سعرًا تُدرج في errors ولا تكلّف شيئًا. تُعطى change_percent بالنسبة المئوية.

أرسل حتى 50 معرّفًا. تُحاسَب الدفعة في خطوة واحدة: إذا لم يكفِ رصيدك لتغطية المعرّفات التي تُحل، يعيد الطلب كله 402 insufficient_credits.

MCP: الأداة equities, action prices.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/prices?ids=XNAS:MSFT,XNAS:NVDA"

{
  "prices": [
    {
      "id": "XNAS:MSFT",
      "symbol": "MSFT",
      "currency": "USD",
      "price": "421.35",
      "previous_close": "418.90",
      "change": "2.45",
      "change_percent": "0.58",
      "volume": "18234100",
      "market_session": "open",
      "timestamp": "2026-10-26T15:42:00Z",
      "stale": false
    },
    {
      "id": "XNAS:NVDA",
      "symbol": "NVDA",
      "currency": "USD",
      "price": "188.20",
      "previous_close": "187.10",
      "change": "1.10",
      "change_percent": "0.59",
      "volume": "152003400",
      "market_session": "open",
      "timestamp": "2026-10-26T15:42:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XNAS:NOPE",
      "code": "not_found"
    }
  ]
}

أكثر الأسهم الأمريكية حركة

GET /v1/equities/movers

أعلى 25 سهمًا وصندوق ETF أمريكيًا بحسب direction: gainers أو losers أو active (الأكثر تداولًا بالقيمة بين أكبر الرابحين والخاسرين في اليوم، وليس السوق كله). تُشمل الأسهم العادية وصناديق ETF فقط التي يبلغ سعرها $1 أو أكثر، وتداول منها اليوم 100,000 سهم على الأقل بقيمة $1 مليون على الأقل. نحن من يرتّبها وتُخزَّن مؤقتًا لمدة 10 دقائق. تُعطى change_percent بالنسبة المئوية. قيمة market هي us حاليًا، وأي سوق آخر يعيد 404 not_covered، وdirection غير المعروفة تعيد 400 invalid_query. استدعاء واحد.

الأسهم الأكثر حركة متاحة للولايات المتحدة فقط. أي سوق آخر يعيد 404 not_covered.

MCP: الأداة equities, action movers.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/movers?market=us&direction=gainers"

{
  "market": "us",
  "direction": "gainers",
  "movers": [
    {
      "id": "XNAS:NVDA",
      "symbol": "NVDA",
      "name": "NVIDIA Corporation",
      "price": "188.20",
      "change_percent": "4.12",
      "volume": "152003400"
    }
  ],
  "timestamp": "2026-10-26T15:42:00Z"
}

شموع أسعار سهم واحد

GET /v1/equities/{id}/bars

شموع يومية (1d) أو بدقيقة واحدة (1m)، الأقدم أولًا، معدّلة لتجزئات الأسهم والتوزيعات. السجل: كامل لكل حساب. تمتد شموع الدقيقة الواحدة إلى عام 2020 وتغطي 5 أيام كحد أقصى في الاستدعاء الواحد (400 range_too_large). تظهر شمعة اليوم اليومية بعد إغلاق البورصة. حتى 5,000 شمعة في الصفحة، مع next_cursor؛ والمؤشر الذي لم يعد يطابق الأسعار يعيد 409 cursor_expired. استدعاء واحد لكل صفحة.

الشموع معدّلة لتجزئات الأسهم والتوزيعات. إذا غيّرت تجزئة أو توزيعة السجل بين صفحتين، يتوقف المؤشر عن العمل ويعيد 409 cursor_expired.

MCP: الأداة equities, action bars.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/bars?interval=1d&start=2026-10-01"

{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "adjusted": true,
  "bars": [
    {
      "date": "2026-10-23",
      "timestamp": "2026-10-23T13:30:00Z",
      "open": "417.10",
      "high": "420.55",
      "low": "415.80",
      "close": "418.90",
      "volume": "21034500"
    }
  ],
  "next_cursor": null
}

توزيعات أرباح سهم واحد

GET /v1/equities/{id}/dividends

التوزيعات النقدية لرمز مُدرج واحد، الأحدث بحسب تاريخ الاستحقاق أولًا، مقسّمة إلى صفحات. قد تتضمن القائمة صفوفًا مستقبلية معلنة. يحصل كل حساب على السجل الكامل. لا تُقتطع الصفوف القادمة أبدًا. يُحتسب كل طلب استدعاء واحدًا. المعرّف غير المعروف يعيد 404 not_found، والسوق الذي لا بيانات له بعد يعيد 404 not_covered.

MCP: الأداة equities, action dividends.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/dividends"

{
  "id": "XNAS:MSFT",
  "dividends": [
    {
      "ex_date": "2026-08-20",
      "amount": "0.91",
      "currency": "USD",
      "pay_date": "2026-09-10",
      "record_date": "2026-08-20"
    }
  ],
  "next_cursor": null
}

تجزئات أسهم سهم واحد

GET /v1/equities/{id}/splits

تجزئات الأسهم لرمز مُدرج واحد، الأحدث أولًا. يحصل كل حساب على السجل الكامل. لا تُقتطع الصفوف القادمة أبدًا. يُحتسب كل طلب استدعاء واحدًا. المعرّف غير المعروف يعيد 404 not_found، والسوق الذي لا بيانات له بعد يعيد 404 not_covered.

MCP: الأداة equities, action splits.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:NFLX/splits"

{
  "id": "XNAS:NFLX",
  "splits": [
    {
      "date": "2025-11-17",
      "ratio": "10:1"
    }
  ]
}

أرباح سهم واحد

GET /v1/equities/{id}/earnings

تقارير الأرباح السابقة لرمز مُدرج واحد (المؤرخة اليوم أو قبله بتوقيت البورصة)، مع التقدير والفعلي والمفاجأة، الأحدث أولًا، مقسّمة إلى صفحات. مواعيد التقارير القادمة غير متاحة بعد. تُعطى surprise_percent بالنسبة المئوية. قيمة eps_actual مبنية على أساس بيانات السوق وقد تختلف عن ربحية السهم EPS من الإيداعات في التقييم. يسمّي filing_id التقرير السنوي أو الربعي الذي يغطي تقريرًا سابقًا عندما يكون لدينا. يحصل كل حساب على السجل الكامل. يُحتسب كل طلب استدعاء واحدًا. المعرّف غير المعروف يعيد 404 not_found، والسوق الذي لا بيانات له بعد يعيد 404 not_covered.

يعيد هذا المسار التقارير السابقة فقط. مواعيد التقارير القادمة غير متاحة بعد.

يربط filing_id التقرير السابق بالإيداع الذي يغطيه. مرّره إلى GET /v1/filings/{filing_id} في Filings API.

MCP: الأداة equities, action earnings.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/earnings"

{
  "id": "XNAS:MSFT",
  "earnings": [
    {
      "date": "2026-07-29",
      "time": "after_close",
      "eps_estimate": "3.31",
      "eps_actual": "3.45",
      "surprise": "0.14",
      "surprise_percent": "4.23",
      "filing_id": "usa:0000789019:0000950170-26-000123"
    }
  ],
  "next_cursor": null
}

القيمة السوقية وP/E وP/S وP/B وعائد التوزيعات لسهم واحد

GET /v1/equities/{id}/valuation

القيمة السوقية (آخر سعر مضروبًا في الأسهم القائمة)، وP/E (آخر سعر مقسومًا على ربحية السهم المخففة لآخر 12 شهرًا من إيداعات الشركة، وفق GAAP أو IFRS كما أُعلنت)، وP/S (القيمة السوقية مقسومة على إيرادات آخر 12 شهرًا)، وP/B (القيمة السوقية مقسومة على إجمالي حقوق الملكية في أحدث ميزانية عمومية)، وعائد التوزيعات (توزيعات السهم لآخر 12 شهرًا مقسومة على السعر، بالنسبة المئوية) لرمز مُدرج واحد أمريكي أو كوري، مع المدخلات وتواريخها. تتوفر لكوريا P/E فقط حاليًا؛ وتأتي القيمة السوقية وP/S وP/B والعائد مع أعداد الأسهم والتوزيعات. تُحذف أي قيمة يتعذر حسابها بشكل صحيح ولا تُرسل أبدًا على أنها 0: القيمة السوقية بعد تجزئة منذ تاريخ عدد الأسهم، وللشركات ذات فئات الأسهم المتعددة التي لا يتوفر عدد لكل فئة منها، ولإيصال الإيداع أو المُصدر الأجنبي؛ وP/E عندما تكون ربحية السهم سالبة أو أقل من 0.01، أو معلنة بعملة أخرى، أو لإيصال الإيداع. الفئة الأخرى من أسهم الشركة، مثل سهم الأفضلية، لا أرقام لها وتظهر دونها. الرمز المُدرج خارج الولايات المتحدة وكوريا، أو الذي لا يطابق شركة مطابقة واضحة، يعيد 404 not_covered. استدعاء واحد.

تأتي كل نسبة مع مدخلاتها وتواريخها: shares_as_of وeps_period_end وrevenue_period_end وequity_as_of وdividends_period_end.

MCP: الأداة equities, action valuation.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/valuation"

{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "market_cap": "3130000000000",
  "pe_ratio": "33.50",
  "ps_ratio": "11.40",
  "pb_ratio": "10.20",
  "dividend_yield": "0.86",
  "shares_outstanding": "7430000000",
  "shares_as_of": "2026-07-24",
  "eps_ttm": "12.58",
  "eps_period_end": "2026-06-30",
  "revenue_ttm": "274500000000",
  "revenue_period_end": "2026-06-30",
  "total_equity": "307000000000",
  "equity_as_of": "2026-06-30",
  "dividend_per_share_ttm": "3.64",
  "dividends_period_end": "2026-06-30",
  "company_id": "usa:0000789019",
  "timestamp": "2026-10-26T15:42:00Z"
}

بيتا وتكلفة حقوق الملكية وتكلفة الدين وWACC لسهم واحد

GET /v1/equities/{id}/cost-of-capital

بيتا لسهم أمريكي أو كوري واحد مقابل صندوق ETF مرجعي (عوائد أسبوعية على مدى عامين افتراضيًا، من أسعار معدّلة لتجزئات الأسهم والتوزيعات)، والعائد الخالي من المخاطر (نقطة العشر سنوات من منحنى عائد السندات الحكومية للدولة، أو قيمتك)، وتكلفة حقوق الملكية (العائد الخالي من المخاطر مضافًا إليه بيتا مضروبة في علاوة مخاطر الأسهم: علاوتك في erp، أو افتراضيًا علاوتنا الإجمالية المنشورة لدولة السهم)، وتكلفة الدين (مصروف الفائدة مقسومًا على متوسط إجمالي الدين من إيداعات الشركة، أو، حيث يتعذر استخدام ذلك، العائد الخالي من المخاطر مضافًا إليه الهامش الافتراضي من جدول عام بحسب تغطية الشركة للفوائد؛ قبل الضريبة وبعدها، مع معدل ضريبة الشركات للدولة من جدول عام ما لم ترسل tax_rate) وWACC، موزونة بالقيمة السوقية وإجمالي الدين. يرد كل مدخل في الاستجابة مع قيمته وأساسه وتاريخه. البنوك وشركات التأمين تعيد 422 not_applicable؛ والمدخل الذي يتعذر حسابه بشكل صحيح يُذكر في 422 inputs_unavailable ولا يُصحَّح أبدًا؛ والرقم الذي يظهر لكنه يحتاج إلى حذر يأتي مع عنصر في warnings. استدعاء واحد.

erp مطلوب. ليس لكوريا منحنى عائد هنا، لذا أرسل risk_free للسهم الكوري. يأتي كل مدخل مع قيمته وتاريخه، وتسرد warnings الأرقام التي يجب التحقق منها قبل الاعتماد عليها.

MCP: الأداة equities, action cost_of_capital.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/cost-of-capital?erp=5"

{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "company_id": "usa:0000789019",
  "beta": {
    "benchmark": {
      "id": "ARCX:SPY",
      "default": true
    },
    "window": "2y",
    "frequency": "weekly",
    "start": "2024-10-25",
    "end": "2026-10-16",
    "observations": 103,
    "raw": "1.0842",
    "adjusted": "1.0564",
    "used": "raw",
    "r_squared": "0.5731",
    "std_error": "0.0894"
  },
  "risk_free": {
    "rate": "4.1200",
    "source": "yield_curve",
    "basis": "ours",
    "country": "USA",
    "maturity": "10y",
    "curve_type": "nominal_par",
    "as_of": "2026-10-22"
  },
  "equity_risk_premium": {
    "rate": "5.0000",
    "source": "caller"
  },
  "cost_of_equity": "9.5410",
  "cost_of_debt": {
    "pre_tax": "3.9100",
    "basis": "ours",
    "after_tax": "2.9078",
    "period": "ttm",
    "period_end": "2026-06-30",
    "interest_expense": "2900000000",
    "average_debt": "74200000000",
    "opening_debt": "72000000000",
    "closing_debt": "76400000000"
  },
  "tax_rate": {
    "rate": "25.6300",
    "source": "country_table",
    "basis": "table",
    "country": "USA",
    "table": "Damodaran, corporate marginal tax rates by country (PwC, January 2026 update)",
    "table_update": "January 2026",
    "table_url": "https://pages.stern.nyu.edu/~adamodar/New_Home_Page/datafile/countrytaxrates.html"
  },
  "weights": {
    "equity": "98.0000",
    "debt": "2.0000",
    "market_cap": "3893412000000",
    "market_cap_as_of": "2026-10-26T15:42:00Z",
    "total_debt": "76400000000",
    "total_debt_as_of": "2026-06-30"
  },
  "wacc": "9.4083",
  "warnings": [],
  "methodology_url": "https://narwhalapi.com/methodology/cost-of-capital"
}

سجل التقييم لسهم واحد

GET /v1/equities/{id}/valuation/history

القيمة السوقية وP/E وP/S وP/B وعائد التوزيعات عند كل نهاية فترة مالية (نهاية ربع أو سنة) لرمز مُدرج واحد أمريكي أو كوري، الأقدم أولًا. كل نقطة هي سعر الإغلاق في ذلك اليوم أو قبله مباشرة، معدّلًا لتجزئات الأسهم فقط، والأرقام المودعة لتلك الفترة (ربحية السهم والإيرادات والتوزيعات لآخر 12 شهرًا، وإجمالي حقوق الملكية، وأقرب عدد للأسهم)، فيدخل فيها أي إعادة بيان لاحقة. تُحذف أي قيمة يتعذر حسابها ولا تُرسل أبدًا على أنها 0، وفق قواعد التقييم نفسها. السجل: كامل لكل حساب. الرمز المُدرج خارج الولايات المتحدة وكوريا، أو الذي لا يطابق شركة مطابقة واضحة، يعيد 404 not_covered. استدعاء واحد.

MCP: الأداة equities, action valuation_history.

المعلمات

حقول الاستجابة

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/valuation/history"

{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "company_id": "usa:0000789019",
  "points": [
    {
      "date": "2026-06-30",
      "price": "497.40",
      "price_date": "2026-06-30",
      "market_cap": "3697000000000",
      "pe_ratio": "39.54",
      "ps_ratio": "13.47",
      "pb_ratio": "12.04",
      "dividend_yield": "0.73"
    }
  ]
}

الأخطاء

تستخدم الأخطاء بنية المشكلة المشتركة مع: request_id. راجع أخطاء API والرصيد لمعرفة الشكل وترويسات الرصيد. لا تُحاسَب الطلبات الفاشلة.