`get_allocations_by_orgid_lots`

Read-only

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

One organization's allocation as lots, oldest first

Each allocation (an ALLOCATION credit) is a LOT, and the allocation is consumed OLDEST FIRST: a batch minted or grown, or a revoke, draws on the oldest lot with anything left and runs on into the next, so one spend may draw on several lots. A return — a batch shrunk, a voucher's unspent remainder, a credit-back — goes back to the lots it was drawn from, then to the oldest lot with room; money no lot can take back (the remainder of a pool-funded batch, a credit-back on an account with nothing drawn) is a lot of its own, dated and described by the line that brought it. For each lot, remaining = granted − drawn + returned, and the lots' remaining values sum to the organization's allocation balance in GET /api/allocations. The ledger lines' lots in GET /api/allocations/{orgId}/ledger name the movements behind each lot's drawn and returned. An organization that has never been funded answers 200 with no lots. One whose lots do not hold its balance — lines not attributed to a lot, or a balance its ledger does not explain — answers 409 with the cents, rather than lots that leave money out. 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_lots",
    "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 lots, oldest first, in CENTS.

json

{
  "currency": "string",
  "lots": [
    {
      "description": "string",
      "drawn": 1,
      "grantTransactionId": "11111111-1111-4111-8111-111111111111",
      "granted": 1,
      "grantedAt": 1,
      "remaining": 1,
      "returned": 1
    }
  ],
  "orgId": "11111111-1111-4111-8111-111111111111"
}

Fields

Field	Type	Description
`currency`	string
`lots`	array of object
`lots[].description`	string \| null	Free text recorded on the lot's transaction.
`lots[].drawn`	integer	What batches minted or grown and revokes have drawn from this lot, cumulatively, in CENTS.
`lots[].grantTransactionId`	string (uuid)	The transaction that is the lot — an ALLOCATION, or the credit that holds money no other lot could take back.
`lots[].granted`	integer	What the lot holds, in CENTS.
`lots[].grantedAt`	integer	When the lot's money was allocated, epoch MILLISECONDS.
`lots[].remaining`	integer	What of this lot is still unspent, in CENTS — `granted − drawn + returned`.
`lots[].returned`	integer	What shrinks, unspent remainders and credit-backs have given back to this lot, cumulatively, in CENTS.
`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.
409: The resource is not in a state that allows this operation.

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_lots",
  "description": "GET /api/allocations/{orgId}/lots — Each allocation (an ALLOCATION credit) is a LOT, and the allocation is consumed OLDEST FIRST: a batch minted or grown, or a revoke, draws on the oldest lot with anything left and runs on into the next, so one spend may draw on several lots. A return — a batch shrunk, a voucher's unspent remainder, a credit-back — goes back to the lots it was drawn from, then to the oldest lot with room; money no lot can take back (the remainder of a pool-funded batch, a credit-back on an account with nothing drawn) is a lot of its own, dated and described by the line that brought it. For each lot, `remaining = granted − drawn + returned`, and the lots' `remaining` values sum to the organization's allocation balance in `GET /api/allocations`. The ledger lines' `lots` in `GET /api/allocations/{orgId}/ledger` name the movements behind each lot's `drawn` and `returned`. An organization that has never been funded answers 200 with no lots. One whose lots do not hold its balance — lines not attributed to a lot, or a balance its ledger does not explain — answers 409 with the cents, rather than lots that leave money out. 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
  }
}