Belgeler Veri

analyze_external_data

analyze_external_data, bağlı bir kaynaktan alınan piyasa verisini köken bilgisiyle doğrulayıp deterministik olarak analiz eden BorsaMCP aracıdır. Bir istek veri türü, köken ve kayıtlar taşır; en fazla 5.000 kayıt kabul edilir ve köken eksikse analiz yapılmaz.

Bu sayfa ileri düzey başvuru içindir. Normal kullanımda isteği Claude hazırlar; senin JSON yazman gerekmez.

İstek alanları

Alan	Zorunlu	Açıklama
`datasetType`	Evet	Veri türü: EQUITY_BARS, EQUITY_QUOTE, DERIVATIVES, BROKER_FLOW, ORDER_BOOK, FX.
`provenance`	Evet	Köken nesnesi (aşağıda).
`records`	Evet	Kanonik alanlarla kayıt dizisi, 1 ile 5.000 arası.
`analysis`	Hayır	İstenen analiz; verilmezse veri türünün varsayılanı çalışır.

Köken alanları

Köken, sonucun neye dayandığını söyler: bu hangi veri, nereden geldi, ne zaman gözlendi, hangi dönemi temsil ediyor ve ne kadar taze. Sekiz alan zorunludur; biri eksikse doğrulama INSUFFICIENT_PROVENANCE olur ve analiz yapılmaz.

Alan	Zorunlu	Anlamı
`source`	Evet	Verinin kaynağı (ör. bağlı veri kaynağının adı).
`sourceType`	Evet	Kaynak türü: USER_EXTERNAL_PROVIDER, PUBLIC, CENTRAL, PROXY.
`observedAt`	Evet	Verinin gözlendiği/alındığı an (ISO 8601).
`effectiveAt`	Evet	Verinin temsil ettiği an ya da dönem (ISO 8601).
`timeliness`	Evet	Beyan edilen zaman seviyesi: REALTIME, DELAYED, DAILY, HISTORICAL, QUARTERLY, UNKNOWN.
`quality`	Evet	DIRECT (doğrudan) ya da PROXY (vekil).
`instrument`	Evet	Enstrüman ya da kontrat kodu (büyük harf, rakam, _ . - /).
`fieldsPresent`	Evet	Kayıtlarda bulunan alanların listesi.
`providerTimestamp`	Hayır	Sağlayıcının kendi zaman damgası. REALTIME için gerekir.
`currency`	Hayır	Para birimi (3 harf, ör. TRY).
`market`	Hayır	Piyasa.
`timezone`	Hayır	Saat dilimi.
`identityLevel`	Hayır	Aracı kurum akışında kimlik düzeyi.
`underlyingInstrument`	Hayır	Türevde dayanak enstrüman.

sourceType PROXY ise quality DIRECT olamaz (PROXY_CANNOT_BE_DIRECT).
Zaman alanları ISO 8601 olmalı; observedAt gelecekte olamaz (FUTURE_TIMESTAMP).
Tanınmayan köken alanları yok sayılır ve yanıtta ignoredFields içinde listelenir.

Kayıt alanları ve analizler

Veri türü	Zorunlu alanlar	Diğer alanlar	Analizler (varsayılan önce)
`EQUITY_BARS`	`timestamp` `close`	`open` sayı `high` sayı `low` sayı `volume` sayı `turnover` sayı `indexClose` sayı	`summary` `volume`
`EQUITY_QUOTE`	`timestamp` `price`	`bid` sayı `ask` sayı `volume` sayı	`summary`
`DERIVATIVES`	`timestamp` `contractCode` `price`	`underlying` metin `expiry` metin `volume` sayı `openInterest` sayı `bid` sayı `ask` sayı `underlyingPrice` sayı	`summary` `basis` `openInterest`
`BROKER_FLOW`	`timestamp` `broker` `symbol` `direction` `identityLevel`	`volume` sayı `value` sayı `positionChange` sayı	`concentration`
`ORDER_BOOK`	`timestamp` `bids` `asks`		`liquidity`
`FX`	`timestamp` `pair` `rate`	`bid` sayı `ask` sayı `swapPoints` sayı `forward` sayı `impliedRate` sayı `tenor` metin	`summary`

Sayılar gerçek sayı olmalı; metin olarak gelen sayı dönüştürülmez: o alan kullanılmaz ve sonuç PARTIAL olur (INVALID_NUMBER).
Aynı anahtar ve zaman damgasıyla yinelenen kayıt kabul edilmez (DUPLICATE_TIMESTAMPS). Sırasız kayıtlar zamana göre sıralanır ve bu açıkça bildirilir.
Şemada olmayan sağlayıcıya özel alanlar analize girmez; ignoredFields içinde listelenir.
basis, summary ve openInterest tek kontratı değerlendirir: birden çok kontrat için her kontrat kendi kayıtlarıyla ayrı çağrılır.
basis aynı zaman damgasında underlyingPrice ister; openInterest en az iki zaman noktası; volume yeterli geçmiş ister, yoksa INSUFFICIENT_HISTORY döner.
concentration, kayıtları köken instrument değeriyle aynı symbol için değerlendirir.

Sınırlar

