Visão Geral da Referência da API
Referência completa para a API REST SharpAPI v1. Todos os endpoints retornam JSON e seguem convenções consistentes para autenticação, filtragem, paginação e tratamento de erros.
URL BaseLink permanente para esta seção
https://api.sharpapi.io/api/v1Sempre use api.sharpapi.io como URL base, não sharpapi.io.
Especificação OpenAPILink permanente para esta seção
A especificação completa OpenAPI 3.1 está disponível para importação em ferramentas como Postman, Insomnia ou geradores de código:
Esta especificação cobre todos os endpoints, esquemas de requisição/resposta e requisitos de autenticação.
Formato da RequisiçãoLink permanente para esta seção
- Todas as requisições usam HTTPS
- Autenticação via cabeçalho
X-API-Key, cabeçalhoAuthorization: Bearerou parâmetro de consultaapi_key - Corpos de requisição (quando aplicável) usam JSON com
Content-Type: application/json - Todos os nomes de campo são
snake_case
Resumo dos EndpointsLink permanente para esta seção
A SharpAPI expõe 35 rotas em 7 namespaces, além de endpoints de referência e de saúde.
OddsLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/odds | Sim | Free |
GET | /api/v1/odds/delta | Sim | Free |
GET | /api/v1/odds/best | Sim | Free |
GET | /api/v1/odds/comparison | Sim | Free |
POST | /api/v1/odds/batch | Sim | Free |
EventosLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/events | Sim | Free |
GET | /api/v1/events/:eventId | Sim | Free |
GET | /api/v1/events/:eventId/odds | Sim | Free |
GET | /api/v1/events/:eventId/markets | Sim | Free |
OportunidadesLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/opportunities/ev | Sim | Pro |
GET | /api/v1/opportunities/arbitrage | Sim | Hobby |
GET | /api/v1/opportunities/middles | Sim | Pro |
SplitsLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/splits | Sim | Pro |
GET | /api/v1/splits/history | Sim | Pro |
StreamingLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/stream | Sim | Add-on |
ContaLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/account | Sim | Free |
GET | /api/v1/account/usage | Sim | Free |
GET | /api/v1/account/keys | Sim | Free |
POST | /api/v1/account/keys | Sim | Free |
DELETE | /api/v1/account/keys/:keyId | Sim | Free |
POST | /api/v1/account/keys/:keyId/rotate | Sim | Free |
Dados de Referência (Públicos)Link permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/sports | Não | - |
GET | /api/v1/leagues | Não | - |
GET | /api/v1/sportsbooks | Não | - |
GET | /api/v1/markets | Não | - |
GET | /api/v1/teams | Não | - |
EnterpriseLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/futures | Sim | Enterprise |
GET | /api/v1/futures/odds | Sim | Enterprise |
SaúdeLink permanente para esta seção
| Método | Caminho | Auth | Tier Mínimo |
|---|---|---|---|
GET | /api/v1/health | Não | - |
Formato da RespostaLink permanente para esta seção
Duas formas de nível superior — ambas colocam data primeiro e updated_at por último, com um bloco pagination opcional no meio. Não existe campo success; o código de status HTTP é a fonte da verdade. Consulte Convenções de Resposta para o conjunto completo de regras.
Resposta de lista paginadaLink permanente para esta seção
{
"data": [
{
"id": "draftkings_33483153_moneyline_PHO",
"sportsbook": "draftkings",
"sport": "basketball",
"home_team": "PHI 76ers",
"away_team": "PHO Suns",
"market_type": "moneyline",
"selection": "PHO Suns",
"odds_american": -150,
"odds_decimal": 1.667,
"odds_probability": 0.60,
"is_live": false
}
],
"pagination": {
"limit": 50,
"offset": 0,
"count": 1,
"total": 3095,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"updated_at": "2026-01-26T02:10:37.846Z"
}| Campo | Descrição |
|---|---|
data | Array de resultados |
pagination.limit | Máximo de itens por página (padrão: 50, máximo: 200) |
pagination.offset | Offset atual nos resultados |
pagination.count | Número de itens retornados nesta resposta |
pagination.total | Total de itens correspondentes em todas as páginas. Omitido em endpoints que não conseguem calculá-lo de forma barata (por exemplo, /odds). |
pagination.has_more | Indica se existem mais resultados além desta página |
pagination.next_offset | Valor de offset a ser usado para a próxima página. Prefira next_cursor em endpoints de dados em tempo real. |
pagination.next_cursor | Cursor opaco para a próxima página. Passe como ?cursor= — estável contra alterações de dados em tempo real. Recomendado para varreduras de múltiplas páginas. Enviado pelos endpoints com suporte a cursor (/odds, /events, /teams) e omitido na última página. /odds/delta não aceita cursor e sempre envia null aqui — ele pagina com next_offset + since. |
updated_at | Timestamp ISO 8601 indicando quando os dados foram atualizados pela última vez |
Resposta de Recurso ÚnicoLink permanente para esta seção
Usada para recursos únicos (/account, /events/:eventId) e endpoints de referência não paginados. Sem bloco pagination.
{
"data": {
"id": "evt_abc123",
"sport": "basketball",
"league": "nba",
"home_team": "PHI 76ers",
"away_team": "PHO Suns",
"start_time": "2026-01-26T19:00:00Z"
},
"updated_at": "2026-01-26T02:10:37.846Z"
}Envelope de ErroLink permanente para esta seção
Todos os erros seguem um formato consistente:
{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Upgrade your plan or wait 45 seconds.",
"docs": "https://docs.sharpapi.io/en/authentication#rate-limits"
}
}| Campo | Descrição |
|---|---|
error.code | Código de erro legível por máquina |
error.message | Descrição legível por humanos |
error.docs | Link para a documentação relevante (opcional — incluído em erros de autenticação, tier, rate limit e streaming) |
error.correct_endpoint | O endpoint correto a ser usado (opcional — incluído em erros unknown_endpoint quando a API reconhece o caminho como uma rota errada conhecida) |
error.retry_after | Segundos até que uma nova tentativa seja permitida (opcional — incluído em erros rate_limited) |
error.addon | O add-on que libera a requisição: game_state ou websocket (opcional — incluído quando uma requisição é recusada por falta de um add-on) |
error.upgrade | Link para o checkout ou a página de cobrança que libera a requisição (opcional — veja Campos de upgrade) |
error.upgrade_note | Nota de uma linha com o plano ou add-on que libera a requisição e o seu preço (opcional — sempre enviado junto com upgrade) |
Campos de upgradeLink permanente para esta seção
Quando uma recusa 403 tier_restricted pode ser liberada por um plano self-service (Hobby, Pro ou Sharp) ou por um add-on, o objeto error também traz upgrade (um link para o checkout desse plano, ou para o add-on na página de cobrança) e upgrade_note (uma nota de uma linha). A message então recebe, depois da frase original, o plano ou add-on, o seu preço e um link. Os exemplos 403 das páginas de EV e arbitragem mostram o corpo completo.
code,tier,required_tieredocsnão mudaram, e nenhum campo foi removido. Os dois campos novos são apenas adicionados.- Uma recusa que só o Enterprise libera não traz nenhum dos dois campos, e a sua
messageé apenas a frase original. - Compare
error.code, nunca o texto demessage: a frase adicionada cita um preço e um link, e ambos podem mudar. Leia o link deupgradeem vez de extraí-lo damessage. - Erros
rate_limitedtambém podem trazerupgradeeupgrade_note, quando um tier superior aumenta o seu limite.
Cabeçalhos de Resposta PadrãoLink permanente para esta seção
Toda resposta da API inclui estes cabeçalhos:
| Cabeçalho | Exemplo | Descrição |
|---|---|---|
X-RateLimit-Limit | 300 | Máximo de requisições por minuto para o seu tier |
X-RateLimit-Remaining | 299 | Requisições restantes na janela atual |
X-RateLimit-Reset | 1705804800 | Timestamp Unix de quando o rate limit é redefinido |
X-Data-Delay | 0 | Atraso dos dados em segundos (60 para Free, 0 para tiers pagos) |
X-Request-Id | req_a1b2c3d4 | Identificador único da requisição para depuração e suporte |
Inclua o valor de X-Request-Id ao entrar em contato com o suporte sobre uma requisição específica.
Comparação de TiersLink permanente para esta seção
| Recurso | Free | Hobby | Pro | Sharp | Enterprise |
|---|---|---|---|---|---|
| Sportsbooks | 2 (DK, FD) | 5 | 15 | 25 (de 43) | Todos |
| Atraso de Dados | 60s | 0s | 0s | 0s | 0s |
| Requisições/min | 12 | 120 | 300 | 1.000 | Personalizado |
| Pinnacle | Não | Não | Não | Sim | Sim |
| EV / Arb / Middles | Não | Não | Sim | Sim | Sim |
| Streaming | Não | Add-on | Add-on | Add-on | Incluído |
| Máx. eventos em batch | 10 | 10 | 50 | 50 | 100 |
Streaming requer o add-on de WebSocket (US$ 99/mês para Hobby e Pro, US$ 149/mês para Sharp). O Enterprise inclui streaming sem custo adicional.
FiltragemLink permanente para esta seção
Todos os endpoints de listagem suportam filtragem via parâmetros de consulta. Os filtros usam nomes de parâmetros no singular e aceitam valores separados por vírgula para seleção múltipla.
Parâmetros de FiltroLink permanente para esta seção
| Parâmetro | Tipo | Exemplo | Descrição |
|---|---|---|---|
sportsbook | string | draftkings,fanduel | Filtrar por um ou mais sportsbooks |
sport | string | basketball,football | Filtrar por esporte. Apenas IDs de esporte; um ID de liga como nba vai em league (veja abaixo) |
league | string | nba,nfl | Filtrar por liga |
market | string | moneyline,spread | Filtrar por tipo de mercado |
event_id | string | evt_abc123 | Filtrar por ID do evento |
is_live | boolean | true | Apenas eventos ao vivo/em andamento |
sort | string | -odds_american | Campo de ordenação com prefixo - opcional para ordem decrescente |
fields | string | id,sportsbook,odds_american | Campos separados por vírgula a serem incluídos na resposta |
min_odds | number | -110 | Filtro de odds americanas mínimas |
max_odds | number | 200 | Filtro de odds americanas máximas |
group_by | string | event | Agrupar resultados por campo |
limit | number | 25 | Resultados por página (padrão: 50, máximo: 200) |
offset | number | 50 | Offset de paginação. Pode produzir linhas duplicadas em endpoints de tempo real quando os dados mudam entre requisições. |
cursor | string | — | Cursor opaco do next_cursor. Recomendado para varreduras de múltiplas páginas sobre dados em tempo real — elimina o desvio de offset. |
Aliases obsoletosLink permanente para esta seção
As grafias antigas de dois filtros continuam aceitas: event para event_id e live
para is_live. Elas retornam as mesmas linhas, portanto nada quebra — mas a resposta
traz Deprecation: true e um cabeçalho Warning, e esses nomes podem ser removidos em
uma versão futura. Use os nomes canônicos da tabela acima em código novo. Não há data de
remoção definida, e ela não ocorrerá sem aviso prévio.
IDs de liga em sportLink permanente para esta seção
sport aceita um ID de esporte, como basketball ou hockey, ou outra grafia de um esporte,
como ice_hockey ou american-football. Os IDs válidos são listados por
GET /api/v1/sports. Um ID de liga, como nba, ncaab,
nfl, ncaaf, nhl, mlb, atp ou ufc, vai em league:
# Errado: um ID de liga em sport
curl "https://api.sharpapi.io/api/v1/odds?sport=nba" -H "X-API-Key: YOUR_KEY"
# Certo: apenas jogos da NBA
curl "https://api.sharpapi.io/api/v1/odds?league=nba" -H "X-API-Key: YOUR_KEY"
# Certo: todas as ligas de basquete
curl "https://api.sharpapi.io/api/v1/odds?sport=basketball" -H "X-API-Key: YOUR_KEY"Um ID de liga em sport está sendo descontinuado:
-
Até terça-feira, 1º de dezembro de 2026, 15:00 UTC (10:00 ET), ele continua retornando as linhas do esporte inteiro, não só daquela liga:
sport=nbaretorna todas as ligas de basquete, as mesmas linhas desport=basketball. Respostas REST e SSE trazemDeprecation: truee um cabeçalhoWarningque indica o filtroleaguea usar e a data (uma conexão WebSocket não recebe cabeçalho):Deprecation: true Warning: 299 - "sport=nba is a league id, not a sport; use league=nba; from Tue, 01 Dec 2026 15:00:00 GMT a league id in sport= returns 400 invalid_filter"Com dois ou mais IDs de liga, o texto diz
sport=nba,nfl are league ids, not sports; use league=nba,nfl; .... Um valor desportque mistura um esporte e um ID de liga, comosport=basketball,nfl, cita apenas o ID de liga. -
A partir dessa data, um ID de liga em
sportretorna400 invalid_filter, o mesmo erro de um esporte desconhecido, com uma sugestãodid_you_meanque indicaleague=<id>.
Mova agora qualquer ID de liga de sport para league. Uma requisição que já usa league para
ligas e sport para esportes não é afetada.
ExemplosLink permanente para esta seção
# Múltiplos sportsbooks (separados por vírgula)
curl "https://api.sharpapi.io/api/v1/odds?sportsbook=draftkings,fanduel" \
-H "X-API-Key: YOUR_KEY"
# Combinar filtros
curl "https://api.sharpapi.io/api/v1/odds?league=nba,nhl&sportsbook=pinnacle&is_live=true" \
-H "X-API-Key: YOUR_KEY"
# Paginar pelos resultados
curl "https://api.sharpapi.io/api/v1/odds?limit=25&offset=50" \
-H "X-API-Key: YOUR_KEY"Os nomes dos parâmetros são sempre no singular (sportsbook, não sportsbooks). Use vírgulas para passar múltiplos valores: sportsbook=draftkings,fanduel.
Formatos de OddsLink permanente para esta seção
Todas as odds são retornadas como campos planos em cada objeto de odds:
{
"odds_american": -110,
"odds_decimal": 1.909,
"odds_probability": 0.5238
}| Campo | Exemplo | Descrição |
|---|---|---|
odds_american | -110, +150 | Formato padrão dos EUA |
odds_decimal | 1.909, 2.50 | Formato multiplicador |
odds_probability | 0.5238 | Probabilidade implícita (0 a 1) |
Códigos de ErroLink permanente para esta seção
A lista canônica de códigos de erro emitidos pela API. A string em error.code é o contrato estável — verifique-a em vez do texto em message.
Códigos de erro HTTPLink permanente para esta seção
Emitidos em respostas REST.
| Código | Status HTTP | Descrição |
|---|---|---|
missing_api_key | 401 | Nenhuma API key fornecida via X-API-Key, ?api_key= ou Authorization: Bearer |
invalid_api_key | 401 | API key foi fornecida, mas não é reconhecida |
expired_api_key | 401 | API key expirou — gere uma nova no painel |
disabled_api_key | 401 | API key está desativada, geralmente porque a assinatura expirou |
unauthorized | 401 | Autenticação por Bearer token falhou em um endpoint interno (distinto de invalid_api_key) |
invalid_token | 401 | Falha na verificação do token de sessão Clerk (endpoints exclusivos do painel) |
tier_restricted | 403 | Endpoint ou recurso não está disponível no seu tier — a resposta inclui tier e required_tier, mais upgrade e upgrade_note quando um plano self-service ou um add-on o libera (Campos de upgrade) |
not_found | 404 | Recurso não encontrado |
method_not_allowed | 405 | Método HTTP não é suportado nesta rota |
gone | 410 | Evento terminou ou expirou — use /api/v1/events para eventos atuais |
unknown_endpoint | 410 | Caminho de API errado — a resposta inclui correct_endpoint com a rota correta (ex.: /api/v1/arbitrage → /api/v1/opportunities/arbitrage) |
validation_error | 400 | Corpo da requisição ou parâmetros de consulta falharam na validação |
offset_too_large | 400 | offset excede o máximo por endpoint (atualmente 500 em /odds e /odds/delta). Mude para paginação baseada em cursor ou avance since |
rate_limited | 429 | Limite de requisições por minuto excedido — a resposta inclui retry_after |
concurrent_request_cap | 429 | Muitas requisições em andamento para o seu tier — reduza o paralelismo ou faça upgrade |
too_many_streams | 429 | Máximo de streams SSE ou WebSocket concorrentes excedido para esta API key |
backpressure | — | Emitido como um SSE event: error (não como um status HTTP) quando o cliente não consegue acompanhar; o servidor então fecha o stream |
upstream_error | 502 | Problema temporário ao acessar um sportsbook upstream ou provedor de autenticação |
service_unavailable | 503 | Um serviço necessário (ex.: gerenciamento de chaves) não está configurado ou está offline |
not_ready | 503 | Um armazenamento de apoio do qual o endpoint depende (ex.: ClickHouse, captura de closing line) ainda não está pronto para atender à requisição. Tente novamente com backoff |
internal_error | 500 | Erro inesperado do servidor — tente novamente com backoff e contate o suporte com o X-Request-Id se persistir |
bad_request e invalid_request estão obsoletos — ambos foram colapsados em validation_error. Clientes que correspondem às strings antigas devem adicionar validation_error ao seu mapa de erros.
Códigos de erro em frames WebSocketLink permanente para esta seção
Emitidos apenas dentro de frames {"type": "error", "code": "..."} em uma conexão WebSocket aberta. Eles descrevem erros do protocolo do cliente e não correspondem a um status HTTP.
| Código | Significado |
|---|---|
invalid_message | O frame não pôde ser analisado como JSON ou não corresponde ao formato esperado |
unknown_message_type | O campo type não é um dos valores documentados (auth, subscribe, filter, refresh_token, ping) |
missing_token | Frame auth ou refresh_token não incluiu um campo token |
missing_channels | Frame subscribe não incluiu um array channels não vazio |
not_authenticated | O frame requer uma sessão autenticada (enviou subscribe, filter ou refresh_token antes de auth) |
already_authenticated | O cliente enviou um segundo frame auth após o primeiro ter sido bem-sucedido |