API Reference - SharpShield

Overview

The SharpShield API provides programmatic access to our enterprise risk management platform. Integrate real-time sharp bettor detection, risk scoring, and automated limit management directly into your sportsbook operations.

Key Features

Real-time player risk assessment
Bet analysis and pattern detection
Automated stake limit recommendations
CLV (Closing Line Value) tracking
Historical analytics and reporting
Webhook notifications for risk events

Authentication

All API requests require authentication using API keys. Include your API key in the request header:

HTTP Header

Authorization: Bearer YOUR_API_KEY

Obtaining API Keys

API keys are available through your SharpShield dashboard at app.sharpshield.io/settings/api.

Environment	Base URL
Production	`https://api.sharpshield.io/v1`
Sandbox	`https://sandbox.api.sharpshield.io/v1`

Rate Limits

Plan	Requests/Minute	Requests/Day
Growth	100	10,000
Enterprise	Unlimited	Unlimited
Titan	Unlimited	Unlimited

Rate limit headers are included in all responses:

HTTP Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1703500800

Endpoints

Player Risk Assessment

Analyze Player

Retrieve real-time risk assessment for a player.

POST /players/analyze

Request Body:

JSON

{
  "player_id": "string",
  "external_id": "string (optional)",
  "include_history": true,
  "time_range_days": 30
}

Response:

JSON

{
  "player_id": "pl_abc123",
  "risk_score": 0.87,
  "risk_tier": "HIGH",
  "classification": {
    "is_sharp": true,
    "confidence": 0.92,
    "sharp_indicators": [
      "consistent_clv_positive",
      "steam_move_timing",
      "closing_line_beating"
    ]
  },
  "metrics": {
    "total_bets": 1247,
    "win_rate": 0.548,
    "avg_clv": 3.2,
    "roi": 0.089,
    "avg_stake": 450.00,
    "total_volume": 561150.00
  },
  "recommendations": {
    "suggested_limit": 100.00,
    "current_limit": 500.00,
    "action": "REDUCE_LIMITS"
  },
  "analyzed_at": "2024-12-26T10:30:00Z"
}

Risk Tiers

Tier	Score Range	Description
`LOW`	0.00 - 0.30	Recreational bettor
`MEDIUM`	0.31 - 0.60	Monitor for patterns
`HIGH`	0.61 - 0.85	Likely sharp, apply limits
`CRITICAL`	0.86 - 1.00	Confirmed sharp, restrict

Get Player Profile

Retrieve comprehensive player profile and history.

GET /players/{player_id}

Response:

JSON

{
  "player_id": "pl_abc123",
  "external_id": "your_internal_id",
  "created_at": "2024-01-15T08:00:00Z",
  "status": "ACTIVE",
  "risk_profile": {
    "current_score": 0.87,
    "tier": "HIGH",
    "last_assessment": "2024-12-26T10:30:00Z"
  },
  "lifetime_stats": {
    "total_bets": 1247,
    "total_wagered": 561150.00,
    "total_won": 612213.50,
    "net_profit": 51063.50,
    "roi": 0.091
  },
  "limits": {
    "current_stake_limit": 100.00,
    "default_stake_limit": 500.00,
    "restricted_markets": ["NFL Spreads", "NBA Moneyline"]
  }
}

Bet Analysis

Submit Bet for Analysis

Analyze a bet in real-time before acceptance.

POST /bets/analyze

Request Body:

JSON

{
  "player_id": "pl_abc123",
  "bet": {
    "type": "SINGLE",
    "stake": 500.00,
    "odds": 1.91,
    "market": {
      "sport": "NFL",
      "event_id": "evt_nfl_123",
      "market_type": "SPREAD",
      "selection": "Kansas City Chiefs -3.5",
      "event_time": "2024-12-29T18:00:00Z"
    }
  },
  "context": {
    "line_movement": -1.5,
    "time_to_event_minutes": 180,
    "current_liability": 15000.00
  }
}

