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

# Get guest wallet status

> Check guest wallet activation, balance, payment status, and paid-read scope

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

Poll this endpoint after the user completes Stripe checkout. The guest key can authenticate this status route while the wallet is pending, but it cannot call paid read routes until a verified Stripe webhook activates it.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://xquik.com/api/v1/guest-wallets/status \
    -H "Authorization: Bearer xq_your_guest_key_here" | jq
  ```
</CodeGroup>

Wait at least `poll_after_seconds` before polling again. Continue while it is non-null, then stop. Use `usable` to decide whether paid reads can run. An active wallet can remain usable while a top-up is pending.

## Headers

<ParamField header="Authorization" type="string" required>
  Send the guest key as `Bearer xq_your_guest_key_here`.
</ParamField>

## Response

<ResponseField name="balance" type="string">Available guest wallet credits.</ResponseField>
<ResponseField name="scope" type="string">Always `paid_reads`.</ResponseField>
<ResponseField name="status" type="string">Combined wallet and pending-checkout state: `active`, `pending`, `expired`, `failed`, `frozen`, or `closed`. A pending top-up can coexist with `usable: true`.</ResponseField>
<ResponseField name="usable" type="boolean">Whether the key can call eligible paid read routes.</ResponseField>
<ResponseField name="poll_after_seconds" type="integer | null">`2` while payment is pending. Otherwise `null`.</ResponseField>
<ResponseField name="latest_purchase" type="object | null">Latest amount, credits, expiry, purchase ID, checkout URL while pending, and purchase status.</ResponseField>
<ResponseField name="top_up" type="object | null">Direct REST top-up action when the wallet is usable and has no pending checkout.</ResponseField>
<ResponseField name="wallet_id" type="string">Guest wallet ID.</ResponseField>

## Interpret the result

Use these fields together:

| Condition                                      | Meaning                                                   | Action                                                             |
| ---------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ |
| `usable: true`, `status: active`               | Paid reads can run. No checkout is pending.               | Call eligible reads. Use `top_up` only after confirmation.         |
| `usable: true`, `status: pending`              | Existing credits remain usable while a top-up is pending. | Continue affordable reads. Poll after the stated delay.            |
| `usable: false`, `status: pending`             | The initial checkout still awaits verified payment.       | Do not call paid reads. Poll after the stated delay.               |
| `usable: false`, `status: expired` or `failed` | The initial checkout reached a terminal state.            | Stop polling. Get new confirmation before creating another wallet. |
| `usable: false`, `status: frozen` or `closed`  | Wallet access is unavailable.                             | Stop paid reads. Do not retry payment automatically.               |

`latest_purchase.status` describes only the latest purchase. Use the top-level `usable` field for paid-read access.

<Tabs>
  <Tab title="200 OK">
    ```json theme={null}
    {
      "balance": "66666",
      "latest_purchase": {
        "amount": { "amount_minor": 1000, "currency": "usd" },
        "checkout_url": null,
        "credits": "66666",
        "expires_at": "2026-07-13T13:00:00.000Z",
        "purchase_id": "gp_example",
        "status": "paid"
      },
      "poll_after_seconds": null,
      "scope": "paid_reads",
      "status": "active",
      "top_up": {
        "method": "POST",
        "path": "/api/v1/guest-wallets/topups"
      },
      "usable": true,
      "wallet_id": "gw_example"
    }
    ```
  </Tab>

  <Tab title="401 Unauthenticated">
    The guest key is missing or invalid. No email or account recovery is available.
  </Tab>

  <Tab title="429 Rate limited">
    Wait for `Retry-After` before polling again.
  </Tab>
</Tabs>

Use `usable` to decide whether the key can call paid reads.

The response sends `Cache-Control: no-store, private` and never returns the guest key.

<Note>
  **Related:** [Guest wallet guide](/guides/guest-wallets) · [Create guest wallet](/api-reference/guest-wallets/create) · [Top up guest wallet](/api-reference/guest-wallets/topup)
</Note>