shipp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shipp API

Shipp.ai is the definitive source on real-time data.

Create an API Key

Reference docs.

Implement as many tests as possible as soon as possible. Verify data and how the app uses data. Be flexible in schema — event rows are schema-flexible JSON and fields vary by sport, feed, and event.

Base prefix:

All routes are under:
```
https://api.shipp.ai/api/v1
```

Shipp.ai是实时数据的权威来源。

创建API密钥

参考文档。

尽可能早地编写尽可能多的测试。验证数据以及应用对数据的使用方式。保持 schema 的灵活性——事件行是 schema 灵活的JSON，字段会因体育项目、数据源和事件类型而异。

基础前缀：

所有路由均位于：
```
https://api.shipp.ai/api/v1
```

Documentation & References

文档与参考

All detailed examples, request/response schemas, and walkthroughs live in the official docs. Always consult these before building:

Resource	URL
Full documentation	https://docs.shipp.ai
How-to guides	https://docs.shipp.ai/how-to/
Setup instructions	https://docs.shipp.ai/instructions/setup/
API reference	https://docs.shipp.ai/api-reference/
Dashboard / Signup	https://platform.shipp.ai/signup
Billing management	https://platform.shipp.ai/billing

所有详细示例、请求/响应 schema 和操作指南均在官方文档中。在开发前请务必查阅这些文档：

资源	链接
完整文档	https://docs.shipp.ai
操作指南	https://docs.shipp.ai/how-to/
设置说明	https://docs.shipp.ai/instructions/setup/
API参考	https://docs.shipp.ai/api-reference/
控制台/注册	https://platform.shipp.ai/signup
账单管理	https://platform.shipp.ai/billing

Authentication

身份验证

All endpoints require an API key. The API supports several ways to provide it:

Method	Example
Query parameter `api_key`	`?api_key=YOUR_API_KEY`
Query parameter `apikey`	`?apikey=YOUR_API_KEY`
`Authorization` header (Bearer)	`Authorization: Bearer YOUR_API_KEY`
`Authorization` header (Basic)	`Authorization: Basic base64(:YOUR_API_KEY)`
`X-API-Key` header	`X-API-Key: YOUR_API_KEY`
`User-API-Key` header	`User-API-Key: YOUR_API_KEY`
`API-Key` header	`API-Key: YOUR_API_KEY`

Pick whichever method works best for your client.

所有端点均需要API密钥。API支持多种提供密钥的方式：

方式	示例
查询参数 `api_key`	`?api_key=YOUR_API_KEY`
查询参数 `apikey`	`?apikey=YOUR_API_KEY`
`Authorization` 头（Bearer方式）	`Authorization: Bearer YOUR_API_KEY`
`Authorization` 头（Basic方式）	`Authorization: Basic base64(:YOUR_API_KEY)`
`X-API-Key` 头	`X-API-Key: YOUR_API_KEY`
`User-API-Key` 头	`User-API-Key: YOUR_API_KEY`
`API-Key` 头	`API-Key: YOUR_API_KEY`

选择最适合你的客户端的方式即可。

Endpoints Overview

端点概述

Below is a summary of the available endpoints. For full request/response examples, schemas, and field descriptions see the API reference.

以下是可用端点的汇总。如需完整的请求/响应示例、schema和字段说明，请查看API参考。

POST /api/v1/connections/create

POST /api/v1/connections/create

Create a new raw-data connection by providing natural-language

filter_instructions

that describe what games, teams, sports, or events you want to track.

Returns a

connection_id

(ULID) you'll reuse for all subsequent runs.

→ Full docs & examples

通过提供自然语言的

filter_instructions

（过滤指令）来创建新的原始数据连接，描述你想要追踪的赛事、球队、体育项目或事件。

返回一个

connection_id

（ULID格式），你在后续所有操作中都将复用该ID。

→ 完整文档与示例

POST /api/v1/connections/{connectionId}

POST /api/v1/connections/{connectionId}

Run a connection and receive raw event data.