Response:

JSON

{
  "bet_id": "bet_xyz789",
  "analysis": {
    "risk_level": "HIGH",
    "recommendation": "REJECT",
    "reasons": [
      "Player has 87% sharp score",
      "Bet timing correlates with steam move",
      "Selection has significant CLV opportunity"
    ],
    "alternative_actions": [
      {
        "action": "ACCEPT_REDUCED",
        "max_stake": 50.00,
        "rationale": "Limit exposure while maintaining engagement"
      },
      {
        "action": "ACCEPT_ADJUSTED_ODDS",
        "adjusted_odds": 1.85,
        "rationale": "Price in player edge"
      }
    ]
  },
  "market_analysis": {
    "consensus_line": -3.0,
    "your_line": -3.5,
    "sharp_money_direction": "FAVORITE",
    "projected_clv": 2.1
  }
}

Webhooks

Configure Webhook

POST /webhooks

Request Body:

JSON

{
  "url": "https://your-domain.com/sharpshield/webhook",
  "events": [
    "player.risk_tier_change",
    "player.sharp_detected",
    "bet.suspicious_pattern",
    "alert.liability_threshold"
  ],
  "secret": "your_webhook_secret"
}

Webhook Payload Example:

JSON

{
  "event": "player.sharp_detected",
  "timestamp": "2024-12-26T10:35:00Z",
  "data": {
    "player_id": "pl_abc123",
    "previous_tier": "MEDIUM",
    "new_tier": "HIGH",
    "risk_score": 0.87,
    "trigger_factors": [
      "CLV threshold exceeded",
      "Win rate anomaly detected"
    ]
  },
  "signature": "sha256=..."
}

Available Events

Event	Description
`player.risk_tier_change`	Player risk tier upgraded/downgraded
`player.sharp_detected`	Player classified as sharp
`player.syndicate_link`	Potential syndicate connection detected
`bet.suspicious_pattern`	Unusual betting pattern identified
`bet.arbitrage_detected`	Potential arbitrage bet detected
`alert.liability_threshold`	Event liability threshold reached
`alert.steam_move`	Sharp money movement detected

SDKs & Libraries

Official SDKs are available for popular languages:

Language	Package	Installation
Python	`sharpshield`	`pip install sharpshield`
Node.js	`@sharpshield/sdk`	`npm install @sharpshield/sdk`
PHP	`sharpshield/php-sdk`	`composer require sharpshield/php-sdk`
Java	`io.sharpshield:sdk`	Maven Central

Python Example

Python

from sharpshield import SharpShieldClient

client = SharpShieldClient(api_key="your_api_key")

# Analyze a player
result = client.players.analyze("pl_abc123")
print(f"Risk Score: {result.risk_score}")
print(f"Is Sharp: {result.classification.is_sharp}")

# Submit a bet for analysis
bet_analysis = client.bets.analyze(
    player_id="pl_abc123",
    stake=500.00,
    odds=1.91,
    market="NFL Spread"
)

if bet_analysis.recommendation == "REJECT":
    print("Bet should be rejected")

Node.js Example

JavaScript

const SharpShield = require('@sharpshield/sdk');

const client = new SharpShield({ apiKey: 'your_api_key' });

// Analyze a player
const result = await client.players.analyze('pl_abc123');
console.log(`Risk Score: ${result.riskScore}`);

// Configure webhook
await client.webhooks.create({
  url: 'https://your-domain.com/webhook',
  events: ['player.sharp_detected']
});

Error Handling

All errors follow a consistent format:

JSON

{
  "error": {
    "code": "PLAYER_NOT_FOUND",
    "message": "The requested player does not exist",
    "details": {
      "player_id": "pl_invalid"
    },
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found
`429`	Rate Limit Exceeded
`500`	Internal Server Error

Support

For API support and questions:

Email: api-support@sharpshield.io
Documentation: docs.sharpshield.io
Status Page: status.sharpshield.io