{"openapi":"3.1.0","info":{"title":"NORTH7 Agent API","summary":"Real-time AI-analyzed trading signals, risk assessment, and market intelligence for autonomous agents.","description":"## Financial Intelligence Infrastructure for AI Agents\n\nNORTH7 provides **decision-ready market intelligence** — not raw data. Every signal comes with AI-generated confidence scores, reasoning, and context.\n\n### Free Endpoints (no API key needed)\n- `GET /v1/risk` — Global risk index 0-100 with active crises\n- `GET /v1/regime` — Market regime: BULL / BEAR / SIDEWAYS / CRISIS\n- `GET /v1/health` — API status and data freshness\n\n### Agent Integration\n- **MCP Server**: `https://north7.ai/mcp` (9 tools)\n- **A2A Agent Card**: `https://north7.ai/.well-known/agent.json`\n- **AI Plugin**: `https://north7.ai/.well-known/ai-plugin.json`\n\n### How to Use\nNORTH7 provides AI-analyzed financial intelligence, NOT raw market data. Use /v1/risk and /v1/regime FIRST to assess market conditions before requesting signals. The risk index (0-100) tells you whether to be cautious; the regime (BULL/BEAR/SIDEWAYS/CRISIS) tells you the current market phase. Then use /v1/signals/latest for actionable trade signals. All signal endpoints return a 'confidence' score (0-1) and a 'reason' in English. Rate limits are returned in response headers (X-RateLimit-Remaining). FREE endpoints (/v1/risk, /v1/regime, /v1/health) require NO API key — use them anytime. For authenticated endpoints, pass your key via the X-API-Key header. Credits are deducted per call (most cost 1-2 credits). Check /v1/account for balance.\n\n### Pricing\n| Tier | Credits | Rate Limit | Price |\n|------|---------|------------|-------|\n| Free | 1,000 | 10/min | Free |\n| Starter | 50,000 | 60/min | 5 EUR |\n| Pro | 500,000 | 300/min | 25 EUR |\n| Enterprise | Unlimited | 1,000/min | Custom |\n","contact":{"name":"NORTH7 Support","url":"https://north7.ai/developers","email":"support@north7.ai"},"license":{"name":"Proprietary","url":"https://north7.ai/disclaimer"},"version":"1.0.0"},"paths":{"/v1/risk":{"get":{"tags":["Free"],"summary":"Global Market Risk Index","description":"Returns the global market risk index (0-100) with active crises and regional breakdown. **NO API KEY REQUIRED** — call this anytime to assess market conditions.\n\nUSE THIS ENDPOINT to determine whether market conditions are favorable for trading. Risk > 70 means elevated risk, consider reducing exposure. Risk > 85 means crisis-level risk, defensive positioning recommended.\n\nThe response includes:\n- `value`: Risk score 0-100\n- `status`: CALM / MODERATE / ELEVATED / CRITICAL\n- `crises`: List of active global crises affecting markets\n- `regions`: Per-region risk scores (Middle East, Europe, Asia etc.)\n\nData sources: GDELT geopolitical event database, Yahoo Finance volatility data, USGS seismic data, weather/climate feeds. Updated every 30 minutes.","operationId":"getRiskIndex","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Risk data returned successfully","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/regime":{"get":{"tags":["Free"],"summary":"Market Regime Detection","description":"Detects the current market regime: **BULL**, **BEAR**, **SIDEWAYS**, or **CRISIS**. **NO API KEY REQUIRED** — call this anytime.\n\nUSE THIS ENDPOINT to determine the market phase before making trading decisions. Based on S&P 500 position relative to its 200-day moving average and VIX volatility level.\n\nInterpretation:\n- **BULL**: SPX above 200d MA, VIX calm — favor long positions\n- **BEAR**: SPX below 200d MA — favor short/defensive positions\n- **SIDEWAYS**: Mixed signals — reduce position sizes\n- **CRISIS**: VIX spike + rapid decline — cash/hedging recommended\n\nThe response includes SPX value, 200d MA, VIX level, and reasoning.","operationId":"getMarketRegime","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Current market regime with reasoning","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/health":{"get":{"tags":["Free"],"summary":"API Health Check","description":"Returns API health status and data freshness. **NO API KEY REQUIRED.**\n\nUse this to verify that the API is operational and data is current before making trading decisions based on NORTH7 signals.","operationId":"getHealthStatus","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signals/latest":{"get":{"tags":["Signals"],"summary":"Get All Trading Signals","description":"Returns real-time trading signals from all 6 AI-powered sources. Each signal includes symbol, direction, confidence score (0-1), and AI-generated reasoning.\n\n**Signal Sources:**\n- `news_5m` — Breaking news analysis (every 10 min, Claude AI)\n- `alpha_14d` — Mid-term alpha screening (daily, fundamental + technical)\n- `radar_daily` — Stock radar picks (daily, momentum + quality)\n- `intraday_30m` — Intraday momentum scanner (every 30 min Mon-Fri)\n- `scr_daily` — Commodity scoring for 15 raw materials (daily)\n\n**How to use:** Call /v1/regime first to know the market phase. In a BULL regime, focus on long signals with confidence > 0.7. In BEAR, focus on short signals or defensive sectors.\n\nFilter by source with the `source` parameter to get only specific signal types.","operationId":"getTradingSignals","parameters":[{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by source: news_5m, alpha_14d, radar_daily, intraday_30m, scr_daily. Omit to get all sources.","title":"Source"},"description":"Filter by source: news_5m, alpha_14d, radar_daily, intraday_30m, scr_daily. Omit to get all sources."},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signals/alpha":{"get":{"tags":["Signals"],"summary":"Alpha Daily Signals","description":"AI-screened mid-term opportunities with 14-day outlook. These are the highest-conviction signals from fundamental + technical analysis.\n\nUpdated daily at 07:00 UTC. Each signal includes a quality score and detailed reasoning.","operationId":"getAlphaSignals","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/prices":{"get":{"tags":["Market"],"summary":"Real-Time Asset Prices","description":"Real-time prices for 80+ tracked assets including stocks, ETFs, commodities, and forex. Updated every 2 minutes from Yahoo Finance.\n\nUse the `symbols` parameter to request specific assets (comma-separated). Omit to get all tracked assets.\n\nExample: `/v1/prices?symbols=AAPL,MSFT,TSLA,GC=F,EURUSD=X`","operationId":"getAssetPrices","parameters":[{"name":"symbols","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated ticker symbols. Example: AAPL,MSFT,TSLA. Omit for all 80+ assets.","title":"Symbols"},"description":"Comma-separated ticker symbols. Example: AAPL,MSFT,TSLA. Omit for all 80+ assets."},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/prices/history":{"get":{"tags":["Market"],"summary":"365-Day Price History","description":"Historical daily prices for the last 365 days for a specific symbol. Use this for technical analysis, backtesting, or trend detection.\n\nExample: `/v1/prices/history?symbol=AAPL`","operationId":"getPriceHistory","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","description":"Ticker symbol. Example: AAPL, MSFT, GC=F","title":"Symbol"},"description":"Ticker symbol. Example: AAPL, MSFT, GC=F"},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analysis/{ticker}":{"get":{"tags":["Analysis"],"summary":"Deep AI Stock Analysis","description":"Comprehensive AI-generated analysis for a specific stock or asset. Includes fundamentals (P/E, revenue, margins), technicals, and AI assessment.\n\nNOT available for all tickers — only assets that have been analyzed. If analysis is not available, the response will include a 404 with hints.","operationId":"getStockAnalysis","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/portfolio/model":{"get":{"tags":["Portfolio"],"summary":"Model Portfolio Positions","description":"Current positions and performance of the NORTH7 model portfolio. Shows what the AI system is currently holding with direction and performance.","operationId":"getModelPortfolio","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/intelligence/briefing":{"get":{"tags":["Intelligence"],"summary":"Daily Intelligence Briefing","description":"AI-generated daily market intelligence briefing covering geopolitical events, market-moving news, and forward-looking analysis. Available in English and German.\n\nUpdated daily. Use `lang=de` for German, `lang=en` (default) for English.","operationId":"getIntelligenceBriefing","parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","description":"Language: 'en' for English (default), 'de' for German.","default":"en","title":"Lang"},"description":"Language: 'en' for English (default), 'de' for German."},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sector-radar":{"get":{"tags":["Analysis"],"summary":"Sector Rotation Radar","description":"Sector rotation analysis showing breadth and momentum across market sectors. Identifies which sectors are leading or lagging the broader market.\n\nUse this to identify sector trends and rotate into strong sectors.","operationId":"getSectorRadar","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/commodities":{"get":{"tags":["Signals"],"summary":"Commodity Signals","description":"AI scoring signals for 15 raw materials: gold, silver, oil, natural gas, wheat, corn, soybeans, coffee, cocoa, sugar, cotton, copper, platinum, palladium, lumber.\n\nIncludes seasonal patterns and AI-generated scoring. Updated daily at 06:00 UTC.","operationId":"getCommoditySignals","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/intraday":{"get":{"tags":["Signals"],"summary":"Intraday Momentum Scanner","description":"Intraday momentum signals updated every 30 minutes during market hours (Mon-Fri 08:00-21:00 UTC). Scans for short-term momentum breakouts and reversals.\n\n**Warning:** Intraday signals are time-sensitive. Check the `updated` timestamp and discard signals older than 1 hour.","operationId":"getIntradayScanner","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account":{"get":{"tags":["Account"],"summary":"API Key Status","description":"Check your API key status, remaining credits, and usage statistics. No credits deducted.","operationId":"getAccountInfo","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout/create":{"post":{"tags":["Checkout"],"summary":"Create PayPal Order","description":"Start a PayPal payment to purchase API credits.","operationId":"createCheckoutOrder","parameters":[{"name":"tier","in":"query","required":true,"schema":{"type":"string","description":"Tier: starter (5 EUR) or pro (25 EUR)","title":"Tier"},"description":"Tier: starter (5 EUR) or pro (25 EUR)"},{"name":"email","in":"query","required":false,"schema":{"type":"string","description":"Your email","default":"","title":"Email"},"description":"Your email"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout/capture":{"post":{"tags":["Checkout"],"summary":"Capture PayPal Payment & Get API Key","description":"After PayPal approval, capture payment and receive your API key.","operationId":"captureCheckoutOrder","parameters":[{"name":"order_id","in":"query","required":true,"schema":{"type":"string","description":"PayPal order ID","title":"Order Id"},"description":"PayPal order ID"},{"name":"name","in":"query","required":false,"schema":{"type":"string","description":"Name for your API key","default":"","title":"Name"},"description":"Name for your API key"},{"name":"email","in":"query","required":false,"schema":{"type":"string","description":"Your email","default":"","title":"Email"},"description":"Your email"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout/tiers":{"get":{"tags":["Checkout"],"summary":"Available Tiers & Pricing","description":"List tiers and pricing. No auth required.","operationId":"getCheckoutTiers","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/checkout/free":{"post":{"tags":["Checkout"],"summary":"Get Free API Key (1,000 credits)","description":"Get a free API key instantly with 1,000 credits. No payment required. Perfect for testing and evaluating the API. Rate limit: 10 requests/minute. One free key per email.","operationId":"getFreeApiKey","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"Your email address (required, one free key per email)","title":"Email"},"description":"Your email address (required, one free key per email)"},{"name":"name","in":"query","required":false,"schema":{"type":"string","description":"Name for your API key","default":"","title":"Name"},"description":"Name for your API key"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/keys":{"post":{"tags":["Admin"],"summary":"Create API Key","description":"Admin: Create a new API key for a developer or agent. Requires X-Admin-Token.","operationId":"adminCreateKey","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","description":"Name for the key, e.g. 'My Trading Agent'","title":"Name"},"description":"Name for the key, e.g. 'My Trading Agent'"},{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"Owner email for billing and notifications","title":"Email"},"description":"Owner email for billing and notifications"},{"name":"tier","in":"query","required":false,"schema":{"type":"string","description":"Tier: free, starter, pro, enterprise","default":"free","title":"Tier"},"description":"Tier: free, starter, pro, enterprise"},{"name":"X-Admin-Token","in":"header","required":false,"schema":{"type":"string","title":"X-Admin-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Admin"],"summary":"List All Keys","operationId":"adminListKeys","parameters":[{"name":"X-Admin-Token","in":"header","required":false,"schema":{"type":"string","title":"X-Admin-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/credits":{"post":{"tags":["Admin"],"summary":"Add Credits","description":"Admin: Add credits to an existing API key.","operationId":"adminAddCredits","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"The full API key to add credits to","title":"Api Key"},"description":"The full API key to add credits to"},{"name":"amount","in":"query","required":true,"schema":{"type":"integer","description":"Number of credits to add","title":"Amount"},"description":"Number of credits to add"},{"name":"X-Admin-Token","in":"header","required":false,"schema":{"type":"string","title":"X-Admin-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/usage":{"get":{"tags":["Admin"],"summary":"Usage Log","operationId":"adminUsageLog","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"default":100,"title":"Limit"}},{"name":"X-Admin-Token","in":"header","required":false,"schema":{"type":"string","title":"X-Admin-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/":{"get":{"tags":["Free"],"summary":"API Overview","description":"Complete API overview with all endpoints, pricing, and integration methods. **NO API KEY REQUIRED.** This is the starting point for any agent discovering NORTH7.","operationId":"getApiOverview","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Free","description":"No API key required. Use these endpoints to evaluate NORTH7 before signing up. Safe to call anytime."},{"name":"Signals","description":"AI-analyzed trading signals from 6 sources. Each signal includes symbol, direction, confidence score, and reasoning."},{"name":"Market","description":"Real-time market data: prices, price history. Updated every 2 minutes from Yahoo Finance."},{"name":"Analysis","description":"Deep AI analysis for individual stocks and sectors. Includes fundamentals, technicals, and AI assessment."},{"name":"Intelligence","description":"AI-generated briefings covering geopolitics, market-moving events, and forward-looking analysis."},{"name":"Portfolio","description":"NORTH7 model portfolio positions and performance tracking."},{"name":"Account","description":"API key management, credit balance, and usage statistics."},{"name":"Admin","description":"Key creation and credit management. Requires X-Admin-Token header."}]}