---
title: "createBudgetTopup"
description: "Buy query budget for an agent credential"
canonical: "https://pgbeam.com/docs/ts-sdk/payments/createBudgetTopup"
last-updated: "2026-09-07T22:45:12.000Z"
---

# createBudgetTopup

> Buy query budget for an agent credential

URL: https://pgbeam.com/docs/ts-sdk/payments/createBudgetTopup

Buys additional queries for the agent credential this request is authenticated as, using the Machine Payments Protocol (HTTP 402 with the `Payment` authentication scheme).

Authenticate with the credential's hosted MCP token (`pba_...`) as a bearer token. The credential identifies itself, so no human and no dashboard session is involved.

Without a payment credential the response is `402` carrying a complete `WWW-Authenticate: Payment` challenge. Fulfil it, then repeat the request with the credential in the `Payment-Authorization` header (the challenge selects that field so the bearer token can stay in `Authorization`). On success the queries are granted, streamed to the data planes, and the response carries a `Payment-Receipt` header.

Purchased queries do not raise the credential's policy budget. They are a separate pool the proxy spends only once the policy's hourly and daily windows have refused a statement, and they expire.

## Usage

## Parameters

Parameter

Type

Required

Description

body.packs

`number`

No

Packs of query budget to buy. One pack is `units_per_pack` queries at `amount_per_pack`, both readable from `GET /v1/payments/resources`.

## Response

`Promise<BudgetTopup>`: payment settled and queries granted. the `payment-receipt` header carries the base64url receipt.

## Example

## Errors

Status

Description

400

The request was rejected. `code` is `INVALID_INPUT`, and `errors` names the offending fields when the failure was a validation one.

401

Missing or invalid authentication. `code` is `UNAUTHORIZED`.

402

Payment required. The `WWW-Authenticate` header carries a complete `Payment` challenge and the body carries RFC 9457 problem details explaining why. A failed or replayed credential also answers `402` with a fresh challenge, never `401`.

403

The caller is authenticated but not allowed to perform this operation. `code` is `FORBIDDEN` when the caller's role is insufficient, and `PLAN_LIMIT_REACHED` when the organization's plan is what stands in the way. The two are answered differently, so branch on the code rather than the status.

404

The resource does not exist, or the caller is not entitled to know that it does. `code` is `NOT_FOUND`.

429

Rate limited. `code` is `RATE_LIMITED`.

503

The service is temporarily unable to answer. `code` is `SERVICE_UNAVAILABLE`. Safe to retry after the delay in `Retry-After`.