---
title: "Get guest wallet and payment status"
method: GET
path: "/guest-wallets/status"
tags: ["Guest Wallets"]
---

# Get guest wallet and payment status

`GET /guest-wallets/status`

Poll after payment. Use usable to decide whether paid reads can run. An active wallet can remain usable while a top-up is pending. A new wallet becomes usable only after payment is verified. Send the guest key as Authorization: Bearer.

## Response `200`

Guest wallet status without exposing the API key.

- GuestWalletStatusResponse — Current balance, usability, and latest guest purchase state.
  - `balance` string, required
  - `latest_purchase` GuestWalletPurchaseStatus, required — Latest guest wallet purchase fulfillment state.
    - `amount` GuestWalletAmount, required — Confirmed USD amount for a guest wallet purchase.
      - `amount_minor` integer, required — USD amount in cents. Accepted range is $10-$250.
      - `currency` 'usd', required
    - `checkout_url` string, uri, nullable, required — Present only while the purchase is pending.
    - `credits` string, required
    - `expires_at` string, date-time, required
    - `purchase_id` string, required
    - `status` 'creating' | 'pending' | 'paid' | 'expired' | 'failed' | 'refunded' | 'disputed', required
  - `poll_after_seconds` 2, nullable, required — Polling delay while payment is pending. Null means stop.
  - `scope` 'paid_reads', required
  - `status` 'active' | 'pending' | 'expired' | 'failed' | 'frozen' | 'closed', required — Combined wallet and pending-checkout state. A pending top-up can coexist with usable true. Terminal expired or failed states require a new guest wallet.
  - `top_up` object, nullable, required — Top-up action when usable and no checkout is pending.
    - `method` 'POST', required
    - `path` '/api/v1/guest-wallets/topups', required
  - `usable` boolean, required — Authoritative paid-read readiness. Use instead of status.
  - `wallet_id` string, required

## Other responses

- `401` — Unauthenticated
- `429` — Guest wallet request limit exceeded.

## Changes

- **2026-08-12** `d8082b3892a2` — 24 warning
  - added the new `invalid_complete_replies_request` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `401`
  - added the new `invalid_complete_replies_request` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `429`
  - added the new `invalid_complete_replies_request` enum value to the `error/oneOf[subschema #2: StructuredError]/code` response property for the response status `401`
  - added the new `invalid_complete_replies_request` enum value to the `error/oneOf[subschema #2: StructuredError]/code` response property for the response status `429`
  - …20 more
- **2026-08-11** `f6affe6e547e` — 1 info
  - the `latest_purchase/anyOf[#/components/schemas/GuestWalletPurchaseStatus]/checkout_url/anyOf[subschema #1]/` response's property pattern `^https://buy\.stripe\.com/` was removed for the status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/xquik-dev/apis/xquik-api/changes/guest-wallets/status/get.md)

---

[API](https://skmtc.dev/xquik-dev/apis/xquik-api.md) · [All operations](https://skmtc.dev/xquik-dev/apis/xquik-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api/revisions/d8082b3892a2/schema)