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

# Budgets

> Allocate per-grant spending budgets, debit usage, check balances, and view transaction history

## 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.

```go theme={null}
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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `GrantID` | `string` | Yes | The grant ID to allocate a budget for. |
| `InitialBudget` | `float64` | Yes | The initial budget amount. Must be positive. |

### Response (`BudgetAllocation`)

| Field | Type | Description |
| - | - | - |
| `ID` | `string` | Unique budget allocation identifier. |
| `GrantID` | `string` | The associated grant ID. |
| `InitialBudget` | `float64` | The original allocated budget amount. |
| `RemainingBudget` | `float64` | The current remaining budget amount. |
| `CreatedAt` | `string` | ISO 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.

```go theme={null}
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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `GrantID` | `string` | Yes | The grant ID to debit from. |
| `Amount` | `float64` | Yes | The amount to debit. Must be positive. |
| `Description` | `*string` | No | Optional description for the transaction. |

### Response (`DebitResponse`)

| Field | Type | Description |
| - | - | - |
| `Remaining` | `float64` | The remaining budget after the debit. |
| `TransactionID` | `string` | Unique identifier for the transaction. |

<Warning>
  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.
</Warning>

## Balance

Check the current budget balance for a grant.

```go theme={null}
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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `grantID` | `string` | Yes | The 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.

```go theme={null}
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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `grantID` | `string` | Yes | The grant ID to list transactions for. |
| `Page` | `*int` | No | Page number for pagination (default: 1). |
| `PageSize` | `*int` | No | Results per page (default: 20, max: 100). |

### Response (`TransactionsResponse`)

| Field | Type | Description |
| - | - | - |
| `Transactions` | `[]BudgetTransaction` | Slice of transaction records. |
| `Total` | `int` | Total number of transactions for this grant. |

### `BudgetTransaction`

| Field | Type | Description |
| - | - | - |
| `ID` | `string` | Unique transaction identifier. |
| `Amount` | `float64` | The debited amount. |
| `Description` | `*string` | Optional description. |
| `CreatedAt` | `string` | ISO 8601 timestamp of the transaction. |
| `BalanceAfter` | `float64` | Remaining budget after this transaction. |

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.