--- title: "智能体快速开始" canonical_url: "https://tweetstream.io/zh-cn/docs/agent-quickstart" last_updated: 2026-10-29 --- # 智能体快速开始 这里的每一步都是 HTTP 调用，智能体无需打开控制台即可替对方执行：先试用免费沙盒，再用邮箱验证码注册，把一个付款链接交给对方，然后连接。 Canonical URL: https://tweetstream.io/zh-cn/docs/agent-quickstart ## 先试用沙盒 沙盒无需账号，也无需 key。它以 60 秒延迟推送一份固定的 50 个 X 账号的帖子，使用与付费流相同的 `tweet` 消息信封：`content`、`update`、`meta`、`delete`、`pin` 和 `unpin`。基于沙盒写的代码，只需更换主机并加上 key，就能在付费流上运行。 每个客户端最多 2 个连接，每次会话 30 分钟后结束，重新连接即可继续。第一帧是 `sandbox_welcome`。添加或移除账号的请求会收到错误回复。 沙盒账号：`@_richardteng`, `@a1lon9`, `@binance`, `@binancewallet`, `@binancezh`, `@blknoiz06`, `@bnbchain`, `@brian_armstrong`, `@cb_doge`, `@cobie`, `@coinbase`, `@cz_binance`, `@deitaone`, `@elonmusk`, `@eth_cedric`, `@fern`, `@finkd`, `@firstsquawk`, `@flapdotsh`, `@fourdotmemezh`, `@heyibinance`, `@jensenhuang`, `@jerallaire`, `@jessepollak`, `@justinsuntron`, `@meadgod`, `@mert`, `@nikitabier`, `@nina_rong`, `@openai`, `@pmarca`, `@polymarket`, `@ponsdotfamily`, `@pumpfun`, `@realdonaldtrump`, `@robinhoodapp`, `@robinhoodcrypto`, `@sama`, `@saylor`, `@solana`, `@spacex`, `@theunipcs`, `@toly`, `@unusual_whales`, `@vitalikbuterin`, `@vladtenev`, `@watcherguru`, `@whitehouse`, `@zachxbt`, `@zerohedge`。 ### 读取沙盒信息 ```bash curl -s https://tweetstream.io/api/agent/sandbox ``` ### 连接沙盒 ```bash npx wscat -c wss://sandbox.tweetstream.io/ws -s tweetstream.v1 ``` ### 第一帧 ```json { "v": 1, "t": "control", "op": "sandbox_welcome", "ts": 1793275200000, "d": { "signupUrl": "https://tweetstream.io/llms.txt", "accounts": 50, "delaySeconds": 60, "sessionSeconds": 1800 } } ``` ## 用邮箱验证码注册 共两次调用。第一次向对方邮箱发送 6 位验证码，第二次用验证码换取账号的 API key。无论该邮箱是否已有账号，第一次调用的响应都相同；已有账号会取回当前的 key。 验证码在 `expiresAt` 过期。`resendAt` 之后可以重新申请。 `setupProof` 有效期 30 分钟，用于生成 Discord 链接和再次读取 key。过期后重新申请并验证验证码。 > 验证前先征得对方同意 > > 只有在对方阅读并同意服务条款后，才发送 `acceptTerms: true`。在同一条消息里向对方索取验证码并确认同意。 > > - [服务条款](https://tweetstream.io/zh-cn/terms) ### 发送验证码 ```bash curl -s https://tweetstream.io/api/agent/email-code/request \ -H 'Content-Type: application/json' \ -d '{"email":"alice@example.com"}' ``` ### 202 响应 ```json { "status": "awaiting_email", "challengeId": "4f1c9e2a7b3d8065c1e4a9f27d3b5c8e0a6f1d2b9c4e7a3f5d8b0c6e2a9f1d47", "expiresAt": "2026-10-29T12:10:00.000Z", "resendAt": "2026-10-29T12:01:00.000Z", "next": { "action": "verify_email", "who": "human_then_agent", "method": "POST", "url": "https://tweetstream.io/api/agent/email-code/verify" } } ``` ### 验证验证码 ```bash # Only after the person gave you the code and accepted the Terms. curl -s https://tweetstream.io/api/agent/email-code/verify \ -H 'Content-Type: application/json' \ -d "{\"challengeId\":\"$CHALLENGE_ID\",\"code\":\"$EMAIL_CODE\",\"acceptTerms\":true}" ``` ### 200 响应 ```json { "status": "payment_required", "family": "BASE", "reason": "new", "apiKey": "", "setupProof": "", "next": { "action": "create_checkout", "who": "agent", "method": "POST", "url": "https://tweetstream.io/api/agent/checkout" } } ``` ### 保存 key ```bash # Keep both out of chat, commits and logs. export TWEETSTREAM_API_KEY='' export TWEETSTREAM_SETUP_PROOF='' ``` ## 发起结账 先问对方想要哪个套餐，再发起结账。对方只会拿到一个付款链接，页面在扣款前会显示价格。默认使用加密货币：页面通过加密钱包付款。如需改用银行卡，加上 `"paymentRail":"CARD"`。 - `planType` 为 `BASIC`（Minimum）或 `ELITE`（Pro）。`billingCycle` 可选 `MONTHLY`、`QUARTERLY`、`SEMIANNUAL` 或 `YEARLY`。 - 如果账号还有试用，结账会使用试用：`offer.mode` 为 `trial`，`amountDueNow` 为 0。 - `offer.renewal.amount` 是在 `renewal.at` 扣的第一笔费用，`renewal.thenAmount` 是之后每次扣的费用。如果试用押金抵扣了第一笔费用，两者会不同。 - 结账时带上 setup proof。如果这次购买需要 Discord，响应中就会有加入链接。没有有效的 proof 时，`next` 为 `reverify_email`：重新申请并验证验证码，再用新的 proof 发送同一个结账请求。 - 每次购买生成一个 `Idempotency-Key`，重试时沿用，这样重试会返回同一个结账。 - 把 `paymentUrl` 交给对方，由对方在页面上付款。然后查询 `next.pollUrl`。 - `GET /api/agent/catalog` 列出所有套餐、价格和额度。 ### 发起结账 ```bash CHECKOUT_KEY=$(uuidgen) # one key per purchase; reuse it on retries curl -s https://tweetstream.io/api/agent/checkout \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ -H "Idempotency-Key: $CHECKOUT_KEY" \ -H 'Content-Type: application/json' \ -d '{"family":"BASE","planType":"ELITE","billingCycle":"MONTHLY"}' ``` ### 201 响应 ```json { "status": "payment_required", "family": "BASE", "reason": "new", "checkoutId": "pl_8k2m4q7x", "offer": { "mode": "trial", "planName": "Pro", "amountDueNow": { "currency": "USD", "minor": "0" }, "renewal": { "amount": { "currency": "USD", "minor": "49900" }, "at": "2026-11-01T12:00:00.000Z", "billingCycle": "MONTHLY", "thenAmount": { "currency": "USD", "minor": "49900" } } }, "paymentUrl": "https://tweetstream.io/pay/EXAMPLE_PAYMENT_LINK", "next": { "action": "open_payment", "who": "human", "url": "https://tweetstream.io/pay/EXAMPLE_PAYMENT_LINK", "pollUrl": "https://tweetstream.io/api/agent/status?family=BASE", "afterSeconds": 5 } } ``` ### 或者：用银行卡付款（两个结账只运行一个） ```bash # Instead of the crypto checkout above, not after it: a new purchase gets its own key. CARD_CHECKOUT_KEY=$(uuidgen) curl -s https://tweetstream.io/api/agent/checkout \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ -H "Idempotency-Key: $CARD_CHECKOUT_KEY" \ -H 'Content-Type: application/json' \ -d '{"family":"BASE","planType":"ELITE","billingCycle":"MONTHLY","paymentRail":"CARD"}' ``` ## 按提示加入 Discord 部分购买需要对方先加入 TweetStream Discord 服务器：付费 Base 套餐，以及所有 Ultra Speed 和 Instagram Tracking 购买。Base 试用不需要。此时结账会返回 `community_required`。 - 带上 setup proof 时，结账响应会包含加入链接。没有有效的 proof 时，`next` 为 `reverify_email`。之后需要再次获取链接时，带上 proof 调用 `POST /api/agent/discord-link`。 - 把链接交给对方。对方加入前，状态查询返回 `wait_for_discord`，加入后返回 `resume_checkout`。 - 用相同的 `Idempotency-Key` 再次发送同一个结账请求，响应中会有付款链接。 - 状态查询从不包含加入链接。 ### 200 响应 ```json { "status": "community_required", "family": "BASE", "reason": "COMMUNITY_REQUIRED", "checkoutId": "pl_8k2m4q7x", "discord": { "url": "https://tweetstream.io/connect/discord/EXAMPLE_DISCORD_LINK", "expiresAt": "2026-10-29T13:00:00.000Z" }, "next": { "action": "join_discord", "who": "human", "url": "https://tweetstream.io/connect/discord/EXAMPLE_DISCORD_LINK", "pollUrl": "https://tweetstream.io/api/agent/status?checkoutId=pl_8k2m4q7x", "afterSeconds": 5 } } ``` ## 查询直到 ready 对方完成操作后，每隔 `next.afterSeconds` 秒查询一次 `next.pollUrl`。每个响应只有一个 `status` 和一个 `next`，`next.who` 说明该由你还是对方操作。 开通状态之后可能变化，例如试用结束时。如果实时流拒绝 key，请重新查询状态。 | 状态 | 含义 | 下一步 | | --- | --- | --- | | `awaiting_email` | 验证码已发送到邮箱。 | `verify_email`：向对方索取验证码，并确认对方同意服务条款。 | | `payment_required` | 该产品还没有套餐或试用。 | `create_checkout`、`open_payment`（把链接交给对方）或 `resume_checkout`。 | | `community_required` | 这次购买需要对方先加入 TweetStream Discord 服务器。 | `join_discord`、`issue_discord_link`、`wait_for_discord` 或 `reverify_email`。 | | `processing` | 正在确认付款。 | `wait`：稍后再次查询。 | | `ready` | 产品已开通。 | `select_accounts`、`save_credential` 或 `connect`。`optionalSteps` 可能会提供 Discord 链接。 | | `closed` | 结账已过期或已取消。 | 用新的 key 执行 `create_checkout`。 | | `blocked` | 账号需要人工支持处理，或 Ultra Speed 选中的账号超过套餐额度。 | `resolve`：告知对方，或关闭部分 Ultra 账号。 | ### 查询状态 ```bash until curl -s "https://tweetstream.io/api/agent/status?family=BASE" \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" | grep -q '"status":"ready"'; do sleep 5 done ``` ### ready 响应 ```json { "status": "ready", "family": "BASE", "access": { "kind": "trial", "through": "2026-11-01T12:00:00.000Z" }, "stream": { "url": "wss://ws-global.tweetstream.io/ws", "subprotocol": "tweetstream.v1", "credentialScope": "STANDARD" }, "next": { "action": "select_accounts", "who": "agent", "method": "POST", "url": "https://tweetstream.io/api/add-account" }, "optionalSteps": [ { "action": "issue_discord_link", "who": "agent", "method": "POST", "url": "https://tweetstream.io/api/agent/discord-link" } ] } ``` ## 选择账号并连接 添加要推送的 X 账号，然后在 `Authorization` 请求头中带上 key，连接 `stream.url`。 - [WebSocket 快速开始](https://tweetstream.io/zh-cn/docs/quickstart): 输出第一条事件，再按 `t` 和 `op` 分流。 - [完整示例](https://tweetstream.io/zh-cn/docs/examples): 可自动重连并合并更新的 TypeScript 或 Python 消费者。 - 如果 WebSocket 客户端无法设置请求头，把 key 作为子协议 `tweetstream.auth.token.` 与 `tweetstream.v1` 一起发送。不要把 key 放进 URL。 - 之后，WebSocket 快速开始和完整示例可以直接使用。 ### 添加账号 ```bash curl -s https://tweetstream.io/api/add-account \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"accounts":["coinbase","binance"]}' ``` ### 连接 ```bash npx wscat -c wss://ws-global.tweetstream.io/ws -s tweetstream.v1 \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` ## 错误码 错误的格式为 `{"error":{"code","message","retryAfterSeconds"},"next"}`。按 `code` 分支处理；`message` 是给人看的说明。每个错误都有 `next`，按它操作。`retry` 表示在 `next.afterSeconds` 秒后重新发送同一个请求。 | 错误码 | HTTP | 处理方式 | | --- | --- | --- | | `INVALID_REQUEST` | 400 | 修正请求体或请求头。未知字段会被拒绝。 | | `INVALID_CODE` | 400 | 请对方核对验证码，或重新申请一个。 | | `TERMS_NOT_ACCEPTED` | 400 | 请对方先接受服务条款，再发送 `acceptTerms: true`。 | | `INVALID_API_KEY` | 401 | 检查 `TWEETSTREAM_API_KEY`。轮换后的旧 key 会失效。 | | `REVERIFY_EMAIL` | 401 | setup proof 缺失或已过期。重新申请并验证验证码。 | | `ACCOUNT_RESTRICTED` | 403 | 停止操作，并告诉对方联系支持。 | | `ORIGIN_REJECTED` | 403 | 从服务器或终端调用，不要带浏览器的 `Origin` 请求头。 | | `CHECKOUT_NOT_FOUND` | 404 | 检查 `checkoutId`，或按 `family` 查询状态。 | | `NOT_ENTITLED` | 404 | 先完成结账，再查询状态直到 `ready`。 | | `PAYMENT_LINK_INVALID` | 404 | 重新发起结账以获得新的付款链接。 | | `DISCORD_LINK_INVALID` | 404 | 重新生成 Discord 链接。 | | `IDEMPOTENCY_CONFLICT` | 409 | 这个 `Idempotency-Key` 已用于不同的请求体。请换一个新 key。 | | `CHECKOUT_CONFLICT` | 409 | 该产品已有未完成的结账。查询状态并按提示操作。 | | `OFFER_CHANGED` | 409 | 价格或套餐已变化。把新的报价告诉对方。 | | `TRIAL_UNAVAILABLE` | 409 | 该账号没有可用试用。请发起付费结账。 | | `TRIAL_AUTHORIZATION_REQUIRED` | 409 | 此试用需要 TweetStream 团队提供的代码。 | | `RATE_LIMITED` | 429 | 等待 `retryAfterSeconds` 秒后重试。 | | `ACTIVATION_BUDGET_EXHAUSTED` | 429 | 试用开通次数过多。等待 `retryAfterSeconds` 秒。 | | `TEMPORARILY_UNAVAILABLE` | 503 | 使用退避重试，并保持相同的 `Idempotency-Key`。 | ## 保管好 key - 把 key 存在 `TWEETSTREAM_API_KEY` 或密钥管理工具中。不要粘贴到聊天里、提交到代码库或打印出来。 - 只通过 `Authorization` 请求头或认证子协议发送 key。URL 会进入日志，所以不要使用 `?apiKey=`。 - 如果 key 已泄露，例如被提交、写入日志或留在共享的对话记录中，请轮换它：带上 setup proof 调用 `POST /api/agent/credentials/rotate`，或使用 MCP 工具 `rotate_api_key`。旧 key 会立即失效，响应中包含新 key。也可以在控制台 API 页点击“Regenerate key”。 - 轮换主 key（`BASE`）也会让 setup proof 失效，因为 proof 属于这个 key：下次需要 proof 的调用前，请先验证新的验证码。轮换 Ultra Speed key（`ULTRA`）不影响 setup proof。 - `setupProof` 同样是机密，30 分钟后过期。 ### 轮换 key ```bash # Needs a setup proof from the last 30 minutes. If it expired, verify a new email code first. curl -s https://tweetstream.io/api/agent/credentials/rotate \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ -H 'Content-Type: application/json' \ -d '{"family":"BASE"}' ``` ## 使用 MCP 服务器 支持远程 MCP 服务器的智能体可以用工具完成同样的流程。服务器地址是 `https://tweetstream.io/mcp`。对方在浏览器中用邮箱验证码登录一次，并在那里接受服务条款。客户端配置中不含任何机密。 ### Claude Code ```bash claude mcp add --transport http tweetstream https://tweetstream.io/mcp # Then run /mcp in Claude Code and sign in. ``` ### Cursor（~/.cursor/mcp.json） ```json { "mcpServers": { "tweetstream": { "url": "https://tweetstream.io/mcp" } } } ``` ### Codex ```bash codex mcp add tweetstream --url https://tweetstream.io/mcp codex mcp login tweetstream ``` ## Ultra Speed、Instagram 和 Scale 所有产品都用同样的调用开通，只是结账请求体不同。 - [OpenAPI 3.1](https://tweetstream.io/zh-cn/docs/openapi.json): 所有智能体路由及其请求和响应 schema。 - Ultra Speed：`{"family":"ULTRA","accountLimit":10}`。开通后，带上 setup proof 用 `POST /api/agent/credentials` 和 `{"family":"ULTRA"}` 读取单独的 key，再用 `POST /api/ultra/accounts` 选择账号。 - Instagram Tracking：`{"family":"INSTAGRAM","accountLimit":15}`。用 `POST /api/instagram/add-account` 添加账号，并用 `tweetstream.instagram.v1` 连接 `wss://insta-ws.tweetstream.io/ws`。 - Scale：`{"family":"BASE","planType":"ENTERPRISE","monitoredAccountLimit":500,"websocketLimit":2}`。如果有 TweetStream 团队提供的试用代码，改为调用 `POST /api/agent/scale-trial`，请求体为 `{"code":""}`。