智能体快速开始

这里的每一步都是 HTTP 调用，智能体无需打开控制台即可替对方执行：先试用免费沙盒，再用邮箱验证码注册，把一个付款链接交给对方，然后连接。

在聊天中打开

按产品代码校对：2026年10月29日

先试用沙盒

沙盒无需账号，也无需 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。过期后重新申请并验证验证码。

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": "<the account's API key, shown once>",
  "setupProof": "<setup proof, valid for 30 minutes>",
  "next": {
    "action": "create_checkout",
    "who": "agent",
    "method": "POST",
    "url": "https://tweetstream.io/api/agent/checkout"
  }
}

发起结账

先问对方想要哪个套餐，再发起结账。对方只会拿到一个付款链接，页面在扣款前会显示价格。默认使用加密货币：页面通过加密钱包付款。如需改用银行卡，加上 "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 快速开始输出第一条事件，再按 t 和 op 分流。完整示例可自动重连并合并更新的 TypeScript 或 Python 消费者。

如果 WebSocket 客户端无法设置请求头，把 key 作为子协议 tweetstream.auth.token.<API_KEY> 与 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所有智能体路由及其请求和响应 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":"<code>"}。