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

# 访客钱包

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

:::warning
访客钱包始终需要有人支付。代理创建结账并传递链接；它永远不会输入银行卡信息。只有在用户确认金额后才能创建钱包。
:::

## 选择访问方法

| 方法 | 账户 | 凭证 | 覆盖范围 | 支付 |
|---|---|---|---|---|
| [账户 API 密钥](/zh/authentication) | 是 | `Authorization: Bearer <API 密钥>` | 每个端点和 MCP | 仪表板：银行卡、PayPal 或加密货币 |
| [MCP 登录](/zh/mcp/oauth) | 是 | MCP 客户端的 OAuth | MCP 工具 | 账户的 Credits |
| 访客钱包 | 否 | `Authorization: Bearer <访客密钥>` | 每个端点和 MCP | 银行卡，通过 Stripe Checkout，预付费 |
| [MPP](/zh/mpp/machine-payments-protocol) | 否 | `Authorization: Payment <凭证>` | 12 个分页读取端点 | Tempo 上的 USDC，按请求付费 |

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

## 创建和激活钱包

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

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

```bash
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"}'
```

```json
{
  "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`：

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

```json
{
  "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

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

```bash
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：

```bash
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` 对象，列出了获取访问权限的方式，包括如何创建访客钱包：

```json
{
  "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 概述](/zh/mcp/overview) 中所述。创建钱包、充值和检查状态是 REST-only；没有 MCP 工具。

## 错误

| 状态 | 含义 | 应做什么 |
|---|---|---|
| `400` | 缺少或无效的 `Idempotency-Key`、`amount_minor` 超出 1000–25000 或货币不是 `usd` | 修复请求 |
| `401` | 缺少或无效的 bearer 密钥或不是访客钱包密钥 | 从步骤 2 发送访客密钥 |
| `403` | 钱包已暂停 | 联系支持 |
| `409` | 重试的结账请求太接近其到期时间而无法完成 | 使用新的 `Idempotency-Key` 重试 |
| `422` | `Idempotency-Key` 已用于不同的请求 | 使用新的 UUID v4 |
| `429` | 一小时内从同一 IP 地址创建的钱包太多 | 等待后重试 |

## 一致性和安全重试

每个创建和充值请求都需要其自己的 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](/zh/mpp/machine-payments-protocol) 允许拥有 Tempo 钱包的代理按请求付费，无需任何密钥。

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

不能：访客钱包需要有人支付 Stripe 结账。拥有 Tempo 上的 USDC 并按请求付费的代理可以使用 [MPP](/zh/mpp/machine-payments-protocol)。

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

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

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

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

## 下一步

- [认证](/zh/authentication) 以获取账户 API 密钥
- [机器支付协议](/zh/mpp/machine-payments-protocol) 以获取按请求付费的访问权限
- [MCP 概述](/zh/mcp/overview) 以使用 AI 客户端的密钥
- [定价](/zh/guides/pricing) 了解每请求的 Credit 成本