Top Up Guest Wallet Credits for X API Reads

{
  "account_required": false,
  "amount": {
    "amount_minor": 1000,
    "currency": "usd"
  },
  "checkout_url": "https://checkout.example/guest/example",
  "credits": "66666",
  "expires_at": "2026-07-13T13:00:00.000Z",
  "instructions": "Give checkout_url to the user. They must complete payment on the hosted checkout page. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.",
  "poll_after_seconds": 2,
  "purchase_id": "gp_example",
  "requires_user_interaction": true,
  "status": "pending"
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

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

{
  "error": "idempotency_conflict",
  "message": "Reuse this Idempotency-Key only with the original request."
}

{
  "error": "checkout_unavailable",
  "message": "Checkout unavailable. Retry with a new Idempotency-Key."
}

{
  "error": "body_too_large",
  "message": "Request body is too large."
}

{
  "error": "unsupported_media_type",
  "message": "Send Content-Type: application/json."
}

{
  "error": "guest_wallet_unavailable",
  "message": "Guest wallet unavailable. Create a new wallet or contact support."
}

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

{
  "error": "guest_wallets_unavailable",
  "message": "Guest wallet checkout is temporarily unavailable."
}

POST

guest-wallets

topups

Top Up Guest Wallet Credits for X API Reads

curl --request POST \
  --url https://xquik.com/api/v1/guest-wallets/topups \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount_minor": 123,
  "currency": "<string>"
}
'

import requests

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

payload = {
    "amount_minor": 123,
    "currency": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>",
    "Idempotency-Key": "<idempotency-key>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<authorization>',
    'Content-Type': '<content-type>',
    'Idempotency-Key': '<idempotency-key>'
  },
  body: JSON.stringify({amount_minor: 123, currency: '<string>'})
};

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"amount_minor\": 123,\n  \"currency\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Idempotency-Key", "<idempotency-key>")

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

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

	fmt.Println(string(body))

}

{
  "account_required": true,
  "amount": {},
  "checkout_url": "<string>",
  "credits": "<string>",
  "expires_at": "<string>",
  "instructions": "<string>",
  "purchase_id": "<string>",
  "status_url": "<string>",
  "poll_after_seconds": 123,
  "requires_user_interaction": true,
  "status": "<string>",
  "wallet_id": "<string>"
}

Add credits to an existing guest wallet. The wallet keeps the same paid_reads key. This endpoint creates a one-use hosted checkout only after the user confirms the amount. It does not charge the user.

Never call this endpoint automatically after a 402. Show the available option and amount, then wait for explicit user confirmation.

idempotency_key=$(uuidgen | tr '[:upper:]' '[:lower:]')
curl -X POST https://xquik.com/api/v1/guest-wallets/topups \
  -H "Authorization: Bearer xq_your_guest_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $idempotency_key" \
  -d '{"amount_minor": 2500, "currency": "usd"}' | jq

Keep the current guest key and store the new Idempotency-Key as a secret. Give only checkout_url to the user. After payment, poll status_url every poll_after_seconds with the same key. Stop when latest_purchase.status is no longer pending. Use usable to decide whether paid reads can run.

Headers

string

required

Send the guest key as Bearer xq_your_guest_key_here.

string

required

Must be application/json.

string

required

A new cryptographically random UUID v4. Reuse it only for an exact retry of this top-up request.

Body

integer

required

Confirmed USD amount in cents. Minimum 1000 and maximum 25000.

string

required

Must be usd.

Response

boolean

Always false.

object

Confirmed amount in minor units and usd currency.

string

One-use hosted checkout URL for the user to open.

string

Credits to grant after verified payment.

string

Pending checkout expiry.

string

Required user interaction and polling guidance.

string

Guest purchase ID.

string

Guest wallet status URL.

integer

Minimum polling delay. Always 2 while pending.

boolean

Always true.

string

Initial top-up status. Normally pending.

string

Existing guest wallet ID.

{
  "account_required": false,
  "amount": { "amount_minor": 2500, "currency": "usd" },
  "checkout_url": "https://checkout.example/guest/example",
  "credits": "166666",
  "expires_at": "2026-07-13T13:00:00.000Z",
  "instructions": "Give checkout_url to the user. They must complete payment on the hosted checkout page. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.",
  "poll_after_seconds": 2,
  "purchase_id": "gp_example",
  "requires_user_interaction": true,
  "status": "pending",
  "status_url": "https://xquik.com/api/v1/guest-wallets/status",
  "wallet_id": "gw_example"
}

This response never returns a new API key.

The same Idempotency-Key was used for a different request.

Reduce the request body, then retry with the same Idempotency-Key.

Send Content-Type: application/json.

Wait for Retry-After before retrying the same request.

Checkout is temporarily unavailable. Retry with the same Idempotency-Key.

The response sends Cache-Control: no-store, private. An exact replay also sends Idempotent-Replayed: true.

{
  "account_required": false,
  "amount": {
    "amount_minor": 1000,
    "currency": "usd"
  },
  "checkout_url": "https://checkout.example/guest/example",
  "credits": "66666",
  "expires_at": "2026-07-13T13:00:00.000Z",
  "instructions": "Give checkout_url to the user. They must complete payment on the hosted checkout page. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.",
  "poll_after_seconds": 2,
  "purchase_id": "gp_example",
  "requires_user_interaction": true,
  "status": "pending"
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

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

{
  "error": "idempotency_conflict",
  "message": "Reuse this Idempotency-Key only with the original request."
}

{
  "error": "checkout_unavailable",
  "message": "Checkout unavailable. Retry with a new Idempotency-Key."
}

{
  "error": "body_too_large",
  "message": "Request body is too large."
}

{
  "error": "unsupported_media_type",
  "message": "Send Content-Type: application/json."
}

{
  "error": "guest_wallet_unavailable",
  "message": "Guest wallet unavailable. Create a new wallet or contact support."
}

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

{
  "error": "guest_wallets_unavailable",
  "message": "Guest wallet checkout is temporarily unavailable."
}

Top Up Guest Wallet Credits for X API Reads

curl --request POST \
  --url https://xquik.com/api/v1/guest-wallets/topups \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount_minor": 123,
  "currency": "<string>"
}
'

import requests

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

payload = {
    "amount_minor": 123,
    "currency": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>",
    "Idempotency-Key": "<idempotency-key>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<authorization>',
    'Content-Type': '<content-type>',
    'Idempotency-Key': '<idempotency-key>'
  },
  body: JSON.stringify({amount_minor: 123, currency: '<string>'})
};

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"amount_minor\": 123,\n  \"currency\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Idempotency-Key", "<idempotency-key>")

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

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

	fmt.Println(string(body))

}

{
  "account_required": true,
  "amount": {},
  "checkout_url": "<string>",
  "credits": "<string>",
  "expires_at": "<string>",
  "instructions": "<string>",
  "purchase_id": "<string>",
  "status_url": "<string>",
  "poll_after_seconds": 123,
  "requires_user_interaction": true,
  "status": "<string>",
  "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

Top Up Guest Wallet Credits for X API Reads

Headers

Body

Response

​Headers

​Body

​Response

Headers

Body

Response