Kayıt sayısı: En fazla 5.000 kayıt.
Veri boyutu: Serileştirilmiş istek yaklaşık 2 MB'ı aşamaz (INPUT_TOO_LARGE).
Ham HTTP gövdesi: En fazla 4 MB; aşılırsa HTTP 413 payload_too_large.
Metin alanları: En fazla 64 karakter.

Sağlayıcının ham dökümünü değil, soruyu cevaplamak için gereken asgari veriyi gönder.

Örnek istek

Tek kontrat için geçmiş tarihli, doğrudan veriyle baz analizi. ORNEK_KONTRAT bir yer tutucudur. Gerçek istekte zaman alanları verinin gerçek zamanını taşır: gözlem anı gelecekte olamaz (FUTURE_TIMESTAMP); DELAYED ya da DAILY beyan edilen eski veri STALE döner.

{
  "datasetType": "DERIVATIVES",
  "analysis": "basis",
  "provenance": {
    "source": "bağlı veri kaynağı",
    "sourceType": "USER_EXTERNAL_PROVIDER",
    "observedAt": "2026-09-25T18:05:00+03:00",
    "effectiveAt": "2026-09-25T18:00:00+03:00",
    "timeliness": "HISTORICAL",
    "quality": "DIRECT",
    "instrument": "ORNEK_KONTRAT",
    "fieldsPresent": [
      "timestamp",
      "contractCode",
      "price",
      "underlyingPrice"
    ]
  },
  "records": [
    {
      "timestamp": "2026-09-25T18:00:00+03:00",
      "contractCode": "ORNEK_KONTRAT",
      "price": 101.25,
      "underlyingPrice": 100.4
    }
  ]
}

Sonuç

status: OK, PARTIAL (bazı kayıtlar ya da beyan edilen alanlar eksik) ya da STALE (veri tazelik sınırını aştı). Köken yetersizse UNAVAILABLE döner ve analiz yapılmaz.
acceptedTimeliness: Kabul edilen zaman seviyesi. Beyan edilenden düşük olabilir (ör. REALTIME → DELAYED).
validation: Kabul ve ret sayıları, sorun kodları, yok sayılan alanlar.
analysis: Analiz sonucu ve durumu: OK, NOT_EVALUABLE (gereken alan eksik), INSUFFICIENT_HISTORY, UNSUPPORTED_ANALYSIS ya da HARD_ARBITRAGE_NOT_EVALUABLE.
limitations: Sonucun sınırları: vekil veri, gecikme, bayatlık, doğrulanamayan kaynak.

Kendi verinle analiz hakkından yalnız analiz gerçekten üretildiğinde (analysis.status OK) 1 birim düşer. Sözleşme sürümü: external-data/1.0.0.

Doğrulama hataları

İsteğin tamamı reddedilir

Aşağıdaki durumlarda analiz yapılmaz, araç INVALID_INPUT döner ve kotadan düşmez.

Kod	Anlamı	Ne yapmalı
`SECRET_FIELD_REJECTED`	Kimlik bilgisi adlı bir alan var.	Alanı kaldır; kimlik bilgisi gönderme.
`INPUT_TOO_LARGE`	5.000 kayıt ya da yaklaşık 2 MB aşıldı.	Soruya gereken dönemi ve alanları gönder.
`UNKNOWN_DATASET_TYPE`	Veri türü tanınmıyor.	Altı veri türünden birini kullan.
`INVALID_TIMELINESS` · `INVALID_QUALITY`	Zaman seviyesi ya da nitelik geçersiz.	Listelenen değerlerden birini kullan.
`PROXY_CANNOT_BE_DIRECT`	Vekil kaynak doğrudan olarak beyan edildi.	quality PROXY olmalı.
`INVALID_PROVENANCE_TIMESTAMP` · `FUTURE_TIMESTAMP`	Köken zamanı ISO 8601 değil ya da gözlem anı gelecekte.	Zamanları verinin gerçek zamanıyla, ISO 8601 yaz.
`FORBIDDEN_IDENTITY_LEVEL`	Aracı kurum/saklamacı dışında kimlik düzeyi.	Yalnız BROKER ya da CUSTODIAN kullan.
`DUPLICATE_TIMESTAMPS`	Yinelenen kayıt.	Yinelenenleri çıkar.
`NO_RECORDS`	Kayıt yok ya da hiçbir kayıt geçerli değil.	Geçerli kayıt gönder.

Köken eksik

Zorunlu köken alanı eksikse (INSUFFICIENT_PROVENANCE) sonuç UNAVAILABLE olur ve analiz yapılmaz; kotadan düşmez.

Yalnız hatalı kayıt ya da alan çıkarılır

Tek tek kayıtlardaki sorunlar isteği reddetmez: sorunlu kayıt (REQUIRED_FIELD_MISSING) ya da alan (INVALID_NUMBER, INVALID_TIMESTAMP, INVALID_STRING) analize girmez, kalan kayıtlarla devam edilir ve sonuç PARTIAL olur. Kalan kayıtlarla analiz üretilirse (analysis.status OK) kendi verinle analiz hakkından 1 birim düşer. Kaç kaydın çıkarıldığı validation içinde yazar.