Token Vesting Schedule Audit API Documentation

POSThttps://www.brainiac.software/api/v1/tokenomics/token-vesting-schedule-audit$0.05 USDC

Audit token vesting schedule

Audit caller-supplied token vesting allocations against a declared supply. Checks totals, cliff and vesting dates, duplicate beneficiaries, overlapping schedules, and distribution records. audit_status is valid, warnings, invalid, or incomplete. Supported models are linear and custom. A linear schedule needs a start, cliffMode (included or before_vesting), a cliff duration or cliff date, a vesting duration, an unlock frequency, and an initial unlock percent or amount. initialUnlockPercent is a decimal string from 0 to 100 with at most 4 decimal places. Timestamps are UTC and must end in Z. No chain is queried, and wallet balances are not verified.

Body

Field	Required	Notes
`supply`	Yes	string
`evaluationDates`	No	array; Array
`allocations`	Yes	array; Array
`distributions`	No	array; Array

Request exampleJSON

{
  "supply": "1000000",
  "evaluationDates": [
    "2026-04-01T00:00:00.000Z"
  ],
  "allocations": [
    {
      "id": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "600000",
      "model": "linear",
      "start": "2026-01-01T00:00:00.000Z",
      "cliffDurationSeconds": 2592000,
      "cliffMode": "before_vesting",
      "vestingDurationSeconds": 7776000,
      "unlockFrequencySeconds": 2592000,
      "initialUnlockPercent": "0"
    },
    {
      "id": "team-bonus",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "100000",
      "model": "custom",
      "unlocks": [
        {
          "at": "2026-02-01T00:00:00.000Z",
          "amount": "50000"
        },
        {
          "at": "2026-03-01T00:00:00.000Z",
          "amount": "50000"
        }
      ]
    }
  ],
  "distributions": [
    {
      "allocationId": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "100000",
      "at": "2026-04-01T00:00:00.000Z"
    }
  ]
}

Response exampleJSON

