Skip to main content

​
Overview

The Budgets service manages per-grant spending budgets. Allocate budgets when issuing grants, debit as agents consume resources, check remaining balances, and review transaction history.

​
Allocate

Allocate a spending budget for a grant. Threshold alerts are automatically triggered at 50% and 80% consumption. 
allocation, err := client.Budgets.Allocate(ctx, grantex.AllocateBudgetParams{
    GrantID:       "grnt_01HXYZ...",
    InitialBudget: 1000,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Budget ID: %s\n", allocation.ID)
fmt.Printf("Initial: %.2f\n", allocation.InitialBudget)
fmt.Printf("Remaining: %.2f\n", allocation.RemainingBudget)

​
Parameters

ParameterTypeRequiredDescription
GrantIDstringYesThe grant ID to allocate a budget for.
InitialBudgetfloat64YesThe initial budget amount. Must be positive.

​
Response (BudgetAllocation)

FieldTypeDescription
IDstringUnique budget allocation identifier.
GrantIDstringThe associated grant ID.
InitialBudgetfloat64The original allocated budget amount.
RemainingBudgetfloat64The current remaining budget amount.
CreatedAtstringISO 8601 timestamp when the allocation was created.

​
Debit

Debit an amount from a grant’s budget. Uses atomic operations to prevent overdraft. Returns an error with HTTP 402 and code INSUFFICIENT_BUDGET if the balance is insufficient. 
result, err := client.Budgets.Debit(ctx, grantex.DebitBudgetParams{
    GrantID:     "grnt_01HXYZ...",
    Amount:      50,
    Description: grantex.String("GPT-4 API call"),
})
if err != nil {
    // Check for insufficient budget
    var apiErr *grantex.APIError
    if errors.As(err, &apiErr) && apiErr.StatusCode == 402 {
        fmt.Println("Insufficient budget")
        return
    }
    log.Fatal(err)
}
fmt.Printf("Remaining: %.2f\n", result.Remaining)
fmt.Printf("Transaction ID: %s\n", result.TransactionID)

​
Parameters

ParameterTypeRequiredDescription
GrantIDstringYesThe grant ID to debit from.
Amountfloat64YesThe amount to debit. Must be positive.
Description*stringNoOptional description for the transaction.

​
Response (DebitResponse)

FieldTypeDescription
Remainingfloat64The remaining budget after the debit.
TransactionIDstringUnique identifier for the transaction.
Debits are all-or-nothing. If the remaining budget is less than the debit amount, the API returns HTTP 402 with code INSUFFICIENT_BUDGET and the debit is not applied.

​
Balance

Check the current budget balance for a grant. 
allocation, err := client.Budgets.Balance(ctx, "grnt_01HXYZ...")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%.2f / %.2f remaining\n", allocation.RemainingBudget, allocation.InitialBudget)

​
Parameters

ParameterTypeRequiredDescription
grantIDstringYesThe grant ID to check the balance for.

​
Response

Returns a BudgetAllocation — same struct as Allocate. See above for field descriptions.

​
Transactions

List all transactions for a grant’s budget. Supports pagination. 
result, err := client.Budgets.Transactions(ctx, "grnt_01HXYZ...", grantex.PaginationParams{
    Page:     grantex.Int(1),
    PageSize: grantex.Int(50),
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Total: %d\n", result.Total)
for _, txn := range result.Transactions {
    fmt.Printf("  %s: -%.2f (balance: %.2f)\n", *txn.Description, txn.Amount, txn.BalanceAfter)
}

​
Parameters

ParameterTypeRequiredDescription
grantIDstringYesThe grant ID to list transactions for.
Page*intNoPage number for pagination (default: 1).
PageSize*intNoResults per page (default: 20, max: 100).

​
Response (TransactionsResponse)

FieldTypeDescription
Transactions[]BudgetTransactionSlice of transaction records.
TotalintTotal number of transactions for this grant.

​
BudgetTransaction

FieldTypeDescription
IDstringUnique transaction identifier.
Amountfloat64The debited amount.
Description*stringOptional description.
CreatedAtstringISO 8601 timestamp of the transaction.
BalanceAfterfloat64Remaining budget after this transaction.