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

# Get guest wallet and payment status

`GET /api/v1/guest-wallets/status`

Poll after Stripe 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 verified webhook fulfillment. 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.
- `default` — Unexpected error.

---

[API](https://skmtc.net/xquik-dev/apis/xquik-api-2.md) · [All operations](https://skmtc.net/xquik-dev/apis/xquik-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api-2/versions/c70f0e286159/schema)