Debit Budget

Debit an amount from a grant’s budget allocation. Returns 402 if the budget is insufficient.

Endpoint

POST /v1/budget/debit

Authentication

Requires a developer API key in the Authorization header.

Request Headers

Header	Value
Authorization	Bearer <api_key>
Content-Type	application/json

Request Body

Field	Type	Required	Description
grantId	string	Yes	The grant whose budget to debit
amount	number	Yes	The amount to debit (must be positive)
description	string	No	Human-readable description of the charge
metadata	object	No	Arbitrary metadata to attach to the transaction

Example Request

curl -X POST https://api.grantex.dev/v1/budget/debit \
  -H "Authorization: Bearer gx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "grantId": "grnt_01HXYZ...",
    "amount": 5.50,
    "description": "GPT-4 API call",
    "metadata": { "model": "gpt-4", "tokens": 1500 }
  }'

Response — 200 OK

{
  "remaining": 94.50,
  "transactionId": "txn_01HXYZ...",
  "grantId": "grnt_01HXYZ..."
}

Response Fields

Field	Type	Description
remaining	number	Budget remaining after the debit
transactionId	string	Unique transaction ID for this debit
grantId	string	The grant that was debited

Error Responses

Status	Code	Description
400	BAD_REQUEST	Missing grantId or amount not positive
401	UNAUTHORIZED	Invalid or missing API key
402	INSUFFICIENT_BUDGET	The grant’s remaining budget is less than the requested amount

SDK Examples

TypeScript

import Grantex from '@grantex/sdk';

const grantex = new Grantex({ apiKey: 'gx_...' });

const result = await grantex.budgets.debit({
  grantId: 'grnt_01HXYZ...',
  amount: 5.50,
  description: 'GPT-4 API call',
});
// result.remaining === 94.50

from grantex import Grantex

grantex = Grantex(api_key="gx_...")

result = grantex.budgets.debit(
    grant_id="grnt_01HXYZ...",
    amount=5.50,
    description="GPT-4 API call",
)
# result.remaining == 94.50