v1.0

Business API Documentation

Integrate Northvane AI predictions into your trading bots. RESTful API with JWT authentication, real-time signals, and actionable intelligence.

Request API Access

Overview

The Northvane Business API provides programmatic access to AI-powered trading predictions for your company's users. Use it to build automated trading bots, integrate signals into your existing systems, or create custom dashboards.

Base URL

https://www.northvane.app/api/business
Real-time Data

Access AI predictions as soon as they're generated

Secure

JWT tokens with 1-month validity

RESTful

Standard JSON responses

Actionable

BUY/SELL/HOLD signals with confidence

Authentication

The API uses JWT (JSON Web Tokens) for authentication. First, obtain a token using your client credentials, then include it in the Authorization header for all subsequent requests.

Step 1: Get Your Credentials

Contact us to get your client_id and client_secret. These are unique to your company and should be kept secure.

Step 2: Request a Token

Exchange your credentials for a JWT token:

POST /api/business/auth/token 
curl -X POST https://www.northvane.app/api/business/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "company_abc123...",
    "client_secret": "your_secret_here..."
  }'

Step 3: Use the Token

Include the token in the Authorization header:

Authorization Header 
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Security Note: Never expose your client_secret in client-side code. Always make API calls from your backend server.

Rate Limits

To ensure fair usage and system stability, the API enforces rate limits:

Limit Type Default Value Description
Per Hour 100 requests Rolling 60-minute window
Per Day 1,000 requests Resets at midnight UTC

Rate limit information is included in every response:

{
  "success": true,
  "data": { ... },
  "rate_limit": {
    "remaining_daily": 950,
    "remaining_hourly": 95
  }
}

Sandbox Mode

Test your integration without affecting production data. Sandbox tokens return realistic fake data and have 10x higher rate limits.

POST /api/business/auth/token 
curl -X POST https://www.northvane.app/api/business/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "sandbox_abc123...",
    "client_secret": "sandbox_secret..."
  }'

Sandbox responses include "sandbox": true in the meta block. All usage is tracked separately.

Widgets SDK

Embed Northvane intelligence directly in your website with zero backend integration. Include our SDK and add HTML attributes.

Include the SDK

<script src="https://northvane.app/sdk/northvane-widgets.js"></script>

Add Widgets

<!-- Market Sentiment Widget -->
<div data-northvane-widget="sentiment"
     data-northvane-token="your_client_id"
     data-northvane-theme="dark"
     data-northvane-lang="en"></div>

<!-- Stock Signal Widget -->
<div data-northvane-widget="stock_signal"
     data-northvane-token="your_client_id"
     data-northvane-symbol="AAPL"
     data-northvane-theme="light"></div>

<!-- Geopolitical Risk Widget -->
<div data-northvane-widget="geopolitical"
     data-northvane-token="your_client_id"></div>

<!-- User Opportunities (requires user_token) -->
<div data-northvane-widget="opportunities"
     data-northvane-token="your_client_id"
     data-northvane-user_token="user_id:hmac_signature"></div>

User Token Generation (Server-side)

# Python
import hmac, hashlib
user_token = f"{user_id}:{hmac.new(client_secret.encode(), str(user_id).encode(), hashlib.sha256).hexdigest()}"

Domain Restriction

Widgets only render on domains listed in your company's allowed_domains. Contact us to add domains.

POST /auth/token

Exchange client credentials for a JWT access token.

Request Body

ParameterTypeRequiredDescription
client_idstringYesYour company's client ID
client_secretstringYesYour company's client secret

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "expires_at": "2026-03-17T12:00:00Z",
  "company": {
    "id": 1,
    "name": "Your Company",
    "rate_limits": {
      "per_hour": 100,
      "per_day": 1000
    }
  }
}

POST /auth/validate

Validate an existing token and check remaining rate limits.

Headers

HeaderValue
AuthorizationBearer <your_token>

Response

{
  "success": true,
  "valid": true,
  "company": {
    "id": 1,
    "name": "Your Company",
    "api_enabled": true,
    "rate_limits": {
      "per_hour": 100,
      "per_day": 1000,
      "remaining_hourly": 95,
      "remaining_daily": 950
    }
  }
}

