List Credit Ledger

Lists every credit ledger entry on your account, newest first, with cursor pagination. Each entry links the related top-up, proposal, contract, or milestone so you can reconcile balance changes against the actions that caused them.

amountCents is signed: positive entries add to the available balance, negative entries draw from it. Accounts that have never used credits get an empty page (not a 404).

Requirements: payments:read scope + the public_api_credits feature. Works pre-claim.

Entry types

type	Meaning
TOP_UP	A completed top-up added funds
HOLD	Funds reserved into escrow (hire or milestone funding)
HOLD_RELEASE	A hold returned to the available balance (e.g. milestone cancelled)
CAPTURE	Held funds paid out (milestone released)
REFUND	Funds returned to the account
ADJUSTMENT	Manual correction by OpenTrain

Request

cursorstringquery

Opaque cursor from a previous response’s nextCursor. Omit for the first page.

limitintegerquery

Default: 50

Page size, 1–100. Out-of-range values return 400.

Response

entriesobject[]

ledger entry

idstring

Ledger entry ID.

typestring

One of the entry types above.

amountCentsnumber

Signed amount in US cents.

createdAtstring

ISO timestamp.

holdEntryIdstring | null

For HOLD_RELEASE/CAPTURE, the originating HOLD entry.

jobofferIdstring | null

Related proposal, when the entry came from a hire.

contractIdstring | null

Related contract.

milestoneIdstring | null

Related milestone.

topUpIdstring | null

Related top-up, for TOP_UP entries.

notestring | null

Free-text note (mostly on ADJUSTMENT entries).

nextCursorstring | null

Pass as cursor to fetch older entries; null at the end of the ledger.

Errors

Status	code	Meaning
400	BAD_REQUEST	limit outside 1–100 (details: {field: "limit"})
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Missing payments:read scope, or public_api_credits disabled

Request examples

curlCLIMCP: opentrain_list_credit_ledger

curl

curl -sS "https://app.opentrain.ai/api/public/v1/credits/ledger?limit=25" \
  -H "Authorization: Bearer $OT_API_TOKEN"

CLI

opentrain credits ledger --limit 25 --json

MCP: opentrain_list_credit_ledger

{
  "limit": 25
}

Response examples

200

{
  "entries": [
    {
      "id": "<ENTRY_ID>",
      "type": "TOP_UP",
      "amountCents": 10000,
      "createdAt": "2026-06-12T10:00:00.000Z",
      "holdEntryId": null,
      "jobofferId": null,
      "contractId": null,
      "milestoneId": null,
      "topUpId": "<TOP_UP_ID>",
      "note": null
    },
    {
      "id": "<ENTRY_ID_2>",
      "type": "HOLD",
      "amountCents": -2500,
      "createdAt": "2026-06-11T15:30:00.000Z",
      "holdEntryId": null,
      "jobofferId": "<PROPOSAL_ID>",
      "contractId": "<CONTRACT_ID>",
      "milestoneId": "<MILESTONE_ID>",
      "topUpId": null,
      "note": null
    }
  ],
  "nextCursor": "<CURSOR>"
}