{ "openapi": "3.1.1", "info": { "title": "Token Unlock Explorer API", "version": "1.0.0", "summary": "Model token vesting (cliff, linear, monthly, tranches, TGE) or audit a VestingWallet.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://tokenunlockexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Model token vesting (cliff, linear, monthly, tranches, TGE) or audit a VestingWallet.", "description": "Builds a token unlock schedule from its parameters — total, start, cliff, duration, linear / monthly / custom tranches and TGE percentage — and shows unlocked vs. locked amounts on any date and the next unlock. On-chain mode reads an OpenZeppelin VestingWallet (start, duration, released, releasable) and compares the schedule with what was actually released.\n\nMethodology:\n- Unlocked(t) = TGE % of total at the start date, plus the remaining amount vesting from the start date to start + duration. Before the cliff only the TGE amount is unlocked; at the cliff everything accrued since the start unlocks at once (OpenZeppelin VestingWalletCliff semantics).\n- Linear: continuous pro-rata by time. Monthly: equal steps on each monthly anniversary of the start date (day clamped to month end). Tranches: the listed percentages of the total on the listed dates (plus TGE).\n- All dates are UTC. Amounts are computed per date; the sample table shows month-end points.\n- On-chain mode reads an OpenZeppelin VestingWallet with eth_call: start(), duration(), cliff() (if present), released() / released(token), releasable() / releasable(token), owner() as beneficiary, plus the wallet's balance. Allocation = balance + released; scheduled vested = allocation × (now − start) / duration (0 before the cliff, full after the end), which equals released + releasable for an unmodified wallet.", "tags": [ "web3" ], "x-mcp-tool": "token_unlock_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenUnlockExplorerInput" }, "examples": { "example1": { "summary": "10 % TGE, 12-month cliff, monthly over 36 months", "value": { "mode": "schedule", "totalTokens": 1000000, "symbol": "ABC", "startDate": "2026-01-01", "cliffMonths": 12, "durationMonths": 36, "schedule": "monthly", "tgePercent": 10, "asOf": "2027-03-15" } }, "example2": { "summary": "Custom tranches", "value": { "mode": "schedule", "totalTokens": 500000, "symbol": "XYZ", "startDate": "2026-06-01", "schedule": "tranches", "tgePercent": 0, "tranches": "2026-12-01, 25\n2027-06-01, 25\n2027-12-01, 50", "asOf": "2027-01-10" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenUnlockExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "TokenUnlockExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "Mode", "type": "string", "enum": [ "schedule", "vesting-wallet" ], "default": "schedule" }, "totalTokens": { "title": "Total tokens", "type": "number", "minimum": 0, "default": 1000000 }, "symbol": { "title": "Token symbol", "type": "string", "maxLength": 20, "default": "TOKEN" }, "startDate": { "title": "Start / TGE date", "type": "string", "format": "date", "default": "2026-01-01" }, "cliffMonths": { "title": "Cliff", "type": "integer", "minimum": 0, "maximum": 120, "default": 12, "x-unit": "months" }, "durationMonths": { "title": "Total vesting duration (from start, incl. cliff)", "type": "integer", "minimum": 1, "maximum": 240, "default": 36, "x-unit": "months" }, "schedule": { "title": "Release type", "type": "string", "enum": [ "linear", "monthly", "tranches" ], "default": "monthly" }, "tgePercent": { "title": "Unlocked at TGE", "type": "number", "minimum": 0, "maximum": 100, "default": 10, "x-unit": "%" }, "tranches": { "title": "Tranches (custom)", "description": "One \"date, percent of total\" per line.", "type": "string", "maxLength": 20000 }, "asOf": { "title": "As of date", "description": "Defaults to today.", "type": "string", "format": "date" }, "chain": { "title": "Chain (on-chain mode)", "type": "string", "enum": [ "ethereum", "base", "arbitrum", "optimism", "polygon", "avalanche", "bsc" ], "default": "ethereum" }, "vestingWallet": { "title": "VestingWallet address", "type": "string", "maxLength": 42 }, "token": { "title": "Token address (blank = native coin)", "type": "string", "maxLength": 42 } }, "required": [] }, "TokenUnlockExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "mode", "symbol", "total", "asOf", "schedule", "unlocked", "locked", "unlockedPercent", "next", "events", "samples", "onchain" ], "properties": { "mode": { "type": "string" }, "symbol": { "type": "string" }, "total": { "type": "number" }, "asOf": { "type": "string" }, "schedule": { "type": "object", "additionalProperties": false, "required": [ "kind", "start", "cliffEnd", "end", "tgePercent" ], "properties": { "kind": { "type": "string" }, "start": { "type": "string" }, "cliffEnd": { "type": "string" }, "end": { "type": "string" }, "tgePercent": { "type": "number" } } }, "unlocked": { "type": "number" }, "locked": { "type": "number" }, "unlockedPercent": { "type": "number" }, "next": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "date", "amount", "label", "daysAway" ], "properties": { "date": { "type": "string" }, "amount": { "type": "number" }, "label": { "type": "string" }, "daysAway": { "type": "integer" } } }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "label", "amount", "cumulative" ], "properties": { "date": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "cumulative": { "type": "number" } } } }, "samples": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "unlocked", "unlockedPercent" ], "properties": { "date": { "type": "string" }, "unlocked": { "type": "number" }, "unlockedPercent": { "type": "number" } } } }, "onchain": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "wallet", "chain", "token", "beneficiary", "startUnix", "durationSeconds", "cliffUnix", "balance", "released", "releasable", "totalAllocation", "scheduledVested", "consistent", "unclaimed" ], "properties": { "wallet": { "type": "string" }, "chain": { "type": "string" }, "token": { "type": [ "string", "null" ] }, "beneficiary": { "type": [ "string", "null" ] }, "startUnix": { "type": "integer" }, "durationSeconds": { "type": "integer" }, "cliffUnix": { "type": [ "integer", "null" ] }, "balance": { "type": "string" }, "released": { "type": "string" }, "releasable": { "type": [ "string", "null" ] }, "totalAllocation": { "type": "string" }, "scheduledVested": { "type": "string" }, "consistent": { "type": [ "boolean", "null" ] }, "unclaimed": { "type": "string" } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }