Guest Wallet API Status & Payment Activation

{
  "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"
  },
  "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"
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "rate_limited",
  "message": "Try again later."
}

GET

guest-wallets

status

Guest Wallet API Status & Payment Activation

curl --request GET \
  --url https://xquik.com/api/v1/guest-wallets/status \
  --header 'Authorization: <authorization>'

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 hosted checkout. The guest key can authenticate this status route while the wallet is pending, but it cannot call paid read routes until payment is verified.

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

string

required

Send the guest key as Bearer xq_your_guest_key_here.

Response

string

Available guest wallet credits.

string

Always paid_reads.

string

Combined wallet and pending-checkout state: active, pending, expired, failed, frozen, or closed. A pending top-up can coexist with usable: true.

boolean

Whether the key can call eligible paid read routes.

integer | null

2 while payment is pending. Otherwise null.

object | null

Latest amount, credits, expiry, purchase ID, checkout URL while pending, and purchase status.

object | null

Direct REST top-up action when the wallet is usable and has no pending checkout.

string

Guest wallet ID.

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.

200 OK
401 Unauthenticated
429 Rate limited

{
  "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"
}

Wait for Retry-After before polling again.

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.

{
  "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"
  },
  "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"
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "rate_limited",
  "message": "Try again later."
}

Guest Wallet API Status & Payment Activation

curl --request GET \
  --url https://xquik.com/api/v1/guest-wallets/status \
  --header 'Authorization: <authorization>'

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>"
}

Overview

X API

X Write

Trends

Radar

Account

API Keys

Guest Wallets

Credits

X Accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Guest Wallet API Status & Payment Activation

Headers

Response

Interpret the result

​Headers

​Response

​Interpret the result

Headers

Response

Interpret the result