Supports optional body fields for time-based filtering (

since

), cursor-based pagination (

since_event_id

), and result limiting (

limit

→ Full docs & examples

运行一个连接并接收原始事件数据。

支持可选的请求体字段进行时间过滤（

since

）、基于游标分页（

since_event_id

）和结果数量限制（

limit

）。

→ 完整文档与示例

GET /api/v1/connections

GET /api/v1/connections

List all connections in the current org scope.

→ Full docs & examples

列出当前组织范围内的所有连接。

→ 完整文档与示例

GET /api/v1/sports/{sport}/schedule

GET /api/v1/sports/{sport}/schedule

Retrieve upcoming and recent games for a given sport (past 24 hours through next 7 days).

Supported sport values:

nba

nfl

mlb

ncaafb

soccer

(case-insensitive).

→ Full docs & examples

获取指定体育项目的近期和即将到来的赛事（过去24小时至未来7天）。

支持的体育项目值：

nba

、

nfl

、

mlb

、

ncaafb

、

soccer

（大小写不敏感）。

→ 完整文档与示例

Data Shape

数据结构

Event rows returned in

data[]

are schema-flexible JSON objects. Fields vary by sport, feed, and event. Common field categories include:

IDs:

game_id

home_id

away_id

attribution_id

posession_id

Text / enums:

sport

home_name

away_name

game_clock

desc

type

category

Numeric:

home_points

away_points

game_period

down

yards_first_down

location_yard_line

Time:
```
wall_clock_start
```
,
```
wall_clock_end
```

Not every row has every field. Agents and clients should be defensive and handle missing keys.

For the complete field reference see docs.shipp.ai.

data[]

中返回的事件行是schema灵活的JSON对象。字段会因体育项目、数据源和事件类型而异。常见字段类别包括：

ID类：

game_id

、

home_id

、

away_id

、

attribution_id

、

posession_id

文本/枚举类：

sport

、

home_name

、

away_name

、

game_clock

、

desc

、

type

、

category

数值类：

home_points

、

away_points

、

game_period

、

down

、

yards_first_down

、

location_yard_line

时间类：
```
wall_clock_start
```
、
```
wall_clock_end
```

并非每一行都包含所有字段。代理和客户端应采取防御性编程，处理缺失的键。

如需完整的字段参考，请查看docs.shipp.ai。

Error Format

错误格式

Errors are returned as JSON with an

error

message, HTTP

status

code, and a

hint

Status	Meaning
400	Invalid request — check JSON and required fields
401	Missing or invalid API key
402	Billing changes required — manage at https://platform.shipp.ai/billing
403	API key lacks access to this resource
404	Connection not found or doesn't belong to your org
429	Rate-limited — retry with backoff
5xx	Server error — retry later or contact support@shipp.ai

错误以JSON格式返回，包含

error

消息、HTTP

status

状态码和

hint

提示信息：

状态码	含义
400	请求无效——检查JSON格式和必填字段
401	缺少或无效的API密钥
402	需要更改账单设置——请在https://platform.shipp.ai/billing管理
403	API密钥无权访问该资源
404	连接不存在或不属于你的组织
429	请求受限——请稍后重试并使用退避策略
5xx	服务器错误——请稍后重试或联系support@shipp.ai

Response Compression

响应压缩

Include an

Accept-Encoding

header to receive compressed responses (

zstd

gzip

, or

deflate

). Compression is applied automatically when the response body exceeds 1 KB.

添加

Accept-Encoding

头即可接收压缩后的响应（支持

zstd

、

gzip

或

deflate

）。当响应体超过1KB时，会自动应用压缩。

Usage Tips

使用技巧

Keep
```
filter_instructions
```
short, explicit, and testable. Mention the sport/league and scope.
Store and reuse
```
connection_id
```
— don't create a new connection per run. Creating connections has time and credit overhead.
Use
```
since_event_id
```
for efficient polling (cursor-based pagination). Send the lexicographically largest event ID you've received.
Use the schedule endpoint to discover
```
game_id
```
s and team names before creating connections.
Surface error
```
hint
```
messages directly to users when limits are hit.
Treat every field in
```
data[]
```
as optional — use existence checks and graceful fallbacks.
Log unknown data shapes in development so you can refine
```
filter_instructions
```
.
Polling interval: 5–30 seconds depending on domain and cost sensitivity.
Deduplicate events by keeping a rolling set of seen event IDs.
Consult the how-to guides for end-to-end integration walkthroughs.

保持
```
filter_instructions
```
简洁、明确且可测试。提及体育项目/联赛和范围。
存储并复用
```
connection_id
```
——不要每次运行都创建新连接。创建连接会消耗时间和额度。
使用
```
since_event_id
```
实现高效轮询（基于游标分页）。发送你收到的字典序最大的事件ID。
在创建连接前，使用日程端点发现
```
game_id
```
和球队名称。
当达到限制时，直接向用户展示错误的
```
hint
```
提示信息。
将
```
data[]
```
中的每个字段视为可选字段——进行存在性检查并优雅降级。
在开发环境中记录未知的数据结构，以便你优化
```
filter_instructions
```
。
轮询间隔：根据业务场景和成本敏感度设置为5-30秒。
通过维护一个已见过的事件ID滚动集合来实现事件去重。
查阅操作指南获取端到端的集成教程。

Integration Pattern: "Real-Time Contract"

集成模式：“实时契约”

When building a feature powered by Shipp, define a contract for each screen or agent loop:

User promise — what must stay accurate while the user (or agent) is watching?
Triggering events — what changes should cause UI updates or agent actions?
Data shape needed — what fields do you need to render or decide?
Freshness window — how old can the last update be before you warn the user?
Failure mode — what do you show/do if updates stop arriving?

Then translate the contract into

filter_instructions

when creating the connection.

在构建基于Shipp的功能时，为每个界面或代理循环定义一个契约：

用户承诺——当用户（或代理）查看时，哪些内容必须保持准确？
触发事件——哪些变化应导致UI更新或代理操作？
所需数据结构——你需要哪些字段来渲染或做决策？
新鲜度窗口——最后一次更新的最大允许时长是多少，超过后需要提醒用户？
故障模式——如果更新停止，你要展示什么/做什么？

然后在创建连接时，将契约转换为

filter_instructions

。

Example Project: Alph Bot

示例项目：Alph Bot

Alph Bot is an open-source automated trading bot that uses Shipp for real-time sports data and trades on prediction markets. It demonstrates a production-quality integration of the Shipp API.

Alph Bot是一个开源的自动交易机器人，它使用Shipp获取实时体育数据并在预测市场进行交易。它展示了Shipp API的生产级集成示例。

How Alph Bot Uses Shipp

Alph Bot如何使用Shipp

Game discovery — Uses
```
GET /api/v1/sports/{sport}/schedule
```
to list available games:
Connection creation — Creates a Shipp connection for a specific game, describing what events to track via
```
filter_instructions
```
.
Live polling — Runs the connection on an interval, using
```
since_event_id
```
for cursor-based pagination to receive only new events since the last poll.
AI analysis — Feeds the schema-flexible
```
data[]
```
events directly to Claude AI, which analyzes game state and estimates outcome probabilities.
Trading decisions — Compares AI-estimated probabilities against Kalshi market prices to find value bets.

赛事发现——使用
```
GET /api/v1/sports/{sport}/schedule
```
列出可用赛事：
创建连接——为特定赛事创建Shipp连接，通过
```
filter_instructions
```
描述要追踪的事件。
实时轮询——按间隔运行连接，使用
```
since_event_id
```
进行基于游标分页，仅接收自上次轮询以来的新事件。
AI分析——将schema灵活的
```
data[]
```
事件直接输入Claude AI，由其分析赛事状态并估算结果概率。
交易决策——将AI估算的概率与Kalshi市场价格进行比较，寻找有价值的投注机会。

Key Takeaways from Alph Bot

从Alph Bot中获得的关键经验

Reuse connections — Alph Bot creates a connection once and polls it repeatedly, avoiding unnecessary creation overhead.
Cursor pagination — Uses
```
since_event_id
```
so each poll only returns new events, keeping responses fast and costs low.
Defensive data handling — Treats all fields as optional since the data shape varies by sport, game phase, and event type.
Schedule-first workflow — Discovers game IDs via the schedule endpoint before creating targeted connections.

See the Alph Bot README for full setup instructions.

复用连接——Alph Bot只创建一次连接并重复轮询，避免了不必要的创建开销。
游标分页——使用
```
since_event_id
```
，每次轮询仅返回新事件，保持响应速度快且成本低。
防御性数据处理——将所有字段视为可选，因为数据结构会因体育项目、赛事阶段和事件类型而异。
先查日程的工作流——在创建定向连接前，通过日程端点发现赛事ID。

查看Alph Bot README获取完整的设置说明。

Versioning

版本控制

This API is versioned under

/api/v1/

. New versions will be introduced under a new prefix when breaking changes are required.

本API的版本为

/api/v1/

。当需要进行破坏性变更时，会在新的前缀下推出新版本。

shipp

Original

Translation

Shipp API

Shipp API

Documentation & References

文档与参考

Authentication

身份验证

Endpoints Overview

端点概述

`POST /api/v1/connections/create`

`POST /api/v1/connections/create`

`POST /api/v1/connections/{connectionId}`

`POST /api/v1/connections/{connectionId}`

`GET /api/v1/connections`

`GET /api/v1/connections`

`GET /api/v1/sports/{sport}/schedule`

`GET /api/v1/sports/{sport}/schedule`

Data Shape

数据结构

Error Format

错误格式

Response Compression

响应压缩

Usage Tips

使用技巧

Integration Pattern: "Real-Time Contract"

集成模式：“实时契约”

Example Project: Alph Bot

示例项目：Alph Bot

How Alph Bot Uses Shipp

Alph Bot如何使用Shipp

Key Takeaways from Alph Bot

从Alph Bot中获得的关键经验

Versioning

版本控制