访客钱包

无需账户即可获取预付费 TwexAPI 密钥：AI 代理创建 Stripe 卡支付，用户支付后，密钥即可在所有端点和 MCP 上使用。

访客钱包

访客钱包是一种无需账户、注册或电子邮件的预付费 TwexAPI API 密钥。AI 代理通过一个请求创建钱包，并返回一个 API 密钥和 Stripe 支付链接。用户通过银行卡支付该链接，然后该密钥即可在 TwexAPI 的每个端点和 MCP 服务器上使用，就像账户密钥一样。

选择访问方法

当代理需要一个正常 API 密钥，而用户不想创建账户时，请使用访客钱包。当代理有自己的钱包并按请求付费时，请使用 MPP。对于任何长期使用的情况，请使用账户密钥。

创建和激活钱包

1. 确认金额。 钱包使用 10 到 250 美元 USD 资金，作为 amount_minor 以分的形式发送（1000 到 25000）。Credits 以每 USD 100,000 的标准速率添加，因此 10 美元购买 1,000,000 Credits。有关请求的成本，请参阅 定价。

2. 创建结账。 在 Idempotency-Key 标头中发送一个新的 UUID v4：

curl -sS https://api.twexapi.io/guest-wallets \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \
  -d '{"amount_minor": 1000, "currency": "usd"}'

{
  "code": 200,
  "msg": "success",
  "data": {
    "wallet_id": "6f1c2a4e-8b3d-4c5e-9a7f-1d2e3f4a5b6c",
    "api_key": "twitterx_...",
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
    "checkout_expires_at": "2026-10-29T14:21:01.000Z",
    "status_url": "/guest-wallets/status",
    "poll_after_seconds": 5,
    "purchase": {
      "id": "0b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "kind": "create",
      "status": "pending",
      "amount_minor": 1000,
      "currency": "usd",
      "credits": 1000000
    }
  }
}

3. 存储 key。 立即保存 api_key 到秘密存储库。这是钱包的唯一凭证，TwexAPI 无法为您恢复它。

4. 向用户提供结账链接。 向用户展示 checkout_url 并要求他们支付。该链接只能使用一次，并在 60 分钟后过期。在支付确认之前，API 调用将返回 401。

5. 轮询直到密钥可用。 在调用之间等待 poll_after_seconds：

curl -sS https://api.twexapi.io/guest-wallets/status \
  -H "Authorization: Bearer $GUEST_KEY"

{
  "code": 200,
  "msg": "success",
  "data": {
    "wallet_id": "6f1c2a4e-8b3d-4c5e-9a7f-1d2e3f4a5b6c",
    "key_hint": "twitterx_1a2…9f0e",
    "usable": true,
    "paused": false,
    "available_credits": 1000000,
    "latest_purchase": { "kind": "create", "status": "completed", "credits": 1000000 },
    "poll_after_seconds": null
  }
}

只有在 usable 为 true 时才调用 API。完成的结账页面本身并不表示 Credits 已添加。latest_purchase.status 在支付确认之前为 pending，然后为 completed。未支付的结账变为 expired，而延迟支付的拒绝变为 failed。一旦没有更多等待的事情，poll_after_seconds 为 null。

调用 API

可用的访客密钥适用于每个端点，具有与账户密钥相同的速率限制和计费：

curl -sS https://api.twexapi.io/twitter/advanced_search/page \
  -H "Authorization: Bearer $GUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["openai"], "sortBy": "Latest"}'

当 Credits 用完时，请求返回 403 并带有 No available credits!。充值钱包以继续。

充值钱包

充值将 Credits 添加到同一钱包和密钥。再次与用户确认金额，然后发送一个新的 UUID v4：

curl -sS https://api.twexapi.io/guest-wallets/topups \
  -H "Authorization: Bearer $GUEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \
  -d '{"amount_minor": 2000, "currency": "usd"}'

响应中有一个新的 checkout_url。将其提供给用户，然后轮询相同的状态端点，直到 latest_purchase.status 为 completed。

无密钥的请求

向任何 TwexAPI 端点发送不带凭据的请求将返回 403 并带有 WWW-Authenticate: Bearer realm="twexapi" 标头。随后的 code、msg 和 data 字段后面跟着一个 auth_options 对象，列出了获取访问权限的方式，包括如何创建访客钱包：

{
  "code": 403,
  "msg": "未认证",
  "data": [],
  "auth_options": {
    "account": { "scheme": "Bearer", "dashboard": "https://twexapi.io/dashboard" },
    "guest_wallet": {
      "method": "POST",
      "url": "https://api.twexapi.io/guest-wallets",
      "idempotency_header": "Idempotency-Key",
      "body": { "amount_minor": 1000, "currency": "usd" },
      "amount_minor_min": 1000,
      "amount_minor_max": 25000,
      "status_url": "https://api.twexapi.io/guest-wallets/status"
    },
    "pay_per_request": { "scheme": "Payment", "endpoints": ["POST /twitter/advanced_search/page", "..."] },
    "mcp": { "url": "https://api.twexapi.io/mcp", "pay_per_call_url": "https://api.twexapi.io/mcp/pay" },
    "docs": "https://twexapi.io/llms.txt"
  }
}

auth_options 告诉代理可以做什么。它不是花费金钱的许可：代理仍然需要用户同意金额后才能创建钱包。

使用访客密钥与 MCP

一旦钱包可用，将 MCP 客户端连接到 https://api.twexapi.io/mcp 并使用 Authorization: Bearer 标头中的访客密钥，如 MCP 概述 中所述。创建钱包、充值和检查状态是 REST-only；没有 MCP 工具。

错误

一致性和安全重试

每个创建和充值请求都需要其自己的 UUID v4 在 Idempotency-Key 中。如果请求超时，请以相同的关键不变地再次发送它：您将获得原始结果，并带有 Idempotent-Replayed: true 标头，并且没有第二个结账。重复使用密钥进行不同的金额或不同的请求返回 422。

保护钱包访问

• 不要将访客密钥和 Idempotency-Key 值放在 URL、日志和聊天记录中。重复创建请求会再次返回 API 密钥。
• 响应以 Cache-Control: no-store, private 发送。不要缓存它们。
• 在调用 API 之前，依赖于状态端点的 usable，而不是结账页面。
• 如果发生支付争议，整个钱包将暂停（paused: true）并且密钥将停止工作，直到案件解决。

常见问题解答

我可以不使用账户就使用 TwexAPI Twitter API 吗？

是的。访客钱包为您提供一个无需注册的预付费 API 密钥，MPP 允许拥有 Tempo 钱包的代理按请求付费，无需任何密钥。

AI 代理可以自己为 TwexAPI 付费吗？

不能：访客钱包需要有人支付 Stripe 结账。拥有 Tempo 上的 USDC 并按请求付费的代理可以使用 MPP。

访客密钥是否限于某些端点？

不。一旦支付，访客密钥即可在所有端点和 MCP 服务器上使用，具有与账户密钥相同的定价和速率限制。

我可以将访客钱包转换为账户吗？

目前不可以。继续使用访客密钥并充值，或者创建账户并使用其密钥进行新的工作。

下一步

• 认证 以获取账户 API 密钥
• 机器支付协议 以获取按请求付费的访问权限
• MCP 概述 以使用 AI 客户端的密钥
• 定价 了解每请求的 Credit 成本