> ## 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://grantex-auth-dd4mtrt2gq-uc.a.run.app/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>