> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick top-up credits

> Instantly charge a saved payment method for X API credits with a USD 10 minimum and USD 500 maximum

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="circle-check" color="#16a34a">
  **Free** - does not consume credits
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  response=$(curl -sS -X POST https://xquik.com/api/v1/credits/quick-topup \
    -H "x-api-key: xq_YOUR_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{"dollars": 25}')
  outcome=$(jq -r '.outcome' <<<"$response")

  if [ "$outcome" = "requires_action" ]; then
    client_secret=$(jq -r '.clientSecret' <<<"$response")
    # Pass $client_secret to the billing confirmation flow; do not print it.
  elif [ "$outcome" = "charged" ]; then
    jq '{outcome, credits, balance}' <<<"$response"
  else
    jq '{outcome}' <<<"$response"
  fi
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://xquik.com/api/v1/credits/quick-topup", {
    method: "POST",
    headers: {
      "x-api-key": "xq_YOUR_KEY_HERE",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ dollars: 25 }),
  });
  const result = await response.json();

  if (result.outcome === "requires_action") {
    const paymentClientSecret = result.clientSecret;
    // Pass paymentClientSecret to the billing confirmation flow; do not print it.
  } else if (result.outcome === "charged") {
    process.stdout.write(`Added ${result.credits} credits. Balance: ${result.balance}\n`);
  } else {
    process.stdout.write("Add a payment method before quick top-up.\n");
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://xquik.com/api/v1/credits/quick-topup",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      json={"dollars": 25},
  )
  data = response.json()
  if data["outcome"] == "requires_action":
      payment_client_secret = data["clientSecret"]
      # Pass payment_client_secret to the billing confirmation flow; do not print it.
  elif data["outcome"] == "charged":
      print(f"Added {data['credits']} credits. Balance: {data['balance']}")
  else:
      print("Add a payment method before quick top-up.")
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      body, _ := json.Marshal(map[string]interface{}{
          "dollars": 25,
      })

      req, err := http.NewRequest("POST", "https://xquik.com/api/v1/credits/quick-topup", bytes.NewReader(body))
      if err != nil {
          panic(err)
      }
      req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
      req.Header.Set("Content-Type", "application/json")

      resp, err := http.DefaultClient.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      var data map[string]interface{}
      if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
          panic(err)
      }
      outcome, _ := data["outcome"].(string)
      if outcome == "requires_action" {
          clientSecret, _ := data["clientSecret"].(string)
          // Pass clientSecret to the billing confirmation flow; do not print it.
          _ = clientSecret
      } else if outcome == "charged" {
          credits, _ := data["credits"].(string)
          balance, _ := data["balance"].(string)
          fmt.Printf("Added %s credits. Balance: %s\n", credits, balance)
      } else {
          fmt.Println("Add a payment method before quick top-up.")
      }
  }
  ```
</CodeGroup>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key. Session cookie authentication is also supported.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="dollars" type="number" required>
  Amount in US dollars to charge. Minimum $10, maximum $500.
</ParamField>

At USD 0.00015 per credit, a USD 25 quick top-up adds 166,666 credits, rounded down to whole credits.

Only the `charged` outcome grants credits and updates `balance`. If the endpoint returns `requires_action`, complete payment authentication with `clientSecret` before retrying the metered API call. Pass `clientSecret` to the billing confirmation flow only; do not print it in logs. If it returns `no_payment_method`, create a checkout top-up instead.

## Response

<Tabs>
  <Tab title="200 Charged">
    Payment succeeded immediately. Credits added to your balance.

    <ResponseField name="outcome" type="string">Always `"charged"`.</ResponseField>
    <ResponseField name="balance" type="string">Updated credit balance after top-up (Bigint string).</ResponseField>
    <ResponseField name="credits" type="string">Number of credits added (Bigint string).</ResponseField>

    ```json theme={null}
    {
      "outcome": "charged",
      "balance": "466666",
      "credits": "166666"
    }
    ```
  </Tab>

  <Tab title="200 Requires action">
    Payment requires additional authentication (e.g., 3D Secure). Use the returned client secret with the billing confirmation flow to complete the payment.

    <ResponseField name="outcome" type="string">Always `"requires_action"`.</ResponseField>
    <ResponseField name="clientSecret" type="string">Payment client secret for completing the payment.</ResponseField>

    ```json theme={null}
    {
      "outcome": "requires_action",
      "clientSecret": "pi_3abc...secret_xyz"
    }
    ```
  </Tab>

  <Tab title="200 No payment method">
    No saved payment method on file. Redirect the user to add one via the billing portal, or use the standard [top-up endpoint](/api-reference/credits/topup) instead.

    <ResponseField name="outcome" type="string">Always `"no_payment_method"`.</ResponseField>

    ```json theme={null}
    {
      "outcome": "no_payment_method"
    }
    ```
  </Tab>

  <Tab title="400 Invalid input">
    ```json theme={null}
    { "error": "Invalid input" }
    ```

    The request body is missing a numeric `dollars` value or includes too many decimal places.
  </Tab>

  <Tab title="401 Unauthenticated">
    ```json theme={null}
    { "error": "unauthenticated" }
    ```

    Missing or invalid API key.
  </Tab>

  <Tab title="429 Rate Limited">
    ```json theme={null}
    { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
    ```

    Too many requests. Wait for the `Retry-After` header before retrying.
  </Tab>
</Tabs>

<Note>
  **Related:** [Top Up Credits](/api-reference/credits/topup) · [Get Top-Up Status](/api-reference/credits/topup-status) · [Get Credits](/api-reference/credits/get) · [Billing Guide](/guides/billing)
</Note>