Resources
Docs Version Switcher
Search

# ViteX Gateway Protocol

Introduction

This specification describes the API that a third-party ViteX Gateway need in order to implement integration into ViteX. It is fully supported by Vite Web Wallet (opens new window) and Vite Mobile App.

For how to integrate the Gateway in the wallet, please see Gateway Integration Guide

Attention

  • HTTPS is required
  • CORS (Cross-Origin Resource Sharing) must be supported
  • Transfer amount should be expressed in minimum precision

# Request

The following parameters are appended in request header from Vite web wallet

Name Description
lang The wallet will pass the current locale, and the gateway should handle it to provide i18n support.
zh-cn(Chinese simplified), en(English) and 5 other languages are currently supported in the wallet.
version The spec version number(s) currently supported by the web wallet, split by ,

# Response

# header

The following parameter should be appended in response header from Gateway

Name Description
version The spec version number(s) currently supported by the Gateway, split by ,

# body

Copy { "code": 0,//response code "subCode": 0,//sub code filled in by Gateway for debugging "msg": null,//additional message filled in by gateway for debugging "data":""//response data }

# Metadata API

# /meta-info

Get Gateway information by token id

  • Method: GET

  • Request: query string

    Name Description Data Type Required
    tokenId Token id string yes

  • Response

    Name Description Data Type Required
    type Binding type. Allowed value:
    0Independent address mode
    1Bind-by-comment mode    		 int yes
    depositState Deposit channel state. Allowed value: OPEN, MAINTAIN, CLOSED string yes
    withdrawState Withdrawal channel state. Allowed value: OPEN, MAINTAIN, CLOSED string yes

Binding Types

The web wallet needs to use binding types to render different deposit/withdrawal UI(s) and build different requests, while the gateway needs to use it to return different responses. Currently, the following two types have been defined:

  • 0 Independent address mode: In this mode, the Gateway will bind a separate inbound address to each user's Vite address. Examples of this type are BTC and ETH
  • 1 Bind-by-comment mode: In this mode, the Gateway cannot bind separate inbound address to each user's Vite address, so that it is necessary to identify the user's VITE address with additional comment. Examples of this type are EOS and XMR

  • Example

    Request

    Copy /meta-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7

    Response

    Copy { "code": 0, "subCode": 0, "msg": null, "data": { "type": 0, "depositState": "OPEN", "withdrawState": "OPEN" } }

# Deposit/Withdrawal API

# /deposit-info

Get deposit information by token id and user's Vite address. The Gateway should bind user's Vite address to a source chain address, and the web wallet will display a deposit page based on the API response.

  • Method: GET

  • Request: query string

    Name Description Data Type Required
    tokenId Gateway token id string yes
    walletAddress User's Vite address string yes

  • Response

    Name Description Data Type Required
    depositAddress Deposit address string yes
    labelName Label name, required if type=1 string no
    label Label value, required if type=1 string no
    minimumDepositAmount Minimum deposit amount string yes
    confirmationCount Confirmations on source chain int yes
    noticeMsg Extra message filled in by gateway string no

  • Example

    Request

    Copy /deposit-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9

    Response

    According to binding type:

Deposit Process

  1. The Gateway establishes the binding relationship between the user's VITE address and the source chain deposit address.
  2. The Gateway listens to the source chain transactions on the deposit address and waits for necessary confirmations.
  3. After the Gateway confirms the deposit transaction on the source chain, it initiates a transfer transaction to send the same amount of Gateway Tokens to user's Vite address on Vite chain.
  4. The Gateway listens to the transfer transaction on Vite, and must resend the transaction in case it doesn't get confirmed.

# /withdraw-info

Get withdrawal information by token id and user's Vite address. The web wallet will display a withdrawal page based on the API response.

  • Method: GET

  • Request: query string

    Name Description Data Type Required
    tokenId Gateway token id string yes
    walletAddress User's Vite address string yes

  • Response

    Name Description Data Type Required
    minimumWithdrawAmount Minimum withdrawal amount string yes
    maximumWithdrawAmount Maximum withdrawal amount string yes
    gatewayAddress Gateway address on Vite chain. The web wallet will send an amount of Gateway Tokens to the address for withdrawal string yes
    labelName Label name, required if type=1 string no
    noticeMsg Extra message filled in by Gateway string no

  • Example

    Request

    Copy /withdraw-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9

    Response

    Copy { "code": 0, "subCode": 0, "msg": null, "data": { "minimumWithdrawAmount": "1000000", "maximumWithdrawAmount": "10000000000", "gatewayAddress": "vite_42f9a5d93e1e392624b97dfa3d7cab057b79c2489d6bc13682", "noticeMsg": "" } }

# /withdraw-address/verification

Verify withdrawal address. The web wallet will use this API to verify the source chain withdrawal address.

  • Method: GET

  • Request: query string

    Name Description Data Type Required
    tokenId Gateway token id string yes
    withdrawAddress User's withdrawal address on the source chain string yes
    labelName Label name, required if type=1 string no

  • Response

    Name Description Data Type Required
    isValidAddress Is the user's withdrawal address valid? bool yes
    message Error message string no

  • Example

    Request

    Copy /withdraw-address/verification?tokenId=tti_82b16ac306f0d98bf9ccf7e7&withdrawAddress=moEGgYAg8KT9tydfNDofbukiUNjWTXaZTm

    Response

    Copy { "code": 0, "subCode": 0, "msg": null, "data": { "isValidAddress": true } }

# /withdraw-fee

Get Gateway withdrawal fee.

  • Method: GET

  • Request: query string

    Name Description Data Type Required
    tokenId Gateway token id string yes
    walletAddress User's Vite address string yes
    amount Withdrawal amount string yes
    containsFee Is the fee included in the original withdrawal amount?
    If this is no, then amount refers to actual amount transferred. The Gateway will calculate the transaction fee based on this amount.
    If this is yes, then amount refers to the sum of actual amount transferred and the transaction fee. The Gateway will subsequently derive the actual amount transferred and the transaction fee. Usually this is used in a full withdrawal.    		 bool yes

  • Response

    Name Description Data Type Required
    fee Withdrawal fee string yes

  • Example

    Request

    Copy /withdraw-fee?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9&amount=100000000000000&containsFee=true

    Response

    Copy { "code": 0, "subCode": 0, "msg": null, "data": { "fee": "1000000" } }

Withdrawal Process

  1. The user fills in a valid withdrawal amount and source chain withdrawal address, then hits the transfer button. At this time, the web wallet will send a corresponding amount of Gateway tokens to the Gateway address on Vite chain. The source chain withdrawal address is stored in the comment of the transaction.
  2. The Gateway listens for the transactions on the withdrawal address and waits for necessary confirmations.
  3. After the Gateway confirms the withdrawal transaction on Vite chain, it initiates a transaction to send the same amount of the source chain tokens to user's withdrawal address on the source chain.
  4. The Gateway listens for the transaction on the source chain, and must resend the transaction in case it doesn't get confirmed.

# Gateway Transaction Comment

According to VEP 8: AccountBlock Data Content Type Definition, a transaction comment is a concatenation of fixed and variable strings.

  • Fixed part:
VEP-8 Type Type
2 Byte,uint16 1 Byte,uint8

For Gateway transactions, VEP-8 Type is fixed at 3011, or 0x0bc3 in hexadecimal format

Type is the type parameter returned by /meta-info API

  • Variable part:

# Deposit/withdrawal Records Query API

# /deposit-records

Get historical deposit records.

  • Method: GET

  • Request: query string

    Name Description Data Type Required
    tokenId Gateway token id string yes
    walletAddress User's Vite address string yes
    pageNum Page index, starting from 1 int yes
    pageSize Page size int yes

  • Response

    Name Description Data Type Required
    totalCount Total deposit records int yes
    depositRecords List of deposit records list no
    inTxExplorerFormat The transaction url on the source chain explorer. Replace {$tx} with the specific inTxHash string yes
    outTxExplorerFormat The transaction url on Vite explorer. Replace {$tx} with the specific outTxHash string yes

  • Definition of depositRecords

    Name Description Data Type Required
    inTxHash The deposit transaction hash on the source chain string yes
    inTxConfirmedCount Confirmations conducted on source chain int no
    inTxConfirmationCount Confirmations required on source chain int no
    outTxHash The deposit transaction hash on Vite chain string no
    amount Deposit amount string yes
    fee Gateway fee string yes
    state Transaction state. Allowed value:
    OPPOSITE_PROCESSING Awaiting confirmation on the source chain
    OPPOSITE_CONFIRMED Confirmed on the source chain
    OPPOSITE_CONFIRMED_FAIL Transaction failed on the source chain
    BELOW_MINIMUM Transaction aborted due to insufficient deposit amount
    TOT_PROCESSING Gateway tokens sent out on Vite chain
    TOT_CONFIRMED Deposit successful
    FAILED Deposit failed    		 string yes
    dateTime Deposit time in millisecond string yes

  • Example

    Request

    Copy /deposit-records?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9&pageNum=1&pageSize=10

    Response

    Copy { "code": 0, "subCode": 0, "msg": null, "data": { "totalCount": 1, "depositRecords": [{ "inTxHash": "0x8e791fc2430761ce82f432c6ad1614fa1ebc57b1e1e0925bd9302a9edf8fd235", "inTxConfirmedCount": 2, "inTxConfirmationCount": 12, "outTxHash": "9fb415eb6f30b27498a174bd868c29c9d30b9fa5bfb050d19156523ac540744b", "amount": "300000000000000000", "fee": "0", "state": "TOT_CONFIRMED", "dateTime": "1556129201000" }], "inTxExplorerFormat": "https://ropsten.etherscan.io/tx/{$tx}", "outTxExplorerFormat": "https://explorer.vite.org/transaction/{$tx}" } }

# /withdraw-records

Get historical withdrawal records

  • Method: GET

  • Request: query string

    Name Description Data Type Required
    tokenId Gateway token id string yes
    walletAddress User's Vite address string yes
    pageNum Page index, starting from 1 int yes
    pageSize Page size int yes

  • Response

    Name Description Data Type Required
    totalCount Total withdrawal records int yes
    withdrawRecords List of withdrawal records list no
    inTxExplorerFormat The transaction url on Vite explorer. Replace {$tx} with the specific inTxHash string yes
    outTxExplorerFormat The transaction url on the source chain explorer. Replace {$tx} with the specific outTxHash string yes

  • Definition of withdrawRecords

    Name Description Data Type Required
    inTxHash The withdrawal transaction hash on Vite chain string yes
    inTxConfirmedCount Confirmations conducted on Vite chain int no
    inTxConfirmationCount Confirmations required on Vite chain int no
    outTxHash The withdrawal transaction hash on the source chain string no
    amount Actual amount transferred string yes
    fee Gateway fee string yes
    state Transaction state. Allowed value:
    TOT_PROCESSING Awaiting confirmation on Vite chain
    TOT_CONFIRMED Confirmed on Vite chain
    TOT_EXCEED_THE_LIMIT Transaction failed due to exceeding the maximum limit
    WRONG_WITHDRAW_ADDRESS Transaction failed due to invalid withdrawal address
    OPPOSITE_PROCESSING Source chain tokens sent out
    OPPOSITE_CONFIRMED Withdrawal successful
    FAILED Withdraw failed    		 string yes
    dateTime Withdrawal time in millisecond string yes

  • Example

    Request

    Copy /withdraw-records?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9&pageNum=1&pageSize=10

    Response

    Copy { "code": 0, "subCode": 0, "msg": null, "data": { "totalCount": 2, "withdrawRecords": [{ "inTxHash": "b95c11ac34d4136f3be1daa3a9fab047e11ee9c87acef63ca21ba2cee388a80f", "inTxConfirmedCount": 2, "inTxConfirmationCount": 300, "outTxHash": "0x8096542d958a3ac4f247eba3551cea4aa09e1cdad5d7de79db4b55f28864b628", "amount": "190000000000000000", "fee": "10000000000000000", "state": "OPPOSITE_CONFIRMED", "dateTime": "1556129201000" }], "inTxExplorerFormat": "https://explorer.vite.org/transaction/{$tx}", "outTxExplorerFormat": "https://ropsten.etherscan.io/tx/{$tx}" } }

# Error Code

Code Description
0 Request is successful
1 Invalid request parameter
2 Internal Gateway error

# Version of the Specification

# Current Version

v1.0

# Historical Version(s)

Version Description
v1.0 Initial version
Found an Issue?
Help us improve this page by suggesting edits on GitHub.
vite.org
© 2023 Vite Labs.