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

# Fund Existing Milestone with Admin Balance

> Apply restricted admin-balance funding to an existing eligible unfunded milestone without creating a duplicate.

Applies OpenTrain's restricted `ADMIN_BALANCE` funding marker to one existing eligible `NOT_FUNDED` milestone. The operation updates that milestone in place; it never creates a replacement contract or milestone.

This endpoint is available only to eligible OpenTrain platform administrators in the canonical admin organization. It is deliberately separate from [ordinary employer milestone funding](/docs/developers/api-reference/milestones/fund), and it does not accept a client-controlled funding source.

Success transitions the existing milestone to `ACTIVE_FUNDED`, moves \$0, and creates no Stripe charge or PaymentIntent. Releasing payment later remains a separate human-authorized action.

## Authorization and validation

The server independently verifies every restricted platform-admin condition described on [Create Admin-Balance Milestone](/docs/developers/api-reference/contracts/create-admin-balance-milestone). It also verifies that:

* the milestone belongs to the named contract and authorized organization;
* the milestone is still eligible and `NOT_FUNDED`;
* its amount, contract rate, and volume are internally consistent; and
* sequencing and unresolved-payment rules allow funding.

## Request

<ParamField path="contractId" type="string" required>
  Contract that must own the milestone.
</ParamField>

<ParamField path="milestoneId" type="string" required>
  Existing eligible `NOT_FUNDED` milestone.
</ParamField>

<ParamField body="idempotencyKey" type="string" required>
  Stable request key, 1–128 characters. Identical retries return the original result; conflicting reuse fails closed.
</ParamField>

No funding-source field is accepted.

## Response

Returns `200`. The result includes the contract and job IDs, the existing milestone ID and new status, `fundingSource: "ADMIN_BALANCE"`, `moneyMoved: false`, `releaseRequiresHumanApproval: true`, and `idempotentReplay`.

## TypeScript SDK

`@opentrain-ai/sdk` 0.22.0 or later exposes the same operation:

```ts theme={null}
import { OpenTrainClient } from '@opentrain-ai/sdk';

const opentrain = new OpenTrainClient({
  apiToken: process.env.OPENTRAIN_API_TOKEN!,
});

const result = await opentrain.fundAdminBalanceMilestone(
  '<CONTRACT_ID>',
  '<MILESTONE_ID>',
  { idempotencyKey: 'fund-existing-milestone-2026-09' }
);
```

## Errors

| Status | Meaning                                                                                                   |
| ------ | --------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid key or internally inconsistent amount/rate/volume data                                            |
| `401`  | Missing or invalid token                                                                                  |
| `403`  | A restricted authorization condition failed, or a payment hold blocks the operation                       |
| `404`  | Contract or milestone not found within the authorized organization boundary                               |
| `409`  | Idempotency conflict, ineligible milestone state, existing funding-source conflict, or sequencing blocker |

<RequestExample>
  ```bash curl theme={null}
  curl -sS -X POST https://app.opentrain.ai/api/public/v1/contracts/<CONTRACT_ID>/admin-balance-milestones/<MILESTONE_ID>/fund \
    -H "Authorization: Bearer $OT_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"idempotencyKey":"fund-existing-milestone-2026-09"}'
  ```

  ```bash CLI theme={null}
  opentrain admin-balance-milestones fund \
    --contract-id <CONTRACT_ID> \
    --milestone-id <MILESTONE_ID> \
    --idempotency-key fund-existing-milestone-2026-09 \
    --json
  ```

  ```json MCP: opentrain_fund_admin_balance_milestone theme={null}
  {
    "contractId": "<CONTRACT_ID>",
    "milestoneId": "<MILESTONE_ID>",
    "idempotencyKey": "fund-existing-milestone-2026-09"
  }
  ```
</RequestExample>