Overview
The budgets sub-client manages per-grant spending budgets. Allocate a budget when issuing a grant, debit against it as your agent consumes resources, check remaining balances, and review transaction history.
// Allocate, debit, check balance, list transactions
await grantex.budgets.allocate({ grantId: 'grnt_01HXYZ...', initialBudget: 1000 });
await grantex.budgets.debit({ grantId: 'grnt_01HXYZ...', amount: 50, description: 'API call' });
const balance = await grantex.budgets.balance('grnt_01HXYZ...');
const history = await grantex.budgets.transactions('grnt_01HXYZ...');
budgets.allocate()
Allocate a spending budget for a grant. The budget is denominated in your chosen unit (e.g., cents, tokens, credits). Threshold alerts are automatically triggered at 50% and 80% consumption.
const allocation = await grantex.budgets.allocate({
grantId: 'grnt_01HXYZ...',
initialBudget: 1000,
});
console.log(allocation.id); // 'bdg_01HXYZ...'
console.log(allocation.grantId); // 'grnt_01HXYZ...'
console.log(allocation.initialBudget); // 1000
console.log(allocation.remainingBudget); // 1000
console.log(allocation.createdAt); // '2026-03-08T10:00:00Z'
Parameters
The grant ID to allocate a budget for.
The initial budget amount. Must be a positive number.
Response: BudgetAllocation
Unique budget allocation identifier.
The original allocated budget amount.
The current remaining budget amount.
ISO 8601 timestamp when the allocation was created.
budgets.debit()
Debit an amount from a grant’s budget. Uses atomic operations (WHERE remaining >= amount) to prevent overdraft. Returns a 402 INSUFFICIENT_BUDGET error if the remaining balance is insufficient.
const result = await grantex.budgets.debit({
grantId: 'grnt_01HXYZ...',
amount: 50,
description: 'GPT-4 API call',
});
console.log(result.remaining); // 950
console.log(result.transactionId); // 'txn_01HXYZ...'
Parameters
The grant ID to debit from.
The amount to debit. Must be a positive number.
Optional description for the transaction (e.g., 'GPT-4 API call').
Response: DebitResponse
The remaining budget after the debit.
Unique identifier for the debit transaction.
If the remaining budget is less than the debit amount, the API returns a 402 error with code INSUFFICIENT_BUDGET. The debit is not applied partially — it either succeeds in full or fails entirely.
budgets.balance()
Check the current budget balance for a grant.
const allocation = await grantex.budgets.balance('grnt_01HXYZ...');
console.log(allocation.id); // 'bdg_01HXYZ...'
console.log(allocation.grantId); // 'grnt_01HXYZ...'
console.log(allocation.initialBudget); // 1000
console.log(allocation.remainingBudget); // 950
console.log(allocation.createdAt); // '2026-03-08T10:00:00Z'
Parameters
The grant ID to check the balance for.
Response: BudgetAllocation
Returns the same BudgetAllocation shape as allocate() — see above for field descriptions.
budgets.transactions()
List all transactions for a grant’s budget. Supports pagination.
const result = await grantex.budgets.transactions('grnt_01HXYZ...', {
page: 1,
pageSize: 50,
});
console.log(result.total); // 12
for (const txn of result.transactions) {
console.log(txn.id); // 'txn_01HXYZ...'
console.log(txn.amount); // 50
console.log(txn.description); // 'GPT-4 API call'
console.log(txn.createdAt); // '2026-03-08T10:05:00Z'
console.log(txn.balanceAfter); // 950
}
Parameters
The grant ID to list transactions for.
Page number for pagination (default: 1).
Number of results per page (default: 20, max: 100).
Response: TransactionsResponse
Array of transaction records.
Total number of transactions for this grant.
BudgetTransaction contains:
Unique transaction identifier.
Optional description of the transaction.
ISO 8601 timestamp when the transaction was created.
The remaining budget after this transaction.
Full example
import { Grantex } from '@grantex/sdk';
const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });
// Allocate a budget for a grant
const allocation = await grantex.budgets.allocate({
grantId: 'grnt_01HXYZ...',
initialBudget: 500,
});
console.log(`Budget allocated: ${allocation.initialBudget}`);
// Debit as the agent uses resources
const debit = await grantex.budgets.debit({
grantId: 'grnt_01HXYZ...',
amount: 25,
description: 'Document analysis',
});
console.log(`Remaining: ${debit.remaining}`);
// Check the current balance
const balance = await grantex.budgets.balance('grnt_01HXYZ...');
console.log(`${balance.remainingBudget} / ${balance.initialBudget} remaining`);
// Review transaction history
const { transactions, total } = await grantex.budgets.transactions('grnt_01HXYZ...');
console.log(`${total} transaction(s)`);
for (const txn of transactions) {
console.log(` ${txn.description}: -${txn.amount} (balance: ${txn.balanceAfter})`);
}
