`get_allocations_by_orgid_ledger`

Read-only

Calls GET /api/allocations/{orgId}/ledger as the signed-in person · REST reference

One organization's allocation as ledger lines, with the running balance

Every movement on the organization's ORG_ALLOCATION account, NEWEST FIRST: a grant (ALLOCATION, CREDIT), a revoke (ALLOCATION, DEBIT), a batch minted or grown against it (ALLOCATION_COMMIT, DEBIT), a batch shrunk or a voucher's unspent remainder returned (ALLOCATION_RELEASE, CREDIT), and a credit-back when an approved or clawed-back voucher's value is reversed (VOUCHER_INVALIDATION, CREDIT). balanceAfter is a running sum of the lines, not the account's stored balance, so a gap between the newest line's balanceAfter and the account balance in GET /api/allocations is a ledger discrepancy. An organization that has never been funded answers 200 with no lines. The caller's own bearer token is forwarded to the DAL. All amounts are integer CENTS.

Arguments

Argument	Type		Description
`orgId`path	string (uuid)	required	Organization whose allocation to read. A non-UUID is refused by the DAL as a 400.
`currency`query	string		Currency of the allocation account to read. Applied only when sent as a string; anything else falls back to USD.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_allocations_by_orgid_ledger",
    "arguments": {
      "orgId": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

The allocation's lines, newest first, in CENTS.

json

{
  "currency": "string",
  "lines": [
    {
      "amount": 1,
      "balanceAfter": 1,
      "createdAt": 1,
      "description": "string",
      "lots": [],
      "purpose": "string",
      "reference": "string",
      "side": "CREDIT",
      "transactionId": "11111111-1111-4111-8111-111111111111",
      "type": "string"
    }
  ],
  "orgId": "11111111-1111-4111-8111-111111111111"
}

Fields

Field	Type	Description
`currency`	string
`lines`	array of object
`lines[].amount`	integer	The line's amount, in CENTS. Always positive; `side` gives the direction.
`lines[].balanceAfter`	integer	The allocation after this line, in CENTS.
`lines[].createdAt`	integer	Epoch MILLISECONDS.
`lines[].description`	string \| null	Free text recorded on the transaction; a revoke's reason.
`lines[].lots`	array of object	The lot(s) this line touched: what a spend or revoke drew from each lot, oldest first, or what a return gave back to each — the line itself when it holds money no other lot could take back. Empty on an allocation itself, and on a line not yet attributed to a lot.
`lines[].lots[].amount`	integer	This line's share of that lot, in CENTS.
`lines[].lots[].grantTransactionId`	string (uuid)	The lot's transaction.
`lines[].purpose`	string \| null	The ledger line's purpose (org_allocation, org_allocation_revoke, allocation_commit, allocation_release, …).
`lines[].reference`	string \| null	What the movement names — a batch id, a voucher code, the organization.
`lines[].side`	"CREDIT" \| "DEBIT"	CREDIT adds to the allocation; DEBIT spends or revokes it.
`lines[].transactionId`	string (uuid)
`lines[].type`	string	The ledger transaction's type — ALLOCATION, ALLOCATION_COMMIT, ALLOCATION_RELEASE or VOUCHER_INVALIDATION on this account.
`orgId`	string (uuid)

When it fails

A failed call returns isError: true with the API's message as text.

400: The request was malformed or failed a guard.
403: Authenticated, but the caller holds none of the required permissions.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json

{
  "name": "get_allocations_by_orgid_ledger",
  "description": "GET /api/allocations/{orgId}/ledger — Every movement on the organization's ORG_ALLOCATION account, NEWEST FIRST: a grant (ALLOCATION, CREDIT), a revoke (ALLOCATION, DEBIT), a batch minted or grown against it (ALLOCATION_COMMIT, DEBIT), a batch shrunk or a voucher's unspent remainder returned (ALLOCATION_RELEASE, CREDIT), and a credit-back when an approved or clawed-back voucher's value is reversed (VOUCHER_INVALIDATION, CREDIT). `balanceAfter` is a running sum of the lines, not the account's stored balance, so a gap between the newest line's `balanceAfter` and the account balance in `GET /api/allocations` is a ledger discrepancy. An organization that has never been funded answers 200 with no lines. The caller's own bearer token is forwarded to the DAL. All amounts are integer CENTS.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orgId": {
        "type": "string",
        "description": "Organization whose allocation to read. A non-UUID is refused by the DAL as a 400."
      },
      "currency": {
        "type": "string",
        "description": "Currency of the allocation account to read. Applied only when sent as a string; anything else falls back to USD."
      }
    },
    "required": [
      "orgId"
    ]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}