Authentication

All API requests require authentication via an API key. Your key starts with sk_ followed by live_ or test_.

Authentication Methods

SharpAPI supports three authentication methods, listed in priority order:

1. X-API-Key Header (Recommended)

The most secure method for server-side applications.


curl -H "X-API-Key: sk_live_your_key" \
  https://api.sharpapi.io/api/v1/odds

2. Authorization Bearer Header

Standard OAuth-style bearer token format.


curl -H "Authorization: Bearer sk_live_your_key" \
  https://api.sharpapi.io/api/v1/odds

3. Query Parameter

Useful for SSE streaming in browsers where you cannot set custom headers.


curl "https://api.sharpapi.io/api/v1/stream?api_key=sk_live_your_key"

Security Warning: Never expose your API key in client-side code or public repositories. Use a backend proxy for browser applications.

Getting Your API Key

Sign Up - Create an account at sharpapi.io/sign-up
Access Dashboard - Log in to your dashboard
Copy Key - Your API key is displayed on the main dashboard

Test Keys

For development and testing, use test keys that don’t count against your quota:

Key	Tier	Use Case
`sk_test_free`	Free	Basic testing
`sk_test_pro`	Pro	Full feature access
`sk_test_sharp`	Sharp	Unlimited testing

Test keys return real data but are rate-limited and don’t affect your billing.

Subscription Tiers

Tier	Price	Requests/Min	Data Delay	Key Features
Free	$0/mo	12	60s	Odds, Events
Hobby	$79/mo	120	Real-time	Odds, Events, Arbitrage
Pro	$229/mo	300	Real-time	+ EV, Middles
Sharp	$399/mo	1,000	Real-time	+ Priority Support
Enterprise	Custom	Custom	Real-time	+ SLA

See Pricing for full details.

Rate Limits

Rate limits are enforced per API key. Current limits are returned in response headers:


X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705804800

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your tier
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when limit resets

Rate Limit Response

When exceeded, you’ll receive a 429 response:


{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Upgrade your plan or wait before retrying.",
    "docs": "https://sharpapi.io/docs/authentication#rate-limits"
  }
}

Implement exponential backoff when you receive a 429 response. Check X-RateLimit-Reset for when the window resets.

Feature Access by Tier

Feature	Free	Hobby	Pro	Sharp	Enterprise
`GET /odds`	Yes	Yes	Yes	Yes	Yes
`GET /odds/best`	Yes	Yes	Yes	Yes	Yes
`GET /odds/comparison`	Yes	Yes	Yes	Yes	Yes
`POST /odds/batch`	Yes	Yes	Yes	Yes	Yes
`GET /events`	Yes	Yes	Yes	Yes	Yes
`GET /events/:eventId`	Yes	Yes	Yes	Yes	Yes
`GET /events/:eventId/odds`	Yes	Yes	Yes	Yes	Yes
`GET /events/:eventId/markets`	Yes	Yes	Yes	Yes	Yes
`GET /opportunities/ev`	No	No	Yes	Yes	Yes
`GET /opportunities/arbitrage`	No	Yes	Yes	Yes	Yes
`GET /opportunities/middles`	No	No	Yes	Yes	Yes
`GET /stream`	No	Add-on	Add-on	Add-on	Yes
`GET /account`	Yes	Yes	Yes	Yes	Yes
`GET /account/usage`	Yes	Yes	Yes	Yes	Yes
`GET /account/keys`	Yes	Yes	Yes	Yes	Yes

Streaming requires the WebSocket add-on ($99/mo) on any paid tier. Enterprise includes streaming at no extra cost.

Public Reference Endpoints

The following reference data endpoints are accessible without authentication at 10 requests/minute:

GET /api/v1/sports - List all sports
GET /api/v1/sports/{sportId} - Get sport details
GET /api/v1/leagues - List all leagues
GET /api/v1/sportsbooks - List all sportsbooks
GET /api/v1/sportsbooks/{bookId} - Get sportsbook details
GET /api/v1/markets - List all market types
GET /api/v1/health - Health check

Authenticated requests receive higher rate limits based on your subscription tier.

Error Codes

Code	HTTP Status	Description
`unauthorized`	401	API key missing or invalid
`forbidden`	403	Feature requires higher tier
`rate_limited`	429	Too many requests
`tier_restricted`	403	Endpoint not available on your tier
`invalid_request`	400	Malformed request parameters
`not_found`	404	Resource not found
`upstream_error`	502	Temporary issue fetching data
`internal_error`	500	Server error

Error Response Format

All errors follow a consistent format:


{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Check that your key is correct and active.",
    "docs": "https://sharpapi.io/docs/authentication"
  }
}

Best Practices

Store keys securely - Use environment variables, never commit to version control
Use server-side requests - Never expose keys in client-side JavaScript
Implement retry logic - Handle 429 errors with exponential backoff
Monitor usage - Check the /account/usage endpoint to track consumption
Rotate keys regularly - Use the /account/keys/:keyId/rotate endpoint periodically for security