API

SDKs & Tools

Official Python, JavaScript, and TypeScript libraries plus CLI, webhooks, and no-code integrations with Zapier and Make.

Introduction

Prophetic provides official SDKs for popular programming languages, along with tools and utilities to streamline integration. Whether you're building a portfolio tracker, market dashboard, or enterprise application, these resources help you ship faster.

Note: All SDKs are open source and available on GitHub.

SDKs Overview

Available Libraries

json

{
  "sdks": {
    "official": ["python", "javascript", "typescript"],
    "community": ["ruby", "go", "php"],
    "status": "actively_maintained",
    "license": "MIT"
  }
}

SDK Matrix

SDK AVAILABILITY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Language        Status      Version    Maintainer
───────────────────────────────────────────────────────────
Python          ✅ Stable    1.2.0      Official
JavaScript      ✅ Stable    1.1.0      Official
TypeScript      ✅ Stable    1.1.0      Official
Ruby            🔶 Beta      0.9.0      Community
Go              🔶 Beta      0.8.0      Community
PHP             🔶 Beta      0.7.0      Community

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Tip: Official SDKs receive priority updates and support.

Python SDK

Installation

bash

Quick Start
python
from prophetic import Prophetic

# Initialize client
client = Prophetic(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Get valuation
valuation = client.valuations.create(
    segment="watches",
    brand="Rolex",
    model="Daytona",
    reference="126500LN"
)

print(f"Value: €{valuation.estimated_value.mid}")
print(f"Score: {valuation.prophetic_score}/100")
Features
PYTHON SDK FEATURES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Feature                  Status
───────────────────────────────────────────────────────────
Auto token refresh       ✅ Included
Async support            ✅ Included
Type hints               ✅ Full coverage
Retry logic              ✅ Configurable
Rate limit handling      ✅ Automatic
Pagination helpers       ✅ Included
Webhook utilities        ✅ Included

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Advanced Usage
python
from prophetic import Prophetic
from prophetic.types import Segment, Scenario

client = Prophetic(client_id="...", client_secret="...")

# Batch valuations
assets = [
    {"segment": "watches", "brand": "Rolex", "model": "Daytona"},
    {"segment": "watches", "brand": "Patek Philippe", "model": "Nautilus"},
    {"segment": "bags", "brand": "Hermès", "model": "Birkin"}
]

batch = client.valuations.batch(assets)
print(f"Total portfolio value: €{batch.total_value}")

# ROI projections with scenarios
projection = client.projections.create(
    asset_id="PRO-WAT-RLX-126500LN",
    horizons=[12, 24, 36],
    scenarios=[Scenario.CONSERVATIVE, Scenario.CENTRAL, Scenario.OPTIMISTIC]
)

for scenario, data in projection.scenarios.items():
    print(f"{scenario}: {data['36_months'].roi}% ROI")

# Async operations
import asyncio

async def get_signals():
    async with Prophetic.async_client(client_id="...", client_secret="...") as client:
        signals = await client.signals.list()
        alerts = await client.signals.alerts()
        return signals, alerts

signals, alerts = asyncio.run(get_signals())
json
{
  "python_sdk": {
    "package": "prophetic",
    "install": "pip install prophetic",
    "version": "1.2.0",
    "python_versions": ["3.8", "3.9", "3.10", "3.11", "3.12"],
    "repository": "github.com/prophetic-ai/prophetic-python"
  }
}
Note: Requires Python 3.8 or higher.
JavaScript SDK
Installation
bash
npm install @prophetic/sdk
# or


Quick Start
javascript
import { Prophetic } from '@prophetic/sdk';

// Initialize client
const client = new Prophetic({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret'
});

// Get valuation
const valuation = await client.valuations.create({
  segment: 'watches',
  brand: 'Rolex',
  model: 'Daytona',
  reference: '126500LN'
});

console.log(`Value: €${valuation.estimatedValue.mid}`);
console.log(`Score: ${valuation.propheticScore}/100`);
Features
JAVASCRIPT SDK FEATURES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Feature                  Status
───────────────────────────────────────────────────────────
Promise-based API        ✅ Native
TypeScript types         ✅ Included
Auto token refresh       ✅ Included
Browser support          ✅ ESM bundle
Node.js support          ✅ CommonJS + ESM
Rate limit handling      ✅ Automatic
Tree-shakeable           ✅ Full

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Advanced Usage
javascript
import { Prophetic, Segment, Scenario } from '@prophetic/sdk';

const client = new Prophetic({ clientId: '...', clientSecret: '...' });

// Portfolio management
const portfolio = await client.portfolio.create({
  name: 'Main Collection',
  assets: [
    { segment: 'watches', brand: 'Rolex', model: 'Daytona', purchasePrice: 22000 },
    { segment: 'wine', producer: 'DRC', vintage: 2018, purchasePrice: 18000 }
  ]
});

// Get performance
const performance = await client.portfolio.performance(portfolio.id);
console.log(`YTD Return: ${performance.periods.ytd.return}%`);

// Stream signals (real-time)
const signalStream = client.signals.stream({ segments: ['watches', 'art'] });

signalStream.on('alert', (alert) => {
  console.log(`New alert: ${alert.title}`);
});

signalStream.on('update', (signal) => {
  console.log(`${signal.segment} momentum: ${signal.momentum}`);
});
json
{
  "javascript_sdk": {
    "package": "@prophetic/sdk",
    "install": "npm install @prophetic/sdk",
    "version": "1.1.0",
    "node_versions": ["16", "18", "20", "22"],
    "browser_support": true,
    "repository": "github.com/prophetic-ai/prophetic-js"
  }
}
Tip: TypeScript definitions are included — no additional packages needed.
TypeScript SDK
Installation
bash
npm
Typed Usage
typescript
import { Prophetic, Valuation, Portfolio, Segment } from '@prophetic/sdk';

const client = new Prophetic({
  clientId: process.env.PROPHETIC_CLIENT_ID!,
  clientSecret: process.env.PROPHETIC_CLIENT_SECRET!
});

// Fully typed responses
const valuation: Valuation = await client.valuations.create({
  segment: Segment.WATCHES,
  brand: 'Rolex',
  model: 'Daytona',
  reference: '126500LN'
});

// Type-safe portfolio
const portfolio: Portfolio = await client.portfolio.get('port_4d5e6f7a8b9c');

// Typed projections
interface ProjectionResult {
  scenarios: {
    conservative: ScenarioData;
    central: ScenarioData;
    optimistic: ScenarioData;
  };
  expectedRoi: Record<string, number>;
}

const projection: ProjectionResult = await client.projections.create({
  assetId: valuation.assetId,
  horizons: [12, 24, 36]
});
Type Definitions
typescript
// Available types
import {
  // Core types
  Prophetic,
  PropheticConfig,
  
  // Asset types
  Valuation,
  ValuationRequest,
  BatchValuation,
  
  // Score types
  Score,
  ScoreBreakdown,
  ScoreFactor,
  
  // Projection types
  Projection,
  Scenario,
  ScenarioData,
  
  // Signal types
  Signal,
  Alert,
  Momentum,
  
  // Portfolio types
  Portfolio,
  PortfolioAsset,
  Performance,
  
  // Enums
  Segment,
  Condition,
  Severity
} from '@prophetic/sdk';
json
{
  "typescript_sdk": {
    "package": "@prophetic/sdk",
    "types": "included",
    "strict_mode": "supported",
    "generics": "full_support"
  }
}
Note: Same package as JavaScript — types are automatically available.
Community SDKs Ruby
# Gemfile
gem 'prophetic'

# Usage
require 'prophetic'

client = Prophetic::Client.new(
  client_id: 'your_client_id',
  client_secret: 'your_client_secret'
)

valuation = client.valuations.create(
  segment: 'watches',
  brand: 'Rolex',
  model: 'Daytona'
)

puts "Value: €#{valuation.estimated_value[:mid]}"
Go
package main

import (
    "fmt"
    "github.com/prophetic-ai/prophetic-go"
)

func main() {
    client := prophetic.NewClient(
        prophetic.WithCredentials("client_id", "client_secret"),
    )
    
    valuation, err := client.Valuations.Create(&prophetic.ValuationRequest{
        Segment: "watches",
        Brand:   "Rolex",
        Model:   "Daytona",
    })
    
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Value: €%d\n", valuation.EstimatedValue.Mid


PHP
<?php

use Prophetic\Client;

$client = new Client([
    'client_id' => 'your_client_id',
    'client_secret' => 'your_client_secret'
]);

$valuation = $client->valuations->create([
    'segment' => 'watches',
    'brand' => 'Rolex',
    'model' => 'Daytona'
]);

echo "Value: €" . $valuation->estimatedValue->mid;
json
{
  "community_sdks": {
    "ruby": {
      "package": "prophetic",
      "version": "0.9.0",
      "status": "beta"
    },
    "go": {
      "package": "github.com/prophetic-ai/prophetic-go",
      "version": "0.8.0",
      "status": "beta"
    },
    "php": {
      "package": "prophetic/sdk",
      "version": "0.7.0",
      "status": "beta"
    }
  }
}
Note: Community SDKs are maintained by contributors. Report issues on GitHub.
CLI Tool
Installation
bash
npm install -g @prophetic/cli
# or


Usage
PROPHETIC CLI COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Command                      Purpose
───────────────────────────────────────────────────────────
prophetic auth login         Authenticate with API
prophetic auth status        Check authentication status

prophetic value <asset>      Get asset valuation
prophetic score <asset>      Get Prophetic Score
prophetic project <asset>    Get ROI projections

prophetic signals            View market signals
prophetic alerts             View active alerts

prophetic portfolio list     List portfolios
prophetic portfolio show     Show portfolio details
prophetic portfolio add      Add asset to portfolio

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Examples
bash
# Authenticate
prophetic auth login

# Quick valuation
prophetic value "Rolex Daytona 126500LN"
# Output: €26,200 (Score: 82/100, Momentum: ▲)

# Get signals for watches
prophetic signals --segment watches
# Output: Momentum: Positive | Volume: +34% | Sentiment: Bullish

# Add to portfolio
prophetic portfolio add main "Patek Philippe Nautilus 5711" --price 95000

# Export portfolio as JSON
prophetic portfolio show main --format


json
{
  "cli_tool": {
    "package": "@prophetic/cli",
    "install": "npm install -g @prophetic/cli",
    "platforms": ["macos", "linux", "windows"],
    "shell_completion": ["bash", "zsh", "fish"]
  }
}
Tip: Enable shell completion for faster command entry.
Webhooks
Webhook Setup
WEBHOOK FLOW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    Prophetic                              Your Server
        │                                       │
        │   Event occurs (signal, alert...)     │
        │                                       │
        ├──────────────────────────────────────▶│
        │   POST /your-webhook-endpoint         │
        │   + Event payload                     │
        │   + Signature header                  │
        │                                       │
        │              200 OK                   │
        │◀──────────────────────────────────────┤
        │                                       │

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Webhook Events
json
{
  "webhook_events": {
    "signals": [
      "signal.momentum_change",
      "signal.volume_spike",
      "signal.sentiment_shift"
    ],
    "alerts": [
      "alert.created",
      "alert.expired"
    ],
    "portfolio": [
      "portfolio.value_change",
      "portfolio.threshold_reached"
    ],
    "valuations": [
      "valuation.significant_change"
    ]
  }
}
Webhook Payload
json
{
  "id": "evt_7f6e5d4c3b2a",
  "type": "signal.momentum_change",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "segment": "watches",
    "previous": "neutral",
    "current": "positive",
    "strength": 0.82
  },
  "signature": "sha256=..."
}
Webhook Verification (Python)
python
from prophetic.webhooks import verify_signature

@app.post("/webhook")
def handle_webhook(request):
    payload = request.body
    signature = request.headers.get("X-Prophetic-Signature")
    
    if not verify_signature(payload, signature, webhook_secret):
        return {"error": "Invalid signature"}, 401
    
    event = json.loads(payload)
    
    if event["type"] == "signal.momentum_change":
        handle_momentum_change(event["data"])
    elif event["type"] == "alert.created":
        handle_new_alert(event["data"])
    
    return {"received": True}, 200
Important: Always verify webhook signatures to ensure authenticity.
Code Samples
Sample Repository
CODE SAMPLES STRUCTURE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

prophetic-samples/
├── python/
│   ├── basic-valuation.py
│   ├── portfolio-tracker.py
│   ├── signal-monitor.py
│   └── webhook-server.py
├── javascript/
│   ├── basic-valuation.js
│   ├── react-dashboard/
│   ├── next-app/
│   └── webhook-handler.js
├── typescript/
│   ├── typed-client.ts
│   └── express-api/
└── integrations/
    ├── zapier/
    ├── n8n/
    └── make/

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Portfolio Tracker Example
python
# portfolio-tracker.py
from prophetic import Prophetic
from datetime import datetime

client = Prophetic(client_id="...", client_secret="...")

# Create portfolio
portfolio = client.portfolio.create(
    name="Watch Collection",
    assets=[
        {
            "segment": "watches",
            "brand": "Rolex",
            "model": "Daytona",
            "reference": "126500LN",
            "purchase_price": 22000,
            "purchase_date": "2023-06-15"
        },
        {
            "segment": "watches",
            "brand": "Patek Philippe",
            "model": "Nautilus",
            "reference": "5711/1A",
            "purchase_price": 95000,
            "purchase_date": "2022-03-20"
        }
    ]
)

# Get current performance
perf = client.portfolio.performance(portfolio.id)

print(f"Portfolio: {portfolio.name}")
print(f"Total Value: €{portfolio.current_value:,}")
print(f"Total Return: {perf.periods['1_year'].return_pct}%")
print(f"vs S&P 500: {perf.periods['1_year'].vs_benchmark}")

# Check signals for holdings
for asset in portfolio.assets:
    signals = client.signals.get(asset.segment)
    print(f"{asset.brand} {asset.model}: {signals.momentum} momentum")
React Dashboard Example
// react-dashboard/src/components/PortfolioCard.tsx
import { useEffect, useState } from 'react';
import { Prophetic } from '@prophetic/sdk';

const client = new Prophetic({
  clientId: process.env.REACT_APP_CLIENT_ID,
  clientSecret: process.env.REACT_APP_CLIENT_SECRET
});

export function PortfolioCard({ portfolioId }) {
  const [portfolio, setPortfolio] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchPortfolio() {
      const data = await client.portfolio.get(portfolioId);
      setPortfolio(data);
      setLoading(false);
    }
    fetchPortfolio();
  }, [portfolioId]);

  if (loading) return <Skeleton />;

  return (
    <Card>
      <CardHeader>
        <Title>{portfolio.name}</Title>
        <Badge momentum={portfolio.metrics.momentum} />
      </CardHeader>
      <CardBody>
        <Stat label="Total Value" value={`€${portfolio.currentValue.toLocaleString()}`} />
        <Stat label="Return" value={`${portfolio.totalReturn}%`} trend="up" />
        <Stat label="Assets" value={portfolio.assetCount} />
      </CardBody>
      <AllocationChart data={portfolio.allocation} />
    </Card>
  );
}
{
  "code_samples": {
    "repository": "github.com/prophetic-ai/prophetic-samples",
    "languages": ["python", "javascript", "typescript"],
    "frameworks": ["react", "next.js", "express", "fastapi"],
    "integrations": ["zapier", "n8n", "make"]
  }
}
Note: All samples are MIT licensed and production-ready.
Integrations
No-Code Platforms
INTEGRATION PLATFORMS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Platform        Status      Use Cases
───────────────────────────────────────────────────────────
Zapier          ✅ Live     Alerts to Slack, sheets sync
Make            ✅ Live     Complex workflows
n8n             ✅ Live     Self-hosted automation
Retool          🔶 Beta     Internal dashboards
Airtable        🔶 Beta     Asset database sync

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Zapier Example
{
  "zapier_triggers": [
    "New Alert",
    "Momentum Change",
    "Portfolio Value Change",
    "Valuation Update"
  ],
  "zapier_actions": [
    "Get Valuation",
    "Get Score",
    "Add to Portfolio",
    "Get Signals"
  ]
}
Tip: Connect Prophetic alerts to Slack, email, or spreadsheets without code.
Summary
Tools Overview
SDKS & TOOLS SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   OFFICIAL SDKs                                         │
│   ─────────────────────────────────────────────────     │
│   Python:           pip install prophetic      ✅       │
│   JavaScript:       npm install @prophetic/sdk ✅       │
│   TypeScript:       npm install @prophetic/sdk ✅       │
│                                                         │
│   COMMUNITY SDKs                                        │
│   ─────────────────────────────────────────────────     │
│   Ruby:             gem install prophetic      🔶       │
│   Go:               go get prophetic-go        🔶       │
│   PHP:              composer require prophetic 🔶       │
│                                                         │
│   TOOLS                                                 │
│   ─────────────────────────────────────────────────     │
│   CLI:              npm install -g @prophetic/cli      │
│   Webhooks:         Real-time event delivery           │    │
│                                                         │
│   INTEGRATIONS                                          │
│   ─────────────────────────────────────────────────     │
│   Zapier, Make, n8n:  No-code automation       ✅       │
│   Retool, Airtable:   Coming soon              🔶       │
│                                                         │
└─────────────────────────────────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{
  "tools_summary": {
    "official_sdks": 3,
    "community_sdks": 3,
    "cli": true,
    "webhooks": true,
    "integrations": 5,
  }
}
Note: All tools are designed to help you build faster with luxury intelligence.
Previous
Endpoints
Previous
Endpoints
Previous
Need help? Contact Support
Join our Discord Community
Questions? Contact Sales