> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Top up guest wallet credits for X API reads
> Create a USD 10-250 hosted checkout to add tweet, profile, follower, reply, timeline, community, and list read credits to a guest key. It charges nothing.
```json theme={null}
{
"account_required": false,
"amount": {
"amount_minor": 1000,
"currency": "usd"
},
"checkout_url": "https://checkout.example/guest/example",
"credits": "66666",
"expires_at": "2026-07-13T13:00:00.000Z",
"instructions": "Give checkout_url to the user. They must complete payment on the hosted checkout page. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.",
"poll_after_seconds": 2,
"purchase_id": "gp_example",
"requires_user_interaction": true,
"status": "pending"
}
```
```json theme={null}
{
"error": "invalid_input",
"message": "Invalid input. Check the request body."
}
```
```json theme={null}
{
"error": "unauthenticated",
"message": "Authentication required. Provide a valid API key or bearer token."
}
```
```json theme={null}
{
"error": "idempotency_conflict",
"message": "Reuse this Idempotency-Key only with the original request."
}
```
```json theme={null}
{
"error": "checkout_unavailable",
"message": "Checkout unavailable. Retry with a new Idempotency-Key."
}
```
```json theme={null}
{
"error": "body_too_large",
"message": "Request body is too large."
}
```
```json theme={null}
{
"error": "unsupported_media_type",
"message": "Send Content-Type: application/json."
}
```
```json theme={null}
{
"error": "guest_wallet_unavailable",
"message": "Guest wallet unavailable. Create a new wallet or contact support."
}
```
```json theme={null}
{
"error": "rate_limited",
"message": "Try again later."
}
```
```json theme={null}
{
"error": "guest_wallets_unavailable",
"message": "Guest wallet checkout is temporarily unavailable."
}
```
For the complete documentation index, see llms.txt.
Add credits to an existing guest wallet. The wallet keeps the same `paid_reads` key. This endpoint creates a one-use hosted checkout only after the user confirms the amount. It does not charge the user.
Never call this endpoint automatically after a `402`. Show the available option and amount, then wait for the user to confirm.
```bash cURL theme={null}
idempotency_key=$(uuidgen | tr '[:upper:]' '[:lower:]')
curl -X POST https://xquik.com/api/v1/guest-wallets/topups \
-H "Authorization: Bearer xq_your_guest_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $idempotency_key" \
-d '{"amount_minor": 2500, "currency": "usd"}' | jq
```
Keep the current guest key and store the new `Idempotency-Key` as a secret. Give only `checkout_url` to the user. After payment, poll `status_url` every `poll_after_seconds` with the same key. Stop when `latest_purchase.status` is no longer `pending`. Use `usable` to decide whether paid reads can run.
## Headers
Send the guest key as `Bearer xq_your_guest_key_here`.
Must be `application/json`.
A new cryptographically random UUID v4. Reuse it only for an exact retry of this top-up request.
## Body
Confirmed USD amount in cents. Minimum `1000` and maximum `25000`.
Must be `usd`.
## Response
Always `false`.
Confirmed amount in minor units and `usd` currency.
One-use hosted checkout URL for the user to open.
Credits to grant after verified payment.
Pending checkout expiry.
Required user interaction and polling guidance.
Guest purchase ID.
Guest wallet status URL.
Minimum polling delay. Always `2` while pending.
Always `true`.
Initial top-up status. Normally `pending`.
Existing guest wallet ID.
```json theme={null}
{
"account_required": false,
"amount": { "amount_minor": 2500, "currency": "usd" },
"checkout_url": "https://checkout.example/guest/example",
"credits": "166666",
"expires_at": "2026-07-13T13:00:00.000Z",
"instructions": "Give checkout_url to the user. They must complete payment on the hosted checkout page. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.",
"poll_after_seconds": 2,
"purchase_id": "gp_example",
"requires_user_interaction": true,
"status": "pending",
"status_url": "https://xquik.com/api/v1/guest-wallets/status",
"wallet_id": "gw_example"
}
```
This response never returns a new API key.
Check the UUID v4 header, amount, currency, JSON, and request fields.
The guest key is missing or invalid.
You used the same `Idempotency-Key` for a different request.
The checkout expired or no longer works.
Reduce the request body, then retry with the same `Idempotency-Key`.
Send `Content-Type: application/json`.
The wallet is unavailable. Check guest wallet status before taking another action.
Wait for `Retry-After` before retrying the same request.
Checkout is temporarily unavailable. Retry with the same `Idempotency-Key`.
The response sends `Cache-Control: no-store, private`. An exact replay also sends `Idempotent-Replayed: true`.
**Related.** [Guest wallet guide](/guides/guest-wallets) · [Create guest wallet](/api-reference/guest-wallets/create) · [Get guest wallet status](/api-reference/guest-wallets/status)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.