Vesting API

Manage token vesting contracts.

Get Vesting Status

GET /vesting/:contractId

Retrieve detailed vesting contract information.

Response


{
  "contractId": "VEST123...",
  "launchId": "launch_abc123",
  "beneficiary": "8vP2...",
  "mint": "ABC123...",
  "total": 1000000000,
  "claimed": 250000000,
  "unlocked": 500000000,
  "claimable": 250000000,
  "locked": 500000000,
  "schedule": {
    "start": 1700000000,
    "cliff": 1710000000,
    "end": 1735000000,
    "cliffMonths": 6,
    "durationMonths": 24
  },
  "status": "active",
  "createdAt": "2026-02-15T12:00:00Z"
}

Status Values

Status	Description
`active`	Vesting in progress
`cliff`	In cliff period
`completed`	All tokens vested
`cancelled`	Contract cancelled

Claim Tokens

POST /vesting/:contractId/claim

Claim unlocked but unclaimed tokens.

Request Body


{
  "amount": "all"  // Or specific amount in base units
}

Response


{
  "signature": "5abc...",
  "claimed": 250000000,
  "newClaimable": 0,
  "newTotalClaimed": 500000000
}

List Vesting Contracts

GET /launches/:launchId/vesting

Get all vesting contracts for a launch.

Response


{
  "contracts": [
    {
      "contractId": "VEST123...",
      "beneficiary": "8vP2...",
      "total": 1000000000,
      "status": "active"
    }
  ]
}

Create Manual Vesting (Admin)

POST /admin/vesting

Create a vesting contract manually (requires admin auth).

Request Body


{
  "mint": "ABC123...",
  "beneficiary": "8vP2...",
  "amount": 1000000000,
  "cliffMonths": 6,
  "durationMonths": 24
}

Response


{
  "contractId": "VEST456...",
  "transaction": "5def...",
  "status": "created"
}

Cancel Vesting (Admin)

POST /vesting/:contractId/cancel

Cancel a vesting contract and return remaining tokens (requires admin auth).

Response


{
  "signature": "5ghi...",
  "returned": 500000000,
  "status": "cancelled"
}

Webhook Events

Vesting emits these webhook events:

Event	Description
`vesting.created`	Contract created
`vesting.cliff_reached`	Cliff period ended
`vesting.claimed`	Tokens claimed
`vesting.completed`	All tokens vested
`vesting.cancelled`	Contract cancelled

Examples

Check and Claim


async function checkAndClaim(authToken: string, contractId: string) {
  // Check status
  const status = await fetch(
    `https://etch.film.fun/api/vesting/${contractId}`,
    { headers: { Authorization: `Bearer ${authToken}` } }
  ).then(r => r.json());
  
  console.log(`Claimable: ${status.claimable}`);
  
  if (status.claimable > 0) {
    // Claim tokens
    const claim = await fetch(
      `https://etch.film.fun/api/vesting/${contractId}/claim`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${authToken}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ amount: "all" })
      }
    ).then(r => r.json());
    
    console.log(`Claimed! Tx: ${claim.signature}`);
    return claim;
  }
  
  return null;
}

Error Codes

Code	Description
`vesting_not_found`	Contract doesn’t exist
`nothing_to_claim`	No tokens available
`vesting_complete`	Already fully claimed
`unauthorized_claim`	Wrong beneficiary
`contract_cancelled`	Contract was cancelled