Skip to main content

Getting Started

Receive transfer events for EVM Security Token.

The Token Movement API is accessible through Upside Token Management Platform.

Feature Overview​

Historical View​

The API provides a historical view of all transfer events for a token, with an option to filter by transaction hash and recipient address.

Callbacks​

The transfer events can de delivered to a callback URL, allowing for real-time updates on token movements.

Vestings and Restrictions Data Included​

The transfer events provide additional on-chain data including vesting details and reg groups of sender and recipient.

Architecture Overview​

Sequence Diagrams​

Historical View​

Callbacks​

Usage​

Historical View​

Authentication​

Each API request must include a X-Project-Api-Key header.

The key is available in API Keys page of a project dashboard in the Upside Token Management Platform.

Example Request​

$ curl -X 'GET' \
  'https://app.upside.gg/r/api/v2/transfer_events' \
  -H 'accept: */*' \
  -H 'X-Project-Api-Key: API_KEY'

[
  {
    "id": 457,
    "block": 38612041,
    "tx_hash": "0x84576d297951f3adf3f76d86adb5d9b7501b3cf8b091e1a9142840b0587b5c1c",
    "method_name": "batchFundReleaseSchedule",
    "amount": 3750000000000,
    "approved_on_chain_at": "2023-12-04T15:36:22.000Z",
    "commencement_timestamp": 1701820800,
    "schedule_id": 0,
    "created_at": "2024-11-15T18:24:00.636Z",
    "updated_at": "2024-11-15T18:24:00.636Z",
    "vesting_schedule": {
      "name": "Gradual Release",
      "release_count": 12,
      "delay_until_first_release_in_seconds": 0,
      "initial_release_portion_in_bips": 1500,
      "period_between_releases_in_seconds": 2678400
    },
    "recipient_wallet": {
      "address": "0x0f74241175da97F296A07a66B4E64b2320535CC2"
    },
    "sender_wallet": {
      "address": "0xe41875CA782f98923D4B9db6df9D057cb8663692"
    },
    "recipient_reg_group": {
      "name": "Reg A",
      "blockchain_id": 1
    },
    "sender_reg_group": {
      "name": "Reg D",
      "blockchain_id": 2
    },
    "token": {
      "_blockchain": "avalanche_fuji",
      "_token_type": "comakery_security_token_v4",
      "id": 32,
      "contract_address": "0xC585511BaA9C7B8e3ee1bE05414e11f093f6d405",
      "decimal_places": 8,
      "name": "Security Token 2c533a82",
      "symbol": "CMK",
      "created_at": "2024-11-13T20:22:25.736Z",
      "updated_at": "2024-11-15T18:22:52.913Z"
    }
  }
]

Callbacks​

Set Up​

The callback URL can be set up in the project settings in the Upside Token Management Platform.

Example Callback​

{
  "id": 457,
  "block": 38612041,
  "tx_hash": "0x84576d297951f3adf3f76d86adb5d9b7501b3cf8b091e1a9142840b0587b5c1c",
  "method_name": "batchFundReleaseSchedule",
  "amount": 3750000000000,
  "approved_on_chain_at": "2023-12-04T15:36:22.000Z",
  "commencement_timestamp": 1701820800,
  "schedule_id": 0,
  "created_at": "2024-11-15T18:24:00.636Z",
  "updated_at": "2024-11-15T18:24:00.636Z",
  "vesting_schedule": {
    "name": "Gradual Release",
    "release_count": 12,
    "delay_until_first_release_in_seconds": 0,
    "initial_release_portion_in_bips": 1500,
    "period_between_releases_in_seconds": 2678400
  },
  "recipient_wallet": {
    "address": "0x0f74241175da97F296A07a66B4E64b2320535CC2"
  },
  "sender_wallet": {
    "address": "0xe41875CA782f98923D4B9db6df9D057cb8663692"
  },
  "recipient_reg_group": {
    "name": "Reg A",
    "blockchain_id": 1
  },
  "sender_reg_group": {
    "name": "Reg D",
    "blockchain_id": 2
  },
  "token": {
    "_blockchain": "avalanche_fuji",
    "_token_type": "comakery_security_token_v4",
    "id": 32,
    "contract_address": "0xC585511BaA9C7B8e3ee1bE05414e11f093f6d405",
    "decimal_places": 8,
    "name": "Security Token 2c533a82",
    "symbol": "CMK",
    "created_at": "2024-11-13T20:22:25.736Z",
    "updated_at": "2024-11-15T18:22:52.913Z"
  }
}

Notes​

EVM Security Token v3 (and lower)​

The API was designed for EVM Security Token v4 and higher, but can also be used with lower versions.

Due the specifics of the contract implementaion for EVM Security Token v3 and lower, each token movement produces two transfer events:

  1. Tokens are transferred from the sender to the RestrictedLockupToken contract.
  2. Tokens are transferred from the RestrictedLockupToken contract to the recipient.

This reflects the actual token movement within the contract, but it's recommended to merge or associate these two events when displaying the data.

Please also consider the following implications:

  1. The recipient data (including reg group) in the first transfer event belongs to RestrictedLockupToken contract.
  2. The sender data (including reg group) in the second transfer event belongs to RestrictedLockupToken contract.
  3. The vesting details are only available in the second transfer event.