{
  "audit_status": "warnings",
  "total_allocated": "700000",
  "unallocated_supply": "300000",
  "allocation_percentage": "70.0000",
  "unlock_schedule": [
    {
      "at": "2026-02-01T00:00:00.000Z",
      "kind": "unlock",
      "allocation_id": "team-bonus",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "50000",
      "cumulative_amount": "50000",
      "cumulative_issuance": "50000"
    },
    {
      "at": "2026-03-01T00:00:00.000Z",
      "kind": "unlock",
      "allocation_id": "team-bonus",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "50000",
      "cumulative_amount": "100000",
      "cumulative_issuance": "100000"
    },
    {
      "at": "2026-03-02T00:00:00.000Z",
      "kind": "unlock",
      "allocation_id": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "200000",
      "cumulative_amount": "200000",
      "cumulative_issuance": "300000"
    },
    {
      "at": "2026-04-01T00:00:00.000Z",
      "kind": "unlock",
      "allocation_id": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "200000",
      "cumulative_amount": "400000",
      "cumulative_issuance": "500000"
    },
    {
      "at": "2026-04-01T00:00:00.000Z",
      "kind": "evaluation",
      "amount": "500000",
      "cumulative_issuance": "500000"
    },
    {
      "at": "2026-05-01T00:00:00.000Z",
      "kind": "unlock",
      "allocation_id": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "200000",
      "cumulative_amount": "600000",
      "cumulative_issuance": "700000"
    }
  ],
  "beneficiary_findings": [
    {
      "allocation_id": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "code": "duplicate_beneficiary",
      "severity": "medium",
      "detail": "Beneficiary 0x1111111111111111111111111111111111111111 has allocations team, team-bonus."
    },
    {
      "allocation_id": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "code": "overlapping_schedule",
      "severity": "medium",
      "detail": "Allocations team and team-bonus cover overlapping times."
    }
  ],
  "distribution_mismatches": [
    {
      "allocation_id": "team",
      "at": "2026-04-01T00:00:00.000Z",
      "expected_amount": "400000",
      "distributed_amount": "100000",
      "code": "distributed_below_unlocked",
      "detail": "Allocation team had 100000 distributed and 400000 unlocked at 2026-04-01T00:00:00.000Z."
    }
  ],
  "warnings": [
    {
      "code": "duplicate_beneficiary",
      "detail": "Beneficiary 0x1111111111111111111111111111111111111111 has allocations team, team-bonus."
    },
    {
      "code": "overlapping_schedule",
      "detail": "Allocations team and team-bonus cover overlapping times."
    }
  ],
  "limitations": [
    "Only the supply, allocations, and distribution records in this request were audited. No wallet balance or token transfer was read.",
    "Timestamps are UTC instants and must end in Z. No timezone is applied.",
    "Amounts are integers in the caller's smallest unit. An initial unlock percent uses integer division, and any remainder stays in the vesting amount.",
    "allocation_percentage is truncated to 4 decimal places.",
    "A linear schedule releases the initial unlock at the start. cliffMode before_vesting places later unlocks one frequency apart after the cliff. cliffMode included starts the clock at the start and withholds vesting unlocks that fall before the cliff until the cliff.",
    "When the vesting duration is not a multiple of the unlock frequency, the last unlock is at the vesting end and receives the remaining tokens. Earlier unlocks are equal integer shares.",
    "The last unlock includes any remainder from integer division, so a complete schedule adds up to the allocation amount.",
    "A custom allocation uses only its unlock list. Linear fields on a custom allocation are not used, and a custom unlock list on a linear allocation is not used.",
    "A distribution is compared only when its allocationId matches an allocation in this request.",
    "Allocations with missing parameters are counted in the supply totals and omitted from the unlock schedule."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/tokenomics/token-vesting-schedule-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "supply": "1000000",
  "evaluationDates": [
    "2026-04-01T00:00:00.000Z"
  ],
  "allocations": [
    {
      "id": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "600000",
      "model": "linear",
      "start": "2026-01-01T00:00:00.000Z",
      "cliffDurationSeconds": 2592000,
      "cliffMode": "before_vesting",
      "vestingDurationSeconds": 7776000,
      "unlockFrequencySeconds": 2592000,
      "initialUnlockPercent": "0"
    },
    {
      "id": "team-bonus",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "100000",
      "model": "custom",
      "unlocks": [
        {
          "at": "2026-02-01T00:00:00.000Z",
          "amount": "50000"
        },
        {
          "at": "2026-03-01T00:00:00.000Z",
          "amount": "50000"
        }
      ]
    }
  ],
  "distributions": [
    {
      "allocationId": "team",
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "amount": "100000",
      "at": "2026-04-01T00:00:00.000Z"
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/tokenomics/vesting-dilution$0.04 USDC

Score vesting dilution

Project a caller-supplied circulating supply and price across vesting cliffs. Each schedule unlocks one period at its cliff month, then monthly until it is fully unlocked. The FDV curve holds the price constant. The dilution score mixes the locked share with the largest single-month unlock. No price feed is queried.

Body

Field	Required	Notes
`circulating`	Yes	integer
`price`	Yes	number
`months`	Yes	integer
`schedules`	Yes	array; Array

Request exampleJSON

{
  "circulating": 400000,
  "price": 2,
  "months": 6,
  "schedules": [
    {
      "name": "investors",
      "amount": 300000,
      "cliff_months": 3,
      "vesting_months": 3
    },
    {
      "name": "team",
      "amount": 300000,
      "cliff_months": 6,
      "vesting_months": 18
    }
  ]
}

Response exampleJSON

{
  "dilution_risk_score": 45,
  "cliff_impact_percentage": 10,
  "projected_fdv_curve": [
    {
      "month": 0,
      "fdv": 800000
    },
    {
      "month": 1,
      "fdv": 800000
    },
    {
      "month": 2,
      "fdv": 800000
    },
    {
      "month": 3,
      "fdv": 1000000
    },
    {
      "month": 4,
      "fdv": 1200000
    },
    {
      "month": 5,
      "fdv": 1400000
    },
    {
      "month": 6,
      "fdv": 1433332
    }
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/tokenomics/vesting-dilution" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "circulating": 400000,
  "price": 2,
  "months": 6,
  "schedules": [
    {
      "name": "investors",
      "amount": 300000,
      "cliff_months": 3,
      "vesting_months": 3
    },
    {
      "name": "team",
      "amount": 300000,
      "cliff_months": 6,
      "vesting_months": 18
    }
  ]
}
JSON