Guest Wallets

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.

Choose an access method

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 for what a request costs.

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

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. 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:

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

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:

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:

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:

{
  "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. Creating a wallet, topping it up and checking its status are REST-only; there are no MCP tools for them.

Errors

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 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.

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 for account API keys
• Machine Payments Protocol for pay-per-request access
• MCP overview to use the key from an AI client
• Pricing for Credit costs per request