Skip to main content
GET
/
guest-wallets
/
status
Get guest wallet status
curl --request GET \
  --url https://xquik.com/api/v1/guest-wallets/status \
  --header 'Authorization: <authorization>'
import requests

url = "https://xquik.com/api/v1/guest-wallets/status"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://xquik.com/api/v1/guest-wallets/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/guest-wallets/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
{
  "balance": "<string>",
  "scope": "<string>",
  "status": "<string>",
  "usable": true,
  "poll_after_seconds": {},
  "latest_purchase": {},
  "top_up": {},
  "wallet_id": "<string>"
}
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. 
curl https://xquik.com/api/v1/guest-wallets/status \
  -H "Authorization: Bearer xq_your_guest_key_here" | jq
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

​
Authorization
string
required
Send the guest key as Bearer xq_your_guest_key_here.

​
Response

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

​
Interpret the result

Use these fields together:
ConditionMeaningAction
usable: true, status: activePaid reads can run. No checkout is pending.Call eligible reads. Use top_up only after confirmation.
usable: true, status: pendingExisting credits remain usable while a top-up is pending.Continue affordable reads. Poll after the stated delay.
usable: false, status: pendingThe initial checkout still awaits verified payment.Do not call paid reads. Poll after the stated delay.
usable: false, status: expired or failedThe initial checkout reached a terminal state.Stop polling. Get new confirmation before creating another wallet.
usable: false, status: frozen or closedWallet 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. 
{
  "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"
}
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.
Related: Guest wallet guide · Create guest wallet · Top up guest wallet
Last modified on July 13, 2026