---
title: "Guest Wallets"
description: "Get a prepaid TwexAPI key without an account: an AI agent creates a Stripe card checkout, a person pays it, and the key works on every endpoint and on MCP."
---

# Guest Wallets

A guest wallet is a prepaid TwexAPI API key that needs no account, sign-up or email. An AI agent creates the wallet with one request and gets back an API key and a Stripe checkout link. A person pays that link by card, and the key then works on every TwexAPI endpoint and on the MCP server, exactly like an account key.

:::warning
A guest wallet always needs a person to pay. The agent creates the checkout and hands over the link; it never enters card details. Create a wallet only after the user has confirmed the amount.
:::

## Choose an access method

| Method | Account | Credential | Coverage | Payment |
|---|---|---|---|---|
| [Account API key](/authentication) | Yes | `Authorization: Bearer <API key>` | Every endpoint and MCP | Dashboard: card, PayPal or crypto |
| [MCP sign-in](/mcp/oauth) | Yes | OAuth in the MCP client | MCP tools | The account's Credits |
| Guest wallet | No | `Authorization: Bearer <guest key>` | Every endpoint and MCP | Card, through Stripe Checkout, prepaid |
| [MPP](/mpp/machine-payments-protocol) | No | `Authorization: Payment <credential>` | 12 paginated read endpoints | USDC on Tempo, per request |

Use a guest wallet when an agent needs a normal API key for a person who doesn't want an account. Use MPP when the agent has its own wallet and pays per request. Use an account key for anything long-lived.

## Create and activate a wallet

**1. Confirm the amount.** A wallet is funded with USD 10 to 250, sent as `amount_minor` in cents (`1000` to `25000`). Credits are added at the standard rate of 100,000 Credits per USD, so USD 10 buys 1,000,000 Credits. See [Pricing](/guides/pricing) for what a request costs.

**2. Create the checkout.** Send a new UUID v4 in the `Idempotency-Key` header:

```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. Store the key.** Save `api_key` in a secret store right away. It is the only credential for the wallet, and TwexAPI cannot recover it for you.

**4. Give the person the checkout link.** Show `checkout_url` to the user and ask them to pay it. The link can be used once and expires after 60 minutes. Until payment is confirmed, the key returns `401` on API calls.

**5. Poll until the key is usable.** Wait `poll_after_seconds` between calls:

```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
  }
}
```

Start calling the API only when `usable` is `true`. A finished checkout page alone doesn't mean the Credits have been added. `latest_purchase.status` is `pending` until payment is confirmed, then `completed`. An unpaid checkout becomes `expired`, and a declined delayed payment becomes `failed`. `poll_after_seconds` is `null` once there is nothing left to wait for.

## Call the API

A usable guest key works on every endpoint, with the same rate limits and billing as an account key:

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

When the Credits run out, requests return `403` with `No available credits!`. Top up the wallet to continue.

## Top up a wallet

Top-ups add Credits to the same wallet and key. Confirm the amount with the user again, then send a new 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"}'
```

The response has a new `checkout_url`. Give it to the person, then poll the same status endpoint until `latest_purchase.status` is `completed`.

## Requests without a key

A request without credentials to any TwexAPI endpoint returns `403` with a `WWW-Authenticate: Bearer realm="twexapi"` header. The usual `code`, `msg` and `data` fields are followed by an `auth_options` object that lists the ways to get access, including how to create a guest wallet:

```json
{
  "code": 403,
  "msg": "Not authenticated",
  "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` tells an agent what is possible. It is not permission to spend money: the agent still needs the user to agree to an amount before it creates a wallet.

## Use a guest key with MCP

Once the wallet is usable, connect an MCP client to `https://api.twexapi.io/mcp` with the guest key in the `Authorization: Bearer` header, as described in the [MCP overview](/mcp/overview). Creating a wallet, topping it up and checking its status are REST-only; there are no MCP tools for them.

## Errors

| Status | Meaning | What to do |
|---|---|---|
| `400` | Missing or invalid `Idempotency-Key`, `amount_minor` outside 1000–25000, or a currency other than `usd` | Fix the request |
| `401` | The bearer key is missing or isn't a guest wallet key | Send the guest key from step 2 |
| `403` | The wallet is paused | Contact support |
| `409` | A retried checkout request is too close to its expiry to finish | Retry with a new `Idempotency-Key` |
| `422` | The `Idempotency-Key` was already used for a different request | Use a new UUID v4 |
| `429` | Too many wallets created from one IP address in an hour | Wait and retry |

## Idempotency and safe retries

Every create and top-up request needs its own UUID v4 in `Idempotency-Key`. If a request times out, send it again unchanged with the same key: you get the original result, marked with an `Idempotent-Replayed: true` header, and no second checkout. Reusing a key for a different amount or a different request returns `422`.

## Protect wallet access

- Keep the guest key and `Idempotency-Key` values out of URLs, logs and chat transcripts. Replaying a create request with its `Idempotency-Key` returns the API key again.
- Responses are sent with `Cache-Control: no-store, private`. Don't cache them.
- Rely on `usable` from the status endpoint, not on the checkout page, before calling the API.
- If a payment is disputed, the whole wallet is paused (`paused: true`) and the key stops working until the case is resolved.

## FAQ

### Can I use the TwexAPI Twitter API without an account?

Yes. A guest wallet gives you a prepaid API key without signing up, and [MPP](/mpp/machine-payments-protocol) lets an agent with a Tempo wallet pay per request without any key.

### Can an AI agent pay for TwexAPI by itself?

Not with a guest wallet: a person always pays the Stripe checkout. An agent that holds its own USDC on Tempo can pay per request with [MPP](/mpp/machine-payments-protocol).

### Is a guest key limited to some endpoints?

No. Once paid, a guest key works on every endpoint and on the MCP server, with the same pricing and rate limits as an account key.

### Can I turn a guest wallet into an account later?

Not today. Keep using the guest key and top it up, or create an account and use its key for new work.

## Next steps

- [Authentication](/authentication) for account API keys
- [Machine Payments Protocol](/mpp/machine-payments-protocol) for pay-per-request access
- [MCP overview](/mcp/overview) to use the key from an AI client
- [Pricing](/guides/pricing) for Credit costs per request