Token Locks

Understanding how token locks work in the Metal ecosystem, including presale locks and lock restrictions.

Overview

Token locks are a security mechanism that prevents tokens from being transferred or sold for a specified period. This feature is primarily used for presale tokens to ensure stability and prevent immediate dumping after token distribution.

How Token Locks Work

Lock Creation

Token locks are automatically created when:

  • Presale tokens are distributed to participants
  • The lock duration is determined by the presale's lockDuration parameter (default: 7 days)
  • Each participant receives their tokens in a locked state

Lock Properties

  • Name
    tokenAddress
    Type
    string
    Description

    The address of the locked token

  • Name
    lockedAmount
    Type
    number
    Description

    The amount of tokens that are locked

  • Name
    unlockDate
    Type
    Date
    Description

    The date when tokens will automatically unlock

  • Name
    userId
    Type
    string
    Description

    The holder's unique identifier

Lock Restrictions

While tokens are locked:

  • Cannot be transferred to other addresses
  • Cannot be sold through the sell endpoint
  • Cannot be used for any transactions
  • Will appear in the holder's locks array
  • Excluded from the available balance

Example Lock Object

{
  "id": "0x1234567890abcdef1234567890abcdef12345678-locked",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "name": "Presale Token",
  "symbol": "PST",
  "balance": 1000,
  "value": 100.25,
  "status": "locked",
  "type": "lock",
  "unlockDate": "2024-04-01T00:00:00.000Z"
}

Lock Behavior in API Responses

In Holder Response

When you retrieve holder information, locked tokens appear in three ways:

  1. In the locks array: Shows all currently locked tokens with unlock dates
  2. Excluded from tokens array: Only unlocked, available tokens appear here
  3. Included in totalValue: The USD value of locked tokens contributes to the total portfolio value

Holder Response Example

{
  "id": "holder_123",
  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
  "totalValue": 500.00,
  "tokens": [
    {
      "id": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "name": "USDC",
      "balance": 100,
      "value": 100,
      "status": "active",
      "type": "token"
    }
  ],
  "locks": [
    {
      "id": "0x1234567890abcdef1234567890abcdef12345678-locked",
      "name": "Presale Token",
      "balance": 2000,
      "value": 400,
      "status": "locked",
      "type": "lock",
      "unlockDate": "2024-04-01T00:00:00.000Z"
    }
  ],
  "presales": []
}

Attempting to Sell Locked Tokens

If a user attempts to sell more tokens than their available (unlocked) balance, the API will return an error:

Sell Error Response

{
  "error": "Insufficient available balance. You have 2000 tokens locked until 04/01/2024. Available balance: 500"
}

Lock Lifecycle

    Presale Participation

    User participates in a presale by contributing USDC

    Presale Completion

    When the presale reaches its target or end date, it enters completion

    Token Distribution

    Tokens are created and distributed to participants in a locked state

    Lock Period

    Tokens remain locked for the duration specified in the presale (default: 7 days)

    Automatic Unlock

    After the unlock date passes, tokens automatically become available for trading

Best Practices

For API Integration

  1. Always check the locks array when displaying user balances
  2. Show unlock dates to users so they know when tokens become available
  3. Calculate available balance by excluding locked amounts
  4. Handle sell errors gracefully when users attempt to sell locked tokens

For Users

  1. Understand lock periods before participating in presales
  2. Plan accordingly as locked tokens cannot be accessed until the unlock date
  3. Monitor unlock dates to know when tokens become tradeable

Was this page helpful?