关于 pp-kalshi
pp-kalshi 是面向 Agent 的命令行技能,用于访问 Kalshi 市场和账户数据。本地 SQLite 快照支持历史价格分析与投资组合分析;只读模式和试运行机制可限制变更操作。
主要功能
- 01本地市场价格历史与快照
- 02投资组合归因、胜率和敞口分析
- 03市场异动与价格相关性分析
- 04查看观察列表自上次同步后的变化
- 05只读模式与变更操作试运行
适用场景
- 01按市场类别复核投资组合表现
- 02根据市场快照追踪价格变化
- 03研究市场间的相关性
- 04使用只读凭据安全编写脚本
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ mvanhorn/ printing-press-library --skill pp-kalshi安装后在 Claude Code 中输入/pp-kalshi确认已加载。
详细介绍
Kalshi — Printing Press CLI
前置条件:安装 CLI
此技能通过 kalshi-pp-cli 二进制文件运行。**调用此技能中的任何命令前,必须确认 CLI 已安装。**如果未安装,请先安装:
- 使用 Printing Press 安装程序安装。在 macOS/Linux 上,二进制文件默认安装到
$HOME/.local/bin;在 Windows 上,默认安装到%LOCALAPPDATA%\Programs\PrintingPress\bin:npx -y @mvanhorn/printing-press-library install kalshi --cli-only - 验证:
kalshi-pp-cli --version - 确保报告的安装目录位于将调用此技能的 Agent/运行时的
$PATH中。
如果 npx 安装失败(没有 Node、处于离线状态等),请改用直接通过 Go 安装(需要 Go 1.26.6 或更高版本)。这会将程序安装到 $GOPATH/bin(默认是 $HOME/go/bin),因此请将该目录添加到 $PATH:
go install github.com/mvanhorn/printing-press-library/library/payments/kalshi/cmd/kalshi-pp-cli@latest
如果安装后 --version 报告“command not found”,说明运行时无法在 $PATH 中找到二进制文件所在目录。验证成功前,不要运行此技能中的命令。
涵盖 Kalshi 的所有功能,还包含一个本地 SQLite 存储,每次同步时都会记录市场价格,因此即使离线也能查询涨跌、相关性和价格历史。明确区分只读密钥与读写密钥;每个修改操作都支持 --dry-run,并提供全局 --read-only 安全模式锁,适用于新闻编辑室和机器人部署。
何时使用此 CLI
当 Agent 需要分析 Kalshi 市场随时间变化的价格或按类别进行分析时,请使用 kalshi-pp-cli。公共 API 只返回当前价格和平铺的持仓,因此需要本地快照存储才能回答历史和汇总类问题。此 CLI 适用于每日投资组合对账、通过跨市场相关性发现信号,以及使用只读 API 凭据安全地编写脚本。
独特功能
其他用于此 API 的工具都不具备这些功能。
可不断积累的本地状态
-
portfolio attribution— 查看任意时间段内按市场类别和系列细分的已实现盈亏(P&L)——只需一条命令,就能回答“本季度政治类市场到底赚到钱了吗?”当 Agent 需要按 Kalshi 分类体系细分已实现盈亏时使用——API 返回的是未整理的成交和结算数据;此命令会将它们与正确归因所需的类别元数据关联起来。
kalshi-pp-cli portfolio attribution --since 2026-01-01 --by category --json -
markets history— 查看某个市场的是/否价格随时间的变化,并以迷你图呈现——数据来自每次市场同步时捕获的快照。当 Agent 询问“这个市场走势如何”或需要价格随时间变化的数据来进行回测时使用;API 只返回当前价格。
kalshi-pp-cli markets history KXPRES-2028-DJT --since 2026-04-01 --sparkline -
portfolio winrate— 计算所有已结算持仓的胜负比、期望值和投资回报率(ROI),还可按类别细分。当 Agent 评估交易策略表现时使用;没有 Kalshi 工具能计算这些指标。
kalshi-pp-cli portfolio winrate --category sports --since 2026-01-01 --json -
portfolio calendar— 查看未来 N 天的待结算事项、相关持仓、预期收益和类别细分。当 Agent 需要规划即将到来的结算时使用;API 在不同端点提供持仓和事件到期时间。
kalshi-pp-cli portfolio calendar --days 14 -
markets movers— 找出自上次同步以来价格波动最大的市场——可按绝对变化或成交量变化排序。当 Agent 需要发现值得关注的市场活动时使用;API 没有“近期波动市场”端点。
kalshi-pp-cli markets movers --window 24h --category politics --json -
markets correlate— 计算两个市场价格历史记录的 Pearson 相关系数——发现相关事件,以便对冲或寻找信号。当 Agent 研究跨市场关系时使用;没有 API 端点或其他工具能计算 Kalshi 市场之间的相关性。
kalshi-pp-cli markets correlate KXFEDFUNDS-26FEB KXCPI-26FEB --window 30d --json -
portfolio exposure— 按类别细分总风险敞口;当任一类别超过可配置的风险阈值时发出集中度警告。当 Agent 需要了解投资组合层面的风险时使用;API 不会按 Kalshi 分类体系汇总风险敞口。
kalshi-pp-cli portfolio exposure --by category --warn-threshold 0.4 --json -
watch diff— 在本地维护代码列表;watch diff会显示每个受关注市场相较于上次同步时的价格和成交量变化——将 Riley 的每日快照惯例简化为一条命令。当 Agent 需要在多次运行中跟踪一组固定市场时使用;API 没有代码列表的概念。
kalshi-pp-cli watch diff --since 24h
诚实的身份验证
-
--read-only— 全局环境变量/标志锁,会在客户端阻止所有修改类命令,无论加载的是哪种密钥层级——将其与每个修改类命令上的 --dry-run 配合使用,以便安全地使用只读凭据编写脚本。当 Agent 使用未知 Kalshi 密钥层级运行时使用——存在只读密钥层级,而且脚本执行中途遇到 403 的情况很常见;此选项会在访问 API 之前于客户端提示这一限制。
kalshi-pp-cli --read-only portfolio create-order --ticker KXTEST --side yes --count 1 --yes-price 50 --dry-run -
subaccounts rollup— 汇总你可查看的所有子账户的持仓、今日成交、余额和按类别细分的风险敞口——以家庭视图查看风险和未成交订单。当 FCM 层级用户需要汇总各子账户的风险时使用;没有 Kalshi 工具能提供家庭视图。
kalshi-pp-cli subaccounts rollup --by category --json
命令参考
account — 管理账户
kalshi-pp-cli account get-api-limits— 用于检索与已验证用户关联的 API 层级限额的端点。kalshi-pp-cli account get-endpoint-costs— 列出已配置令牌成本与默认成本不同的 API v2 端点。使用默认成本的端点……
api-keys — API 密钥管理端点
kalshi-pp-cli api-keys create— 用于使用用户提供的公钥创建新 API 密钥的端点。此端点允许拥有 Premier 或……的用户kalshi-pp-cli api-keys delete— 用于删除现有 API 密钥的端点。此端点会永久删除 API 密钥。密钥删除后,……kalshi-pp-cli api-keys generate— 用于通过自动生成密钥对来创建新 API 密钥的端点。此端点会生成公钥……kalshi-pp-cli api-keys get— 用于检索与已验证用户关联的所有 API 密钥的端点。API 密钥支持以编程方式访问……
communications — 报价请求(RFQ)端点
kalshi-pp-cli communications accept-quote— 用于接受报价的端点。报价方需要进行确认kalshi-pp-cli communications confirm-quote— 用于确认报价的端点。这会启动订单执行计时器kalshi-pp-cli communications create-quote— 用于响应 RFQ 创建报价的端点kalshi-pp-cli communications create-rfq— 用于创建新 RFQ 的端点。最多可以同时有 100 个未关闭的 RFQ。kalshi-pp-cli communications delete-quote— 用于删除报价的端点。删除后,该报价将无法再被接受。kalshi-pp-cli communications delete-rfq— 用于按 ID 删除 RFQ 的端点kalshi-pp-cli communications get-id— 用于获取已登录用户 communications ID 的端点。kalshi-pp-cli communications get-quote— 用于获取特定报价的端点kalshi-pp-cli communications get-quotes— 用于获取报价的端点kalshi-pp-cli communications get-rfq— 用于按 ID 获取单个 RFQ 的端点kalshi-pp-cli communications get-rfqs— 用于获取 RFQ 的端点
events — 事件端点
kalshi-pp-cli events get— 获取所有事件。此端点不包含多变量事件。要检索多变量事件,请使用 GET……kalshi-pp-cli events get-eventticker— 用于按事件代码获取事件数据的端点。事件代表可能……的现实世界事件kalshi-pp-cli events get-multivariate— 检索多变量(组合)事件。这些事件由多变量事件集合动态创建……
exchange — 交易所状态和信息端点
kalshi-pp-cli exchange get-announcements— 用于获取交易所范围内所有公告的端点。kalshi-pp-cli exchange get-schedule— 用于获取交易所日程的端点。kalshi-pp-cli exchange get-status— 用于获取交易所状态的端点。kalshi-pp-cli exchange get-user-data-timestamp— 通常,交易所事件反映到 API 端点会有短暂延迟。在可能的情况下,……
fcm — FCM 成员专用端点
kalshi-pp-cli fcm get-fcmorders— FCM 成员用于按子交易员 ID 筛选订单的端点。此端点需要 FCM 成员访问权限,并且……kalshi-pp-cli fcm get-fcmpositions— FCM 成员用于按子交易员 ID 筛选市场持仓的端点。此端点需要 FCM 成员访问权限……
historical — 管理历史数据
kalshi-pp-cli historical get-cutoff— 返回用于定义实时数据与历史数据边界的截止时间戳。## 截止字段 -...kalshi-pp-cli historical get-fills— 获取成员所有历史成交记录的端点。成交是指您的一笔交易成功撮合。kalshi-pp-cli historical get-market— 根据市场代码从历史数据库中获取特定市场数据的端点。kalshi-pp-cli historical get-market-candlesticks— 获取已从实时数据集中归档的市场历史蜡烛图数据的端点。时间...kalshi-pp-cli historical get-markets— 获取已归档到历史数据库的市场的端点。筛选条件互斥。kalshi-pp-cli historical get-orders— 获取已归档到历史数据库的订单的端点。kalshi-pp-cli historical get-trades— 获取所有市场的所有历史交易的端点。在历史截止时间之前成交的交易...
incentive-programs — 激励计划端点
kalshi-pp-cli incentive-programs— 列出激励计划,可选择筛选条件。激励计划是针对特定市场交易活动的奖励计划。
kalshi-trade-manual-search — 管理 Kalshi 交易手动搜索
kalshi-pp-cli kalshi-trade-manual-search— 按体育项目检索可用筛选条件。此端点会返回各体育项目可用的筛选选项,...
kalshi-trade-manual-search-2 — 管理 Kalshi 交易手动搜索 2
kalshi-pp-cli kalshi-trade-manual-search-2— 按系列类别检索标签。此端点会返回系列类别与其对应内容的映射,...
live-data — 实时数据端点
kalshi-pp-cli live-data get— 获取多个里程碑的实时数据kalshi-pp-cli live-data get-by-milestone— 获取特定里程碑的实时数据。kalshi-pp-cli live-data get-game-stats— 获取特定里程碑的比赛逐回合统计数据。支持的体育项目:职业橄榄球、大学橄榄球、职业...
markets — 市场数据端点
kalshi-pp-cli markets batch-get-candlesticks— 获取多个市场蜡烛图数据的端点。- 每个请求最多接受 100 个市场代码 -...kalshi-pp-cli markets get— 按市场状态筛选。可能的值:unopened、open、closed、settled。留空则返回市场...kalshi-pp-cli markets get-orderbooks— 在单个请求中获取多个市场当前订单簿的端点。订单簿显示所有...kalshi-pp-cli markets get-ticker— 根据市场代码获取特定市场数据的端点。市场代表特定的二元结果...kalshi-pp-cli markets get-trades— 获取所有市场所有交易的端点。交易表示两个用户之间完成的一笔交易...
milestones — 里程碑端点
kalshi-pp-cli milestones get— 用于筛选里程碑的最早开始日期。格式:RFC3339 时间戳kalshi-pp-cli milestones get-milestoneid— 根据 ID 获取特定里程碑数据的端点。
multivariate-event-collections — 管理多变量事件集合
kalshi-pp-cli multivariate-event-collections create-market-in— 在多变量事件集合中创建单个市场的端点。必须至少调用此端点...kalshi-pp-cli multivariate-event-collections get— 获取多变量事件集合数据的端点。kalshi-pp-cli multivariate-event-collections get-multivariateeventcollections— 根据代码获取特定多变量事件集合数据的端点。
portfolio — 投资组合和余额信息端点
-
kalshi-pp-cli portfolio amend-order— 用于修改现有订单中可成交合约的最大数量和/或价格的端点。可成交合约的最大数量…… -
kalshi-pp-cli portfolio amend-order-v2— 使用 V2……修改现有事件市场订单的价格和/或剩余数量的端点。 -
kalshi-pp-cli portfolio apply-subaccount-transfer— 在已验证身份的用户的子账户之间转移资金。主账户使用 0,编号子账户使用 1-32…… -
kalshi-pp-cli portfolio batch-cancel-orders— 用于批量取消订单的端点。最大批次大小取决于您所在层级的写入预算——请参阅 [Rate... -
kalshi-pp-cli portfolio batch-cancel-orders-v2— 使用 V2 响应格式批量取消事件市场订单的端点。最大批次大小取决于…… -
kalshi-pp-cli portfolio batch-create-orders— 用于批量提交订单的端点。最大批次大小取决于您所在层级的写入预算——请参阅 [Rate... -
kalshi-pp-cli portfolio batch-create-orders-v2— 使用 V2 请求/响应格式批量提交事件市场订单的端点。最大批次大小…… -
kalshi-pp-cli portfolio cancel-order— 用于取消订单的端点。orderId 的值应与您要取消的订单的 id 字段一致…… -
kalshi-pp-cli portfolio cancel-order-v2— 使用 V2 响应格式取消事件市场订单的端点。返回 `{order_id, client_order_id,... -
kalshi-pp-cli portfolio create-order— 用于在市场中提交订单的端点。每位用户同时最多可持有 200 000 个未结订单。 -
kalshi-pp-cli portfolio create-order-group— 创建新的订单组,其合约限额按滚动 15 秒窗口计算。达到限额时,…… -
kalshi-pp-cli portfolio create-order-v2— 使用 V2 请求/响应格式提交事件市场订单的端点(单订单簿bid/ask方向以及…… -
kalshi-pp-cli portfolio create-subaccount— 为已验证身份的用户创建新的子账户。子账户从 1 开始按顺序编号。最大…… -
kalshi-pp-cli portfolio decrease-order— 用于减少现有订单中合约数量的端点。这是……可用的唯一编辑方式。 -
kalshi-pp-cli portfolio decrease-order-v2— 使用 V2 请求/响应格式减少现有事件市场订单剩余数量的端点…… -
kalshi-pp-cli portfolio delete-order-group— 删除订单组并取消其中的所有订单。此操作会永久移除该组。 -
kalshi-pp-cli portfolio get-balance— 用于获取会员余额和投资组合价值的端点。两个值均以美分为单位返回。 -
kalshi-pp-cli portfolio get-fills— 用于获取会员所有成交记录的端点。成交指您持有的交易成功撮合。发生于……的成交 -
kalshi-pp-cli portfolio get-order— 用于获取单个订单的端点。 -
kalshi-pp-cli portfolio get-order-group— 获取单个订单组的详情,包括所有订单 ID 和自动取消状态。 -
kalshi-pp-cli portfolio get-order-groups— 获取已验证身份用户的所有订单组。 -
kalshi-pp-cli portfolio get-order-queue-position— 用于获取订单在订单簿中排队位置的端点。该位置表示还需要……的订单数量。 -
kalshi-pp-cli portfolio get-order-queue-positions— 用于获取所有挂单排队位置的端点。排队位置表示……的合约数量。 -
kalshi-pp-cli portfolio get-orders— 将响应限制为具有特定状态的订单:挂单、已取消或已执行。已……的订单 -
kalshi-pp-cli portfolio get-positions— 将持仓限制为以下任一字段值非零的持仓,字段以逗号分隔。…… -
kalshi-pp-cli portfolio get-resting-order-total-value— 用于获取挂单总价值(以美分为单位)的端点。此端点仅供 FCM……使用。 -
kalshi-pp-cli portfolio get-settlements— 用于获取会员历史结算记录的端点。 -
kalshi-pp-cli portfolio get-subaccount-balances— 获取所有子账户(包括主账户)的余额。 -
kalshi-pp-cli portfolio get-subaccount-netting— 获取所有子账户的净额结算启用设置。 -
kalshi-pp-cli portfolio get-subaccount-transfers— 获取已验证身份用户在子账户之间进行的所有转账的分页列表。 -
kalshi-pp-cli portfolio reset-order-group— 将订单组的已撮合合约计数器重置为零,使其在限额……后可以再次下单。 -
kalshi-pp-cli portfolio trigger-order-group— 触发订单组,取消组内所有订单,并阻止提交新订单,直到重置该组。 -
kalshi-pp-cli portfolio update-order-group-limit— 更新订单组合约限额(滚动 15 秒窗口)。如果更新后的限额会立即触发…… -
kalshi-pp-cli portfolio update-subaccount-netting— 更新指定子账户的净额结算启用设置。主账户使用 0,编号子账户使用 1-32…… series — 管理系列 -
kalshi-pp-cli series get— 根据代码获取特定系列的数据。系列代表定期事件的模板…… -
kalshi-pp-cli series get-fee-changes— 获取系列费用变更 -
kalshi-pp-cli series get-list— 根据指定筛选条件获取多个系列的数据。系列代表定期事件的模板……
structured-targets — 结构化目标端点
kalshi-pp-cli structured-targets get— 页面大小(最小值:1,最大值:2000)kalshi-pp-cli structured-targets get-structuredtargets— 根据 ID 获取特定结构化目标的数据。
查找合适的命令
知道自己想做什么,但不确定该用哪个命令时,可以直接询问 CLI:
kalshi-pp-cli which "<capability in your own words>"
which 会根据自然语言功能查询,从 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一项匹配;退出代码 2 表示没有足够确定的匹配——请改用 --help 或缩小查询范围。
使用示例
本季度政治类目的损益
kalshi-pp-cli portfolio attribution --since 2026-01-01 --by category --agent --select 'rows.category,rows.realized_pnl,rows.fills'
按 Kalshi 分类体系统计的已实现损益;--select 会将响应范围缩小到 Agent 所需的三个字段。
在观察列表中跟踪美联储降息市场
kalshi-pp-cli watch add KXFEDFUNDS-26FEB && kalshi-pp-cli watch diff --since 24h --agent
将代码添加到本地观察列表,然后查询该代码自昨日以来的变动。
对照通胀与降息市场
kalshi-pp-cli markets correlate KXFEDFUNDS-26FEB KXCPI-26FEB --window 30d --agent
在本地根据两个市场的快照价格序列计算 Pearson r。
安全的模拟交易会话
kalshi-pp-cli portfolio create-order --ticker KXTEST-2026 --side yes --count 1 --yes-price 50 --action buy --dry-run
同时启用两层安全限制:客户端只读锁 + dry-run;绝不会访问 API。(搭配 KALSHI_READ_ONLY=1 使用,以启用客户端安全模式锁。)
过去 24 小时体育市场中的异动
kalshi-pp-cli markets movers --window 24h --category sports --limit 5 --agent
根据 market_price_history 快照计算价格变动;同步后可离线运行。
身份验证设置
Kalshi 要求使用组合式 RSA-PSS 签名身份验证:UUID 访问密钥 ID(KALSHI_API_KEY)以及 RSA 私钥文件(KALSHI_PRIVATE_KEY_PATH 或 KALSHI_PRIVATE_KEY)。Kalshi 提供两种密钥权限级别——只读和读写。无论加载的是哪种级别,CLI 都会将 KALSHI_READ_ONLY=1(或 --read-only)作为客户端锁,在签名前阻止所有 POST/PUT/PATCH/DELETE 请求。使用只读密钥运行写入命令时,Kalshi 会返回 403;调试时请搭配 --dry-run 使用。
运行 kalshi-pp-cli doctor 验证设置。
Agent 模式
为任何命令添加 --agent。它会展开为:--json --compact --no-input --no-color --yes。
-
可通过管道传输 — JSON 输出到 stdout,错误输出到 stderr
-
可筛选 —
--select保留部分字段。点分路径可深入嵌套结构;数组会逐项遍历。对于冗长 API,这对缩小上下文至关重要:kalshi-pp-cli api-keys get --agent --select id,name,status -
可预览 —
--dry-run显示请求,但不会发送 -
支持离线使用 — 有本地 SQLite 存储时,同步/搜索命令可使用该存储
-
非交互式 — 从不提示输入;所有输入都通过标志提供
响应封装
从本地存储或 API 读取数据的命令,会将输出封装在来源信息中:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
解析 .results 获取数据,并查看 .meta.source 判断数据来自实时 API 还是本地存储。只有 stdout 连接到终端时,才会向 stderr 输出便于阅读的 N results (live) 摘要;通过管道传输或由 Agent 使用时,stdout 只包含纯 JSON。
Agent 反馈
当你(或 Agent)发现此 CLI 有问题时,请记录下来:
kalshi-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
kalshi-pp-cli feedback --stdin < notes.txt
kalshi-pp-cli feedback list --json --limit 10
条目会本地保存在 ~/.kalshi-pp-cli/feedback.jsonl。只有设置了 KALSHI_FEEDBACK_ENDPOINT,并且传入 --send 或设置 KALSHI_FEEDBACK_AUTO_SEND=true 时,才会 POST。默认情况下,反馈仅保存在本地。
请记录让你感到意外的地方,而不是提交 bug 报告。简短、具体、一行即可:这部分会不断积累价值。
输出交付
每个命令都接受 --deliver <sink>。除了标准输出外(或取代标准输出),输出还会发送到指定的接收目标,因此 Agent 无需手动管道传输即可路由命令结果。支持三种接收目标:
| 接收目标 | 效果 |
|---|---|
stdout | 默认;仅写入标准输出 |
file:<path> | 原子地将输出写入 <path>(临时文件 + 重命名) |
webhook:<url> | 将输出正文 POST 到 URL(使用 --compact 时为 application/json 或 application/x-ndjson) |
对于未知协议,会拒绝请求并返回结构化错误,其中列出支持的协议。Webhook 请求失败时会返回非零状态码,并在标准错误中记录 URL 和 HTTP 状态码。
命名配置
配置是保存的一组标志值,可在多次调用中重复使用。如果计划运行的 Agent 每次都使用相同配置调用同一命令,可使用此功能——这是 HeyGen 的“Beacon”模式。
kalshi-pp-cli profile save briefing --json
kalshi-pp-cli --profile briefing api-keys get
kalshi-pp-cli profile list --json
kalshi-pp-cli profile show briefing
kalshi-pp-cli profile delete briefing --yes
显式标志始终优先于配置值;配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置,供 Agent 在运行时发现。
退出代码
| 代码 | 含义 |
|---|---|
| 0 | 成功 |
| 2 | 用法错误(参数不正确) |
| 3 | 未找到资源 |
| 4 | 需要身份验证 |
| 5 | API 错误(上游问题) |
| 7 | 触发速率限制(等待后重试) |
| 10 | 配置错误 |
参数解析
解析 $ARGUMENTS:
- 为空、
help或--help→ 显示kalshi-pp-cli --help输出 - 以
install开头 → 以mcp结尾 → 安装 MCP;否则 → 参见上文的先决条件 - 其他任何内容 → 直接使用(作为 CLI 命令执行,并带上
--agent)
MCP 服务安装
- 安装 MCP 服务:
go install github.com/mvanhorn/printing-press-library/library/payments/kalshi/cmd/kalshi-pp-mcp@latest - 在 Claude Code 中注册:
claude mcp add kalshi-pp-mcp -- kalshi-pp-mcp - 验证:
claude mcp list
直接使用
- 检查是否已安装:
which kalshi-pp-cli如果未找到,请提供安装选项(参见本技能顶部的先决条件)。 - 根据用户查询,从上方的独特功能和命令参考中选择最合适的命令。
- 使用
--agent标志执行:kalshi-pp-cli <command> [subcommand] [args] --agent - 如果存在歧义,请查看子命令帮助:
kalshi-pp-cli <command> --help。