Skip to main content

Vesting Schedules

Deploy VestingWallet contracts to lock tokens with a cliff period and linear release schedule.

When to Use​

  • Team token allocation — lock founder/employee tokens with a cliff
  • Investor vesting — gradual token release over time
  • Community grants — time-locked distributions to contributors
  • Token launch — prevent early dumping with vesting periods
How It Works
  1. Cliff period — no tokens vest during the cliff (e.g., 3 months)
  2. Linear release — after the cliff, tokens vest linearly over the remaining duration
  3. Release — the beneficiary (or anyone) can call release() to send vested tokens to the beneficiary

Deploy a Vesting Schedule​

const vesting = await urblock.vesting.create({
  token_id: "tok_abc123",
  beneficiary: "0xBeneficiary...",
  total_amount: "1000000000000000000000",
  start_timestamp: Math.floor(Date.now() / 1000),
  duration_seconds: 31536000,  // 1 year
  cliff_seconds: 7776000,     // 3 months cliff
  network: "polygon_amoy",
  idempotency_key: "vesting-001",
});

List Vesting Schedules​

const schedules = await urblock.vesting.list({ limit: 10 });

Check Vested Amount​

const vested = await urblock.vesting.getVestedAmount("vst_abc123", {
  timestamp: Math.floor(Date.now() / 1000),
});
console.log(vested.vested);
console.log(vested.releasable);

Release Tokens​

Release all currently vested tokens to the beneficiary:

const tx = await urblock.vesting.release("vst_abc123", {
  idempotency_key: "release-001",
});

Example Timeline​

1-Year Vesting with 3-Month Cliff​

TimeVested
Month 0-3 (cliff)0%
Month 325%
Month 650%
Month 975%
Month 12100%

curl Example​

# Create a vesting schedule
curl -X POST https://api.urblock.io/v1/vesting \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "tok_abc123",
    "beneficiary": "0xBeneficiary...",
    "total_amount": "1000000000000000000000",
    "start_timestamp": 1718234567,
    "duration_seconds": 31536000,
    "cliff_seconds": 7776000,
    "network": "polygon_amoy",
    "idempotency_key": "vesting-001"
  }'

# Check vested amount
curl "https://api.urblock.io/v1/vesting/vst_abc123/vested?timestamp=$(date +%s)" \
  -H "Authorization: Bearer sk_test_..."

Next Steps​