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

# 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

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

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

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