> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shakesco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Vesting Grant

> Set up a vesting schedule that releases tokens to a customer over time

<span style={{display:"none"}}>For the complete documentation index, see [llms.txt](/llms.txt).</span>

Creates a vesting grant for a customer. Tokens are released gradually: a percentage unlocks at the cliff, and the rest unlocks linearly over the remaining vesting period. Each customer can have at most one active grant at a time.

<Info>
  Treat this as a transaction. If you don't get a `200 OK`, check [`/vesting-info`](/api-reference/tokens/vesting/vesting-info) before retrying. A successful retry over an existing grant returns `409`.
</Info>

### Request Body

<ParamField body="customer_ref" type="string" required>
  Your unique identifier for this customer
</ParamField>

<ParamField body="total_amount" type="number" required>
  Total tokens to vest. Decimals allowed.
</ParamField>

<ParamField body="vesting_duration" type="string" required>
  Total vesting period in seconds
</ParamField>

<ParamField body="cliff_duration" type="string" required>
  Cliff period in seconds. No tokens vest before this point.
</ParamField>

<ParamField body="cliff_percent" type="number" required>
  Percent of total released at the cliff (`25` = 25%). Decimals allowed.
</ParamField>

### Response

<ResponseField name="tx_hash" type="string">
  Reference identifier for the grant
</ResponseField>

```javascript theme={null}
await fetch("https://tokens.shakesco.com/create-vesting-grant", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    customer_ref: "customer-123",
    total_amount: 1000,
    vesting_duration: "31536000",
    cliff_duration: "7776000",
    cliff_percent: 25,
  }),
});
```

<ResponseExample>
  ```json 200 OK theme={null}
  { "tx_hash": "0xabc..." }
  ```

  ```json 409 Grant Exists theme={null}
  { "error": "An active vesting grant already exists" }
  ```
</ResponseExample>