@polygonlabs/staker-pool-allocations-schemas 0.1.0

package/openapi.json

@@ -0,0 +1,1215 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "staker-pool-allocations",
+    "version": "0.0.0",
+    "description": "Public REST API for the PIP-85 staker fee pool monthly merkle distributions. Read-only: distribution metadata, per-address allocations, claim history, and on-demand merkle proofs."
+  },
+  "servers": [
+    {
+      "url": "/"
+    }
+  ],
+  "components": {
+    "schemas": {
+      "OperationalStatus": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok"
+            ]
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "boolean",
+            "enum": [
+              true
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "info": {
+            "type": "object",
+            "additionalProperties": {
+              "nullable": true
+            }
+          }
+        },
+        "required": [
+          "error",
+          "message"
+        ],
+        "description": "Standard error response shape from `@polygonlabs/express`'s `createErrorHandler`. `info` is present when the underlying `HTTPError` carries structured info (e.g. validation failures, domain-specific context); absent for plain errors and most non-validation HTTPErrors."
+      },
+      "DistributionListResponse": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DistributionSummary"
+            }
+          },
+          "nextCursor": {
+            "type": "string",
+            "nullable": true
+          }
+        },
+        "required": [
+          "items",
+          "nextCursor"
+        ]
+      },
+      "DistributionSummary": {
+        "type": "object",
+        "properties": {
+          "distributionId": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}$",
+            "example": "2026-04"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "running",
+              "completed",
+              "failed"
+            ],
+            "example": "completed"
+          },
+          "startPoSBlock": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          },
+          "endPoSBlock": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          },
+          "merkleRoot": {
+            "type": "string",
+            "nullable": true,
+            "pattern": "^0x[0-9a-fA-F]{64}$",
+            "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+          },
+          "totalAllocated": {
+            "type": "string",
+            "nullable": true,
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          },
+          "completedAt": {
+            "type": "string",
+            "nullable": true,
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "distributionId",
+          "status",
+          "startPoSBlock",
+          "endPoSBlock",
+          "merkleRoot",
+          "totalAllocated",
+          "completedAt"
+        ]
+      },
+      "DistributionDetail": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/DistributionSummary"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "checkpointCount": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "polUsdPrice": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^[0-9]+(\\.[0-9]{1,6})?$",
+                "example": "0.423100"
+              },
+              "maxClaimableUsdThreshold": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^[0-9]+(\\.[0-9]{1,6})?$",
+                "example": "0.423100"
+              },
+              "inputsHash": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^0x[0-9a-fA-F]{64}$",
+                "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+              },
+              "posStakingSubgraphBlock": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^[0-9]+$",
+                "example": "1234567890000000000"
+              },
+              "posStakingSubgraphHash": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^0x[0-9a-fA-F]{64}$",
+                "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+              },
+              "posCheckpointsSubgraphBlock": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^[0-9]+$",
+                "example": "1234567890000000000"
+              },
+              "posCheckpointsSubgraphHash": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^0x[0-9a-fA-F]{64}$",
+                "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+              },
+              "posPriorityFeesSubgraphBlock": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^[0-9]+$",
+                "example": "1234567890000000000"
+              },
+              "posPriorityFeesSubgraphHash": {
+                "type": "string",
+                "nullable": true,
+                "pattern": "^0x[0-9a-fA-F]{64}$",
+                "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+              }
+            },
+            "required": [
+              "checkpointCount",
+              "polUsdPrice",
+              "maxClaimableUsdThreshold",
+              "inputsHash",
+              "posStakingSubgraphBlock",
+              "posStakingSubgraphHash",
+              "posCheckpointsSubgraphBlock",
+              "posCheckpointsSubgraphHash",
+              "posPriorityFeesSubgraphBlock",
+              "posPriorityFeesSubgraphHash"
+            ]
+          }
+        ]
+      },
+      "ValidationErrorResponse": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "boolean",
+            "enum": [
+              true
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "info": {
+            "$ref": "#/components/schemas/ValidationErrorInfo"
+          }
+        },
+        "required": [
+          "error",
+          "message",
+          "info"
+        ],
+        "description": "Narrowed `ErrorResponse` for 400s emitted by the registry-driven router when request validation fails. `info` is non-optional and carries the section-keyed `ValidationErrorInfo` shape."
+      },
+      "ValidationErrorInfo": {
+        "type": "object",
+        "properties": {
+          "params": {
+            "$ref": "#/components/schemas/ZodErrorTree"
+          },
+          "query": {
+            "$ref": "#/components/schemas/ZodErrorTree"
+          },
+          "body": {
+            "$ref": "#/components/schemas/ZodErrorTree"
+          },
+          "headers": {
+            "$ref": "#/components/schemas/ZodErrorTree"
+          }
+        },
+        "description": "Section-keyed map of request validation failures. Only sections that failed appear; each value is the `z.treeifyError` tree for that section. Clients can wire e.g. `info.body.properties.label.errors[0]` directly into field-level UI feedback rather than walking a flat issue list."
+      },
+      "ZodErrorTree": {
+        "type": "object",
+        "properties": {
+          "errors": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "properties": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/ZodErrorTree"
+            }
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ZodErrorTree"
+            }
+          }
+        },
+        "required": [
+          "errors"
+        ],
+        "description": "Recursive Zod validation error tree (the output of `z.treeifyError`). `errors` carries the messages at this node; `properties` keys nested object errors by field name; `items` indexes nested array errors."
+      },
+      "AllocationListResponse": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AllocationRow"
+            }
+          },
+          "nextCursor": {
+            "type": "string",
+            "nullable": true
+          }
+        },
+        "required": [
+          "items",
+          "nextCursor"
+        ]
+      },
+      "AllocationRow": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "type": "string",
+            "pattern": "^0x[0-9a-f]{40}$",
+            "example": "0xabc0000000000000000000000000000000000001"
+          },
+          "amount": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          },
+          "leafIndex": {
+            "type": "integer",
+            "nullable": true,
+            "minimum": 0
+          }
+        },
+        "required": [
+          "address",
+          "amount",
+          "leafIndex"
+        ]
+      },
+      "ExcludedAllocationsResponse": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExcludedAllocationRow"
+            }
+          },
+          "total": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "totalAmount": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          }
+        },
+        "required": [
+          "items",
+          "total",
+          "totalAmount"
+        ]
+      },
+      "ExcludedAllocationRow": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "type": "string",
+            "pattern": "^0x[0-9a-f]{40}$",
+            "example": "0xabc0000000000000000000000000000000000001"
+          },
+          "amount": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          }
+        },
+        "required": [
+          "address",
+          "amount"
+        ]
+      },
+      "AllocationHistoryResponse": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AllocationHistoryRow"
+            }
+          }
+        },
+        "required": [
+          "items"
+        ]
+      },
+      "AllocationHistoryRow": {
+        "type": "object",
+        "properties": {
+          "distributionId": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}$",
+            "example": "2026-04"
+          },
+          "address": {
+            "type": "string",
+            "pattern": "^0x[0-9a-f]{40}$",
+            "example": "0xabc0000000000000000000000000000000000001"
+          },
+          "amount": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          },
+          "leafIndex": {
+            "type": "integer",
+            "nullable": true,
+            "minimum": 0
+          },
+          "merkleRoot": {
+            "type": "string",
+            "pattern": "^0x[0-9a-fA-F]{64}$",
+            "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+          },
+          "completedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "claimed",
+              "unclaimed"
+            ],
+            "description": "Derived live at request time by diffing the address's allocations against the pos-staker-pool-claims subgraph. Never persisted (spec D10)."
+          }
+        },
+        "required": [
+          "distributionId",
+          "address",
+          "amount",
+          "leafIndex",
+          "merkleRoot",
+          "completedAt",
+          "status"
+        ]
+      },
+      "UnclaimedProofsResponse": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/UnclaimedProofBatch"
+            }
+          }
+        },
+        "required": [
+          "items"
+        ]
+      },
+      "UnclaimedProofBatch": {
+        "type": "object",
+        "properties": {
+          "distributionId": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}$",
+            "example": "2026-04"
+          },
+          "merkleRoot": {
+            "type": "string",
+            "pattern": "^0x[0-9a-fA-F]{64}$",
+            "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+          },
+          "amount": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          },
+          "leafIndex": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "proof": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{64}$",
+              "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+            }
+          }
+        },
+        "required": [
+          "distributionId",
+          "merkleRoot",
+          "amount",
+          "leafIndex",
+          "proof"
+        ]
+      },
+      "ProofResponse": {
+        "type": "object",
+        "properties": {
+          "merkleRoot": {
+            "type": "string",
+            "pattern": "^0x[0-9a-fA-F]{64}$",
+            "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "description": "Distribution merkle root — same value as `DistributionDetail.merkleRoot`."
+          },
+          "address": {
+            "type": "string",
+            "pattern": "^0x[0-9a-f]{40}$",
+            "example": "0xabc0000000000000000000000000000000000001"
+          },
+          "amount": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "example": "1234567890000000000"
+          },
+          "leafIndex": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Index of this leaf in the canonical (lowercased-address-sorted) tree."
+          },
+          "proof": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{64}$",
+              "example": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+            },
+            "description": "Sibling-hash array. Pass straight to the claimer contract."
+          }
+        },
+        "required": [
+          "merkleRoot",
+          "address",
+          "amount",
+          "leafIndex",
+          "proof"
+        ]
+      }
+    },
+    "parameters": {}
+  },
+  "paths": {
+    "/health-check": {
+      "get": {
+        "operationId": "getHealthCheck",
+        "summary": "Liveness check (K8s probe)",
+        "responses": {
+          "200": {
+            "description": "Service is alive.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OperationalStatus"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/readiness": {
+      "get": {
+        "operationId": "getReadiness",
+        "summary": "Readiness check",
+        "description": "Distinguishes \"fully ready\" from \"partially degraded but still serving\". Currently a 200 stub — the real DB + subgraph reachability probe is outstanding work.",
+        "responses": {
+          "200": {
+            "description": "Service is ready.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OperationalStatus"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/distributions": {
+      "get": {
+        "operationId": "listDistributions",
+        "summary": "List completed distributions",
+        "description": "Paginated list of completed distributions, oldest first by id (e.g. `2026-04`). Non-completed rows are not surfaced on the public API.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "name": "cursor",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 50
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Page of distribution summaries.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DistributionListResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid pagination cursor (`info.code: \"INVALID_CURSOR\"`) or request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/distributions/{distributionId}": {
+      "get": {
+        "operationId": "getDistribution",
+        "summary": "Get a single completed distribution",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}$",
+              "example": "2026-04"
+            },
+            "required": true,
+            "name": "distributionId",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Distribution detail.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DistributionDetail"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Distribution not found or not yet completed.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/distributions/{distributionId}/allocations": {
+      "get": {
+        "operationId": "listAllocations",
+        "summary": "List allocations for a completed distribution",
+        "description": "Paginated by `leafIndex` ascending.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}$",
+              "example": "2026-04"
+            },
+            "required": true,
+            "name": "distributionId",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "name": "cursor",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 50
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Page of allocation rows.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AllocationListResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid pagination cursor (`info.code: \"INVALID_CURSOR\"`) or request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Distribution not found or not yet completed.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/distributions/{distributionId}/excluded-allocations": {
+      "get": {
+        "operationId": "listExcludedAllocations",
+        "summary": "List off-chain (merkle-excluded) allocations for a distribution",
+        "description": "Recipients allocated but excluded from the merkle tree (excluded addresses) — not claimable on-chain, settled manually. Not paginated (small bounded set). `totalAmount` equals the distribution `total_allocated - claimable_total`.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}$",
+              "example": "2026-04"
+            },
+            "required": true,
+            "name": "distributionId",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The off-chain allocation set.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExcludedAllocationsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Distribution not found or not yet completed.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/distributions/{distributionId}/allocations/{address}": {
+      "get": {
+        "operationId": "getAllocation",
+        "summary": "Get a single address allocation in a distribution",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}$",
+              "example": "2026-04"
+            },
+            "required": true,
+            "name": "distributionId",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{40}$",
+              "example": "0xabc0000000000000000000000000000000000001"
+            },
+            "required": true,
+            "name": "address",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Allocation row.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AllocationRow"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Distribution or allocation not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/addresses/{address}/allocations": {
+      "get": {
+        "operationId": "getAddressAllocationHistory",
+        "summary": "Per-address cross-distribution allocation history with live claim status",
+        "description": "Returns every allocation row for the given address across all completed distributions on the network, enriched with `status: \"claimed\" | \"unclaimed\"` derived live at request time by querying the pos-staker-pool-claims subgraph (spec §3.6, D10). Empty array if the address never qualified.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{40}$",
+              "example": "0xabc0000000000000000000000000000000000001"
+            },
+            "required": true,
+            "name": "address",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "History rows ordered most-recently-completed first.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AllocationHistoryResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/addresses/{address}/unclaimed-proofs": {
+      "get": {
+        "operationId": "getUnclaimedProofs",
+        "summary": "Per-address unclaimed-proofs array — the primary claim-flow UI endpoint",
+        "description": "Returns the address's outstanding allocations with merkle proofs ready to submit to the claimer contract in one batched transaction. Proof generation is on demand from the persisted leaves (spec D9); the in-memory tree cache absorbs repeat calls for the same distribution. Empty array if every allocation has been claimed (or the address has none).",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{40}$",
+              "example": "0xabc0000000000000000000000000000000000001"
+            },
+            "required": true,
+            "name": "address",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Batch of unclaimed-proof entries ordered oldest-distribution first.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnclaimedProofsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/{network}/distributions/{distributionId}/allocations/{address}/proof": {
+      "get": {
+        "operationId": "getProof",
+        "summary": "Get the merkle proof for a single allocation",
+        "description": "Rebuilds (or cache-hits) the merkle tree from the persisted allocations table and extracts the proof for the requested address. The returned tuple `(merkleRoot, address, amount, leafIndex, proof)` can be passed straight to a Solidity verifier built around the same `[address, uint256]` leaf encoding.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "mainnet",
+                "amoy"
+              ],
+              "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+              "example": "mainnet"
+            },
+            "required": true,
+            "description": "Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.",
+            "name": "network",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}$",
+              "example": "2026-04"
+            },
+            "required": true,
+            "name": "distributionId",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{40}$",
+              "example": "0xabc0000000000000000000000000000000000001"
+            },
+            "required": true,
+            "name": "address",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Proof bundle ready to submit to the claimer contract.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProofResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request failed schema validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Distribution not found, not yet completed, address has no allocation, or the allocation is excluded from the tree (settled off-chain).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}