GET /v1/sentiment/latest

Get the latest market sentiment analysis including Fear & Greed index, VIX, trending stocks, and sector analysis.

Query Parameters

ParameterTypeDefaultDescription
langstringenResponse language (en or fr)

Response

{
  "success": true,
  "data": {
    "analysis_date": "2026-07-05",
    "overall_sentiment": "bullish",
    "market_mood": "optimistic",
    "importance_level": "high",
    "summary": "Markets rally on strong earnings...",
    "fear_greed": { "value": 72, "label": "Greed" },
    "vix": { "value": 14.2, "change_percent": -3.5 },
    "key_topics": [...],
    "trending_stocks": [...],
    "commodities": [...],
    "market_alerts": [...],
    "notable_events": [...],
    "sector_analysis": [...]
  },
  "meta": { "api_version": "v1", "sandbox": false, "timestamp": "..." }
}

GET /v1/sentiment/history

Get historical sentiment data for the past N days (max 30).

Query Parameters

ParameterTypeDefaultDescription
daysinteger7Number of days (1-30)
langstringenResponse language

GET /v1/geopolitical/current

Get the current geopolitical risk assessment with DEFCON-style threat level, hotspots, bilateral tensions, and market implications.

Response includes:

  • defcon - Level (1-5), label, description, change from previous
  • threat_level - Overall risk assessment
  • hotspots - Active conflict zones with intensity scores
  • bilateral_tensions - Key geopolitical tensions between nations
  • market_implications - Sectors at risk, safe havens, commodities impact
  • prediction_markets - Related prediction market probabilities

GET /v1/geopolitical/summary

Compact geopolitical summary: DEFCON level + top 3 risks + executive brief.

GET /v1/stocks/:symbol

Get comprehensive stock data including price, AI analysis (daily/weekly/medium-term), forecasts (J+1, J+7), Danelfin scores, trade plan, and growth metrics.

Path Parameters

ParameterTypeDescription
symbolstringStock ticker (e.g. AAPL, MSFT, BTC-USD)

Response

{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "exchange": "NASDAQ",
    "price": {
      "current": 195.50,
      "change_percent": 1.23,
      "currency": "USD"
    },
    "analysis": {
      "daily": { "action": "BUY", "target_price": 202, "confidence_level": "HIGH" },
      "weekly": { "action": "HOLD", "target_price": 210 },
      "ai_passes": { "quant_direction": "UP", "qual_direction": "UP", "disagreement": false }
    },
    "forecasts": {
      "j1": { "price": 197.2, "change_percent": 0.87, "confidence": 78 },
      "j7": { "price": 201.5, "change_percent": 3.07, "confidence": 65 }
    },
    "danelfin": { "ai_score": 9, "technical_score": 8, "fundamental_score": 9 }
  }
}

GET /v1/stocks/:symbol/analysis

Get AI analysis only: daily + weekly actions, targets, confidence, opportunities, risks, key levels.

GET /v1/stocks/:symbol/fundamentals

Get fundamental data: P/E ratio, revenue, margins, debt, EPS growth, etc.

GET /v1/stocks/batch

Get compact data for multiple stocks at once (max 20).

Query Parameters

ParameterTypeRequiredDescription
symbolsstringYesComma-separated tickers (e.g. AAPL,MSFT,TSLA)
langstringNoResponse language

GET /v1/opportunities

Get AI-detected investment opportunities for your company's users.

Query Parameters

ParameterTypeDescription
user_idintegerFilter by specific user
sectorstringFilter by sector
recommendationstringBUY, SELL, or HOLD
min_confidencenumberMinimum confidence threshold

GET /v1/pre-market/events

Get today's pre-market events: earnings, dividends, corporate actions, and price-moving news.

Query Parameters

ParameterTypeDescription
marketstringFilter by market (us or eu)

GET /v1/pre-market/macro-events

Get recent macro-economic events (last 7 days): central bank decisions, employment data, GDP reports, etc.

GET /v1/prediction-markets

Get active prediction market events from Polymarket, Kalshi, and other platforms, with real-time probabilities.

Query Parameters

ParameterTypeDescription
categorystringFilter by category
limitintegerMax results (default 20, max 50)

GET /v1/prediction-markets/:id

Get full prediction event detail with all nested markets and cross-platform data.

GET /v1/webhooks

List all webhooks configured for your company.

POST /v1/webhooks

Create a new webhook. A signing secret is auto-generated.

Request Body

{
  "url": "https://yourapp.com/webhooks/northvane",
  "events": ["sentiment.updated", "geopolitical.alert", "opportunity.detected"]
}

Webhook Delivery

Payloads are signed with HMAC-SHA256. Verify using the X-Northvane-Signature header:

# Python verification
import hmac, hashlib
expected = hmac.new(webhook_secret.encode(), request.body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(f"sha256={expected}", request.headers["X-Northvane-Signature"])

DELETE /v1/webhooks/:id

Delete a webhook. Pending deliveries are cancelled.

POST /v1/webhooks/:id/test

Send a test delivery to verify your webhook endpoint is working.

GET /predictions Legacy

Get AI predictions for all stocks held by users in your company.

Headers

HeaderValue
AuthorizationBearer <your_token>

Response

{
  "success": true,
  "data": {
    "company": {
      "id": 1,
      "name": "Your Company"
    },
    "users_count": 5,
    "predictions": [
      {
        "user_id": 123,
        "user_email": "trader@company.com",
        "stocks": [
          {
            "stock": {
              "symbol": "AAPL",
              "name": "Apple Inc.",
              "exchange": "NASDAQ",
              "current_price": 178.50
            },
            "position": {
              "shares": 100,
              "avg_purchase_price": 150.00,
              "current_value": 17850.00
            },
            "signals": {
              "daily_action": "BUY",
              "weekly_action": "HOLD",
              "personalized_signal": "STRONG_BUY",
              "confidence_level": "high"
            },
            "forecasts": {
              "est_close": {
                "price": 180.25,
                "change_percent": 0.98,
                "confidence": "high"
              },
              "j7": {
                "price": 185.00,
                "change_percent": 3.64,
                "confidence": "medium"
              }
            }
          }
        ]
      }
    ]
  },
  "timestamp": "2026-02-17T12:00:00Z",
  "rate_limit": {
    "remaining_daily": 949,
    "remaining_hourly": 94
  }
}

GET /predictions/:id

Get AI predictions for a specific user in your company.

Path Parameters

ParameterTypeDescription
idintegerUser ID

Response

Same structure as /predictions but filtered to one user.

GET /predictions/summary

Get an aggregated summary of all predictions across your company's users. Useful for quick overview and top signals.

Response

{
  "success": true,
  "data": {
    "company": { "id": 1, "name": "Your Company" },
    "summary": {
      "total_users": 5,
      "total_stocks": 25,
      "total_value": 1250000.00,
      "signals_breakdown": {
        "strong_buy": 3,
        "buy": 8,
        "hold": 10,
        "sell": 3,
        "strong_sell": 1
      },
      "top_buy_signals": [
        {
          "symbol": "NVDA",
          "name": "NVIDIA Corporation",
          "signal": "STRONG_BUY",
          "confidence": "high",
          "predicted_change_percent": 5.2
        }
      ],
      "top_sell_signals": [
        {
          "symbol": "META",
          "name": "Meta Platforms",
          "signal": "SELL",
          "confidence": "medium",
          "predicted_change_percent": -2.1
        }
      ]
    }
  },
  "timestamp": "2026-02-17T12:00:00Z",
  "rate_limit": { "remaining_daily": 948, "remaining_hourly": 93 }
}

Response Format

All API responses follow a consistent JSON structure:

{
  "success": true | false,
  "data": { ... },           // Present on success
  "error": "Error message",  // Present on failure
  "timestamp": "ISO8601",
  "rate_limit": {
    "remaining_daily": 950,
    "remaining_hourly": 95
  }
}

Error Codes

HTTP CodeMeaningDescription
400Bad RequestMissing or invalid parameters
401UnauthorizedInvalid or missing token
403ForbiddenAPI access disabled for company
404Not FoundUser not found or not in company
429Too Many RequestsRate limit exceeded
500Server ErrorInternal server error

Code Examples

Python

import requests

BASE_URL = "https://www.northvane.app/api/business"

# Get token
auth_response = requests.post(f"{BASE_URL}/auth/token", json={
    "client_id": "company_abc123...",
    "client_secret": "your_secret..."
})
token = auth_response.json()["token"]
headers = {"Authorization": f"Bearer {token}"}

# Get market sentiment
sentiment = requests.get(f"{BASE_URL}/v1/sentiment/latest", headers=headers)
print(f"Market mood: {sentiment.json()['data']['market_mood']}")

# Get stock analysis
stock = requests.get(f"{BASE_URL}/v1/stocks/AAPL?lang=en", headers=headers)
print(f"AAPL action: {stock.json()['data']['analysis']['daily']['action']}")

# Get geopolitical risk
geo = requests.get(f"{BASE_URL}/v1/geopolitical/current", headers=headers)
print(f"DEFCON level: {geo.json()['data']['defcon']['level']}")

# Batch stocks
batch = requests.get(f"{BASE_URL}/v1/stocks/batch?symbols=AAPL,MSFT,NVDA", headers=headers)
for s in batch.json()["data"]:
    print(f"{s['symbol']}: {s['daily_action']}")

JavaScript / Node.js

const axios = require('axios');
const BASE_URL = 'https://www.northvane.app/api/business';

async function main() {
  // Authenticate
  const { data: auth } = await axios.post(`${BASE_URL}/auth/token`, {
    client_id: 'company_abc123...',
    client_secret: 'your_secret...'
  });
  const headers = { Authorization: `Bearer ${auth.token}` };

  // Get sentiment
  const { data: sentiment } = await axios.get(`${BASE_URL}/v1/sentiment/latest`, { headers });
  console.log('Fear & Greed:', sentiment.data.fear_greed.value);

  // Get stock
  const { data: stock } = await axios.get(`${BASE_URL}/v1/stocks/NVDA`, { headers });
  console.log('NVDA target:', stock.data.analysis.daily.target_price);

  // Create webhook
  const { data: webhook } = await axios.post(`${BASE_URL}/v1/webhooks`, {
    url: 'https://yourapp.com/webhooks/northvane',
    events: ['sentiment.updated', 'geopolitical.alert']
  }, { headers });
  console.log('Webhook secret:', webhook.data.secret);
}

main();

Ruby

require "httparty"

BASE_URL = "https://www.northvane.app/api/business"

# Authenticate
auth = HTTParty.post("#{BASE_URL}/auth/token", body: {
  client_id: "company_abc123...",
  client_secret: "your_secret..."
}.to_json, headers: { "Content-Type" => "application/json" })

token = auth.parsed_response["token"]
headers = { "Authorization" => "Bearer #{token}" }

# Get prediction markets
markets = HTTParty.get("#{BASE_URL}/v1/prediction-markets?limit=5", headers: headers)
markets.parsed_response["data"].each do |event|
  puts "#{event['title']}: #{event['main_probability']}%"
end

cURL

# Get token
TOKEN=$(curl -s -X POST https://www.northvane.app/api/business/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"company_abc123...","client_secret":"your_secret..."}' \
  | jq -r '.token')

# Get sentiment
curl -s https://www.northvane.app/api/business/v1/sentiment/latest \
  -H "Authorization: Bearer $TOKEN" | jq '.data.market_mood'

# Get stock analysis
curl -s https://www.northvane.app/api/business/v1/stocks/AAPL/analysis \
  -H "Authorization: Bearer $TOKEN" | jq '.data.daily.action'

# Batch stocks
curl -s "https://www.northvane.app/api/business/v1/stocks/batch?symbols=AAPL,MSFT,TSLA" \
  -H "Authorization: Bearer $TOKEN"

Ready to Get Started?

Contact us to get your API credentials and start building your trading bot today.

Request API Access