كيف تنتقل إلى بديل Alpha Vantage في Narwhal

من ينبغي أن ينتقل ومن ينبغي أن يبقى

ينتقل الفريق بسبب الترخيص والحصة. تقصر Alpha Vantage المفاتيح المجانية والمميزة على الاستخدام الشخصي غير التجاري ما لم تتفقوا على غير ذلك كتابةً، بينما يشمل كل حساب في Narwhal استخدام التطبيقات التجارية. يتيح مفتاح Alpha Vantage المجاني 25 طلبًا في اليوم؛ أما Narwhal فتمنح كل حساب رصيدًا مجانيًا قدره $10 شهريًا خلال أول 12 شهرًا من عمر الحساب. وتغطي سلاسل Alpha Vantage الاقتصادية الولايات المتحدة فقط، بينما تقرأ Narwhal البيانات الاقتصادية لـ37 دولة. كما يعمل مفتاح Narwhal الواحد عبر MCP، وهو مناسب لمشاريع الوكلاء.

ابقَ مع Alpha Vantage للمؤشرات الفنية والخيارات وتحليل مشاعر الأخبار. فهو يعرض سجلًا يوميًا يمتد 25 عامًا أو أكثر، بينما يعيد Narwhal السجل الكامل لكل سلسلة. وتغطي أسهم Narwhal 42 بورصة، وطوكيو ليست إحداها.

اربط كل function بنقطة نهاية

جرى استدعاء كل مسار أدناه بمفتاح فعلي في 3 نوفمبر 2026. ابحث عن السهم أولًا عبر /v1/equities/search، لأن معرّفات Narwhal تتضمن البورصة، كما في XNYS:IBM.

ما لا مقابل له في Narwhal

احتفظ بـ Alpha Vantage أو بمصدر آخر لهذه الأمور.

• المؤشرات الفنية، وهي 53 function مثل SMA وRSI وMACD.
• الخيارات، اللحظية والتاريخية على السواء.
• NEWS_SENTIMENT وIPO_CALENDAR.
• نطاق المؤشرات: يسرد INDEX_DATA 200 مؤشر أو أكثر، بينما يسعّر Narwhal 18 منها.

انقل ثلاثة استدعاءات

1. اضبط مفتاحك احصل على مفتاح مجاني واحفظه في NARWHAL_API_KEY. يقرأ Narwhal المفتاح من ترويسة Authorization: Bearer، لذا أزل apikey من كل عنوان URL.
2. استبدل استدعاء CPI يحدد مسار Narwhal الدولة ويعيد أحدث قيمة. وللحصول على السجل أضف /observations مع start وend، فيعيد قيم المؤشر نفسها التي يسردها Alpha Vantage.
   curl، CPI قبل الانتقال وبعده

   # Ran 2026-11-03: Alpha Vantage 200 OK with the demo key, Narwhal 200 OK both calls
   # Before: Alpha Vantage, CPI
   curl "https://www.alphavantage.co/query?function=CPI&interval=monthly&apikey=demo"
   
   # After: Narwhal, latest US CPI
   curl "https://api.narwhalapi.com/v1/economics/USA/cpi" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"
   
   # After: Narwhal, CPI for July to September
   curl -G \
     --url "https://api.narwhalapi.com/v1/economics/USA/cpi/observations" \
     -d start=2026-07 -d end=2026-09 \
     -H "Authorization: Bearer $NARWHAL_API_KEY"

3. استبدل استدعاءي السعر وأسعار الصرف يحدد Narwhal السهم بمعرّف الإدراج وسعر الصرف بالعملة الأساسية، مع وضع العملات المستهدفة في currencies.
   curl، السعر وأسعار الصرف قبل الانتقال وبعده

   # Ran 2026-11-03: Alpha Vantage quote 200 OK (demo key), Narwhal quote and FX 200 OK
   # Before: Alpha Vantage, last price for IBM
   curl "https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol=IBM&apikey=demo"
   
   # After: Narwhal, same stock (ids look like XNYS:IBM)
   curl "https://api.narwhalapi.com/v1/equities/XNYS:IBM/price" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"
   
   # Before: Alpha Vantage, USD to JPY (request taken from its documentation, not run)
   curl -G \
     --url "https://www.alphavantage.co/query" \
     -d function=CURRENCY_EXCHANGE_RATE -d from_currency=USD \
     -d to_currency=JPY -d apikey=YOUR_ALPHA_VANTAGE_KEY
   
   # After: Narwhal, USD to JPY
   curl "https://api.narwhalapi.com/v1/fx/rates/USD?currencies=JPY" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"

4. أعد كتابة المحلّل تفقد الحقول أرقامها وتصبح السلسلة مصفوفة. ينفذ السكربت الاستدعاءات الثلاثة كلها في Narwhal.
   Python، الاستدعاءات الثلاثة على Narwhal

   # Ran 2026-11-03: 200 OK for all three calls
   import os
   import requests
   
   session = requests.Session()
   session.headers["Authorization"] = f"Bearer {os.environ['NARWHAL_API_KEY']}"
   
   
   def get(path, **params):
       r = session.get("https://api.narwhalapi.com" + path, params=params, timeout=10)
       r.raise_for_status()
       return r.json()
   
   
   cpi = get("/v1/economics/USA/cpi")  # was function=CPI
   print(cpi["period"], cpi["value"])
   
   ibm = get("/v1/equities/search", q="IBM", country="USA")["results"][0]["id"]
   print(ibm, get(f"/v1/equities/{ibm}/price")["price"])  # was GLOBAL_QUOTE
   
   fx = get("/v1/fx/rates/USD", currencies="JPY")["rates"][0]  # was CURRENCY_EXCHANGE_RATE
   print(fx["currency"], fx["rate"])

5. قارن الناتج شغّل المزوّدين على المدخلات نفسها. مؤشر أسعار المستهلك الأمريكي لشهر 2026-09 هو 336.940 عند كليهما، وإغلاق IBM في 2 نوفمبر هو 252.51 عند كليهما.

كيف تختلف الاستجابات

يضع Alpha Vantage سعر الصرف متداخلًا تحت Realtime Currency Exchange Rate بمفاتيح مرقمة. أما Narwhal فيعيد مصفوفة rates فيها كائن لكل عملة.

{
  "name": "Consumer Price Index for all Urban Consumers",
  "interval": "monthly",
  "unit": "index 1982-1984=100",
  "data": [
    { "date": "2026-09-01", "value": "336.940" },
    { "date": "2026-08-01", "value": "334.980" }
  ]
}

{
  "country": "USA",
  "period": "2026-09",
  "value": "336.940",
  "index_base": "1982-84=100",
  "released_on": "2026-10-14"
}

{
  "Global Quote": {
    "01. symbol": "IBM",
    "05. price": "252.5100",
    "07. latest trading day": "2026-11-02",
    "08. previous close": "257.8100",
    "10. change percent": "-2.0558%"
  }
}

{
  "id": "XNYS:IBM",
  "symbol": "IBM",
  "currency": "USD",
  "price": "252.51",
  "previous_close": "257.81",
  "change_percent": "-2.06",
  "market_session": "closed",
  "timestamp": "2026-11-02T21:00:00Z",
  "stale": false
}

التعامل مع حدود المعدل

يسمح مفتاح Alpha Vantage المجاني بـ 25 طلبًا في اليوم. وتتراوح خططه المدفوعة من 75 إلى 1,200 طلب في الدقيقة دون حد يومي، ابتداءً من $49.99 شهريًا. ويسمح Narwhal بـ 50 طلبًا في الدقيقة على الرصيد المجاني و500 في الدقيقة بعد أن يصبح لديك رصيد مدفوع، وتكلف الاستدعاءات من $2 إلى $10 لكل 1,000.

يبلّغ Alpha Vantage عن المشكلات داخل استجابة 200، فيفوتك الفحص المعتمد على رمز الحالة وحده؛ وفي استدعاءات خارج أمثلته أعاد المفتاح التجريبي ملاحظة Information. يرد Narwhal بـ 429 rate_limit_exceeded عند الإرسال بسرعة زائدة: انتظر المدة في ترويسة Retry-After ثم أعد المحاولة. وعند نفاد رصيدك يرد بـ 402 insufficient_credits: أضف رصيدًا. ولا يُحتسب أي منهما. تحمل كل استجابة ناجحة X-RateLimit-Remaining وX-RateLimit-Reset. راجع التخزين المؤقت للاستجابات ومعالجة أخطاء 429 لمعرفة التفاصيل.

# 200 OK on both test calls; the 402 and 429 branches follow the documented codes
import os
import time
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NARWHAL_API_KEY']}"


def get(path, **params):
    for attempt in range(4):
        r = session.get("https://api.narwhalapi.com" + path, params=params, timeout=10)
        if r.status_code == 402:
            raise RuntimeError("Out of credit; add credit in the dashboard.")
        if r.status_code == 429:
            time.sleep(float(r.headers.get("Retry-After", 2)))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError(f"Gave up on {path}")

كيف أجد معرّف سهم؟

استدعِ /v1/equities/search?q=IBM&country=USA. تحتوي كل نتيجة على id مثل XNYS:IBM للأسعار والشموع، وعلى company_id مثل usa:0000051143 للبيانات المالية.

هل أستطيع إبقاء Alpha Vantage لبقية الأمور؟

نعم. يحتفظ كل مزوّد بمفتاحه وفوترته، لذا انقل العائلات المذكورة في الجدول واترك المؤشرات والخيارات والمعنويات حيث هي. يسرد مقارنة Narwhal مع Alpha Vantage الفروق الأخرى.

قائمة تحقق الانتقال

• اذكر كل function يستدعيها كودك وضع علامة عليها مقابل الجدول.
• حوّل رموز الأسهم إلى معرّفات إدراج مرة واحدة واحفظ المعرّفات.
• انقل المفتاح إلى ترويسة Bearer وأزله من عناوين URL المسجّلة.
• أعد كتابة المحلّلات لتناسب الأسماء البسيطة والمصفوفات المرتبة من الأقدم والأرقام النصية.
• استبدل فحص Information بفحص الحالة وcode.
• تأكد من تعريف الناتج المحلي الإجمالي وسعر الفائدة على الأموال الفيدرالية قبل مقارنة الأرقام.
• أعد المحاولة وفق Retry-After وتوقف عند insufficient_credits.
• شغّل المزوّدين جنبًا إلى جنب وقارن القيم قبل أن تنتقل.