Skip to main content

API List

VeChain
  • Updated
Follow
API Description
v2/tokens Get access token
user/v5/batchCreateUser Create account
vip181/v3/uid/mintToken Mint NFT to account
vip181/v3/address/mintToken Mint NFT to address
vip181/v3/setName Set NFT name
vip181/v3/setSymbol Set NFT symbol
vip181/v3/setMetadataBaseURI Set NFT base url
vip181/v3/setMintable Toggle mintable status
vip181/v3/applyFor Apply for ownership transfer
vip181/v3/uid/approve Authorize NFT transfer by account in batches
vip181/v3/uid/setApprovalForAll Manage all NFTs by authorized account
vip181/v3/uid/transfer Transfer NFT to account
vip181/v3/address/transfer Transfer NFT to address
vip181/v3/uid/uid/transferFrom Authorized transfer: from account to account 
vip181/v3/uid/address/transferFrom Authorized transfer: from account to address 
vip181/v3/address/uid/transferFrom Authorized transfer: from address to account
vip181/v3/address/address/transferFrom Authorized transfer: from address to address
vip181/v3/query/tokenByIndex Query NFT by index
vip181/v3/query/uid/tokenOfOwnerByIndex Query NFT of the specified account by index
vip181/v3/query/address/tokenOfOwnerByIndex Query NFT of the specified address by index
vip181/v3/query/tokensByRange Query NFT based on the range of index
vip181/v3/query/uid/tokensOfOwnerByRange Query the specified account NFT based on the range of index
vip181/v3/query/address/tokensOfOwnerByRange Query the specified Address NFT based on the range of index
vip181/v3/query/uid/balanceOf Query NFT balance of the specified account
vip181/v3/query/uid/getApplication Query tokenId of NFT according to the applicant account
vip181/v3/query/address/getApplication Query tokenId of NFT according to the applicant address
vip181/v3/query/getApproved Query approved authorized account
vip181/v3/query/uid/uid/isApprovedForAll Query whether account A has all the authorizations of account B
vip181/v3/query/ownerOf Query the owner of NFT
vip181/v3/query/totalSupply Query total supply of smart contract
vip181/v3/query/name Query NFT name
vip181/v3/query/metadataBaseURI Query NFT base url 
vip181/v3/query/mintable Query mintable status of smart contract
vip181/v3/query/symbol Query NFT symbol
vip181/v3/query/tokenURI Query NFT url

 

Request URL

  • AWS / Projects hosted outside of China: https://developer.vetoolchain.com/api/

  • Ali / Projects hosted inside China: https://developer.vetoolchain.cn/api/

 

Request Header

Header Description Example
content-type indicates the media type of the resource application/json;charset=utf-8
x-api-token contains the JWT token to authenticate a user  eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

 

Result Code

code message codeString
1
success
success
-1 ERR_SERVER_ERROR SYNCFailRetry
1002
Exception, parameter {0} is empty
 SYNCFailTerminate
1003
Exception, parameter {0} is illegal
SYNCFailTerminate
1100 ERR_GET_DEVELOPER_INFO_FAILED SYNCFailTerminate
1101 ERR_GENERATE_TOKEN_FAILED SYNCFailTerminate
1102 ERR_VERIFY_SIGNATURE_FAILED SYNCFailTerminate
2100 ERR_DEVELOPER_INFO_IS_NOT_FOUND SYNCFailTerminate
2119 ERR_DEVELOPER_TOKEN_IS_EXPIRED SYNCFailTerminate
2120 ERR_DEVELOPER_PROJECT_IS_NOT_ENABLED SYNCFailTerminate
2121 ERR_DEVELOPER_TOKEN_IS_NOT_WITHIN_TIME_FRAME SYNCFailTerminate
3019 ERR_TCC_INSUFFICIENT SYNCFailTerminate
100004 ERR_TOKEN_IS_INVAILD SYNCFailTerminate
100006 ERR_NO_ACCESS SYNCFailTerminate

 

Description: When the request fails, codeString has two definitions. Among them, when codeString returns SYNCFailRetry, an internal system error occurs, indicating that the request needs to be retried. When it returns to SYNCFailTerminate, it means that the request has failed verification. Please reconstruct the request according to the error message.

 

Terms

Status

When you send the request, the requestNo is the request number, orderStatus is the request status. Inside one request, there may be several sub-requests. For example: mint NFT to account, you can have many [tokenId, toUID] pairs inside one request, each will have a transaction on blockchain. Here the orderStatus means the whole request status, if any of transactions is FAILED, it will fail. Therefore, when the request status (orderStatus) is failed, please check the on-chain status of each transaction.

Name Type Description
orderStatus string PROCESSING, SUCCESS, FAILED

 

Account

When the client calls to create account, the escrow account created in ToolChain consists of two parts: UID and wallet address. The address is derived from UID, and they are same.

Name Type Description
UID string account, 32bytes, hex string
Address string address, 20bytes, hex string

 

 Idempotent

ToolChain®️'s idempotent processing of write requests requires the requester to provide the request number (requestNo) to achieve. The same request number will only be executed once in ToolChain®️, and repeated requests will be regarded as query operations.

  • Get access token

    POST v2/tokens

Get token, for the method of obtaining appid and appkey, please refer to here 

Java Sample:

signString ：appid=15cf8af3ebeca443d377bd5c2658cae9
&appkey=15cf8af3ebeca443d377bd5c2658cae98a1030dd513184568e89fbbd776bc2cb
&nonce =3806143519628774
&timestamp=1552185608

signature ： sha256( signString )

public static String sha256( String text )
{
    try {
        MessageDigest message = MessageDigest.getInstance( "SHA-256" );

        byte[] hash = message.digest( text.getBytes( "UTF-8" ) );

        return(Hex.encodeHexString( hash ) );
    } catch ( Exception e ) {
        e.printStackTrace();
    }

    return(null);
}


public static String signature( TokenRequest request )
{
    StringBuffer sign = new StringBuffer();

    sign.append( String.format( "appid=%s&", request.getAppid() ) );

    sign.append( String.format( "appkey=%s&", appkey ) );

    sign.append( String.format( "nonce=%s&", request.getNonce() ) );

    sign.append( String.format( "timestamp=%s", request.getTimestamp() ) );

    return(sha256( sign.toString().toLowerCase() ) );
}


public static void testGetToken()
{
    TokenRequest request = new TokenRequest();

    request.setAppid( appid );

    request.setNonce( RandomUtils.nextHexString( 8 ) );

    request.setTimestamp( String.valueOf( (System.currentTimeMillis() / 1000) ) );

    request.setSignature( signature( request ) );

    System.out.println( JSONObject.toJSONString( request ) );
}

Request Parameters

Name Type Required Description
appid string Y appid
nonce string Y random number (length is 16)
signature string Y sha256 signature
timestamp string Y current timestamp, within 5 minutes (UTC time)
source string N application request source. For the same request source, the valid request is the latest request

Request Example

{
    "appid": "15cf8af3ebeca443d377bd5c2658cae9",
    "nonce": "3806143519628774",
    "signature": "1c442f56664317d81c32e41010660f54ba1e71223fa6d766ebbe45de3906998b",
    "timestamp": "1552185608"
}

Response Example

{
    "code": "common.success",
    "data": {
        "timeToLive": 86400,
        "expireTime": 1593257539,
        "expire": 86400,
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbklkIjoiNGNhY2IyNzk3NDVjIiwiYXBwSWQiOiJhODJiN2I5MGNmMDE0ZDFhMDk5YzEzOTdmMzA5NzZiYyIsInNvdXJjZSI6ImFhYSIsImV4cCI6MTU5MzI1NzUzOSwiaWF0IjoxNTkzMTcxMTM5fQ.YhXSdmicmbjajIiZqyIPpUPWn1lFrsO6G8-JWK_yXmY"
    }
}

Response Parameters

Name Type Description
token string returned token
expire integer token effective time (24 hours), unit: second
timeTolive integer token remaining effective time, unit: second
expireTime integer expiry timestamp

After getting the token, you can start sending **HTTP GET/POST** requests to call the blockchain service. Each time it is called, please make sure that the value of the x-api-token of the HTTP request is valid.

  • Create account

    POST user/v5/batchCreateUser

create account. Please repeat the request until the orderStatus becomes the final status.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
quantity integer Y quantity. It is recommended to create no more than 5 in a single request.

Request Example

{
    "quantity": 5,
    "requestNo": "20210701-001"
}

Response Example

{
        "data": {
        "requestNo": "20210701-001",
        "orderStatus": "SUCCESS",
        "users": [
            {
                "address": "0xc6914fa7e1409e0d2e85933331f9f0394163de52",
                "uid": "0x57795956418a28ba9a72181fe323fb509f9c6959362ff2e3a13ee0128218e6d6"
            },
            {
                "address": "0xb4ae46837fdd6a41c9fbd2e3d6d1fe4007023b66",
                "uid": "0xd5a3e4dce2d7d8438104157ca3b53a1b1a2bd4b44e9bce45bb1d15bdfa7703d5"
            },
            {
                "address": "0xf55ca42b56746f93fc2792484bf9648ce0d2b5ee",
                "uid": "0xe78e2e860ef455958517a359dd19e3f4093f41bba7653919bed8c91ceeddf777"
            },
            {
                "address": "0xd4cd05fcceb154ddce38aa28ce5158bd34740ee6",
                "uid": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b"
            },
            {
                "address": "0x8c80140ad3b83926af555830a63309b98c25cd47",
                "uid": "0x2203b26196f5f41789a9285d50c5838de439ef7e93063465bfc9bbf19554b163"
            }
        ]
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Parameters

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
+ users array account list
└ uid string UID of account, start with '0x', 32 bytes
└ address string address of UID, start with '0x', 20 bytes

  • Mint NFT to account

    POST vip181/v3/uid/mintToken

mint a non-fungible token to a specific account. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the ownerUID field in the request parameters is the UID of the administrator account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
ownerUID string Y UID of the administrator account, start with '0x', 32 bytes, please refer to here
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ toUID string Y UID of the target account, start with '0x', 32 bytes

Request Example

{
    "requestNo": "mintTokenToUID20210702001",
    "tokenContractAddress": "0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "list": [
        {
            "tokenId": "1",
            "toUID": "0x57795956418a28ba9a72181fe323fb509f9c6959362ff2e3a13ee0128218e6d6"
        },
        {
            "tokenId": "2",
            "toUID": "0xd5a3e4dce2d7d8438104157ca3b53a1b1a2bd4b44e9bce45bb1d15bdfa7703d5"
        }
    ],
    "ownerUID": "0x42ceddea9c55dcf8087b7d65232cf6f4a8a38ff2621e40443af42bc6b530198e"
}

Response Example

{
    "data": {
        "requestNo": "mintTokenToUID20210702001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0xfbab3c4dd941c90af3a1a8b4e3a0421063b29be71b932e21b5948ebff7a1d3d8",
                "txStatus": "SUCCESS",
                "tokenId": "1"
            },
            {
                "clauseIndex": 1,
                "txID": "0xfbab3c4dd941c90af3a1a8b4e3a0421063b29be71b932e21b5948ebff7a1d3d8",
                "txStatus": "SUCCESS",
                "tokenId": "2"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Parameters

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Mint NFT to address

    POST vip181/v3/address/mintToken

mint a non-fungible token to a specific address. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the ownerUID field in the request parameters is the UID of the administrator account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
ownerUID string Y UID of the administrator account, start with '0x', 32 bytes, please refer to here
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ toAddress string Y target address, start with '0x', 20 bytes

Request Example

{
    "requestNo": "mintTokenToAddress20210702001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "list": [
        {
            "tokenId": "3",
            "toAddress": "0xc6914fa7e1409e0d2e85933331f9f0394163de52"
        },
        {
            "tokenId": "4",
            "toAddress": "0xb4ae46837fdd6a41c9fbd2e3d6d1fe4007023b66"
        } 
    ],
    "ownerUID": "0x42ceddea9c55dcf8087b7d65232cf6f4a8a38ff2621e40443af42bc6b530198e"
}

Response Example

{
        "data": {
        "requestNo": "mintTokenToAddress20210702001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0x77e30a098d9b06789300d16698b041c5efa2b1c6755438516b1878c9489fd267",
                "txStatus": "SUCCESS",
                "tokenId": "3"
            },
            {
                "clauseIndex": 1,
                "txID": "0x77e30a098d9b06789300d16698b041c5efa2b1c6755438516b1878c9489fd267",
                "txStatus": "SUCCESS",
                "tokenId": "4"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Parameters

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Set NFT name

    POST vip181/v3/setName

Set name for NFT. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the ownerUID field in the request parameters is the UID of the administrator account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
name string Y NFT name, maximum length is 255
ownerUID string Y UID of the administrator account, start with '0x', 32 bytes, please refer to here

Request Example

{
    "requestNo": "setName20210702001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "name":"name_vet",
    "ownerUID":"0x42ceddea9c55dcf8087b7d65232cf6f4a8a38ff2621e40443af42bc6b530198e"
}

Response Example

{
        "data": {
        "requestNo": "setName20210702001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "clauseIndex": 0,
        "txID": "0x89f81cd56bfc90a6dbbecfe9f4fc32994047e2f3c09e28cb64feb94778998df0",
        "txStatus": "SUCCESS",
        "tokenId": null,
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181TxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
txID string blockchain transaction ID
txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
tokenId string here tokenId returns null

  • Set NFT symbol

    POST vip181/v3/setSymbol

Set symbol for NFT. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the ownerUID field in the request parameters is the UID of the administrator account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
symbol string Y NFT symbol, maximum length is 255
ownerUID string Y UID of the administrator account, start with '0x', 32 bytes, please refer to here

Request Example

{
    "requestNo": "setSymbol20210702001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "symbol":"VET-Symbol",
    "ownerUID": "0x42ceddea9c55dcf8087b7d65232cf6f4a8a38ff2621e40443af42bc6b530198e"
}

Response Example

{
        "data": {
        "requestNo": "setSymbol20210702001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "clauseIndex": 0,
        "txID": "0xa251c5d87f5bfbcda5bb606df159ca046f57a885e87681f6aad3be3012a268fc",
        "txStatus": "SUCCESS",
        "tokenId": null,
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181TxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
txID string blockchain transaction ID
txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
tokenId string here tokenId returns null

  • Set NFT base url 

    POST vip181/v3/setMetadataBaseURI

Set base url for NFT. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the ownerUID field in the request parameters is the UID of the administrator account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
baseURI string Y base url
ownerUID string Y UID of the administrator account, start with '0x', 32 bytes, please refer to here

Request Example

{
     "requestNo": "setMetadataBaseURI20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "baseURI":"https://www.vechain.com/",
    "ownerUID": "0x42ceddea9c55dcf8087b7d65232cf6f4a8a38ff2621e40443af42bc6b530198e"
}

Response Example

{
        "data": {
        "requestNo": "setMetadataBaseURI20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "clauseIndex": 0,
        "txID": "0x86bb185d51121f3cb45d8935684adc6f70efbae12e2ecc789af6a611558a03e8",
        "txStatus": "SUCCESS",
        "tokenId": null,
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181TxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
txID string blockchain transaction ID
txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
tokenId string here tokenId returns null

  • Toggle mintable status 

    POST vip181/v3/setMintable

Toggle mintable status. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the ownerUID field in the request parameters is the UID of the administrator account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
ownerUID string Y UID of the administrator account, start with '0x', 32 bytes, please refer to here
mintable boolean Y Whether to allow minting

Request Example

{
    "requestNo": "setMintable20210701003",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "mintable": true,
    "ownerUID": "0x42ceddea9c55dcf8087b7d65232cf6f4a8a38ff2621e40443af42bc6b530198e"
}

Response Example

{
        "data": {
        "requestNo": "setMintable20210701003",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "clauseIndex": 0,
        "txID": "0x62e960f3385eba6ba826e41bab9f1aa8f574589c4ddffb3517489b6eafe05e7b",
        "txStatus": "SUCCESS",
        "tokenId": null,
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181TxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
txID string blockchain transaction ID
txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
tokenId string here tokenId returns null

  • Apply for ownership transfer

    POST vip181/v3/applyFor

Initiate a transfer application to the owner of NFT. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
applicantUID string Y applicant UID,start with '0x',32 bytes
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].

Request Example

{
    "requestNo": "applyFor20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "applicantUID": "0xe78e2e860ef455958517a359dd19e3f4093f41bba7653919bed8c91ceeddf777",
    "tokenID": "1"
}

Response Example

{
       "data": {
        "requestNo": "applyFor20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "clauseIndex": 0,
        "txID": "0x8c79c8604e13907237f1332fb95982b88f74c5d8544d39ba16df822836d49a60",
        "txStatus": "SUCCESS",
        "tokenId": null,
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181TxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
txID string blockchain transaction ID
txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
tokenId string here tokenId returns null

  • Authorize NFT transfer by account in batches

    POST vip181/v3/uid/approve

Authorize NFT transfer by account in batches . Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

2. Check whether the currentOwnerUID field of the request parameter is the UID of the current NFT owner. You can use query NFT owner interface to confirm the owner of the NFT.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
currentOwnerUID string Y UID of current owner, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ delegateUID string Y the UID of authorized account, start with '0x', 32 bytes

Request Example

{
    "requestNo": "approve20210705002",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "currentOwnerUID": "0x57795956418a28ba9a72181fe323fb509f9c6959362ff2e3a13ee0128218e6d6",
    "list": [
            {
                    "tokenId": "5",
                    "delegateUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b"
            },
            {
                    "tokenId": "6",
                    "delegateUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b"
            }
    ]
}

Response Example

{
        "data": {
        "requestNo": "approve20210705002",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0xf02c86ec14ce9390808f0ada356bc97de8414f9b990685081f8fd2e0c055800e",
                "txStatus": "SUCCESS",
                "tokenId": "5"
            },
            {
                "clauseIndex": 1,
                "txID": "0xf02c86ec14ce9390808f0ada356bc97de8414f9b990685081f8fd2e0c055800e",
                "txStatus": "SUCCESS",
                "tokenId": "6"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Manage all NFTs by authorized account

    POST vip181/v3/uid/setApprovalForAll

Manage all NFTs by authorized account. Please repeat the request until the orderStatus becomes the final status.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
currentOwnerUID string Y UID of current owner, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ approved boolean Y if approved
└ delegateUID string Y the UID of authorized account, start with '0x', 32 bytes

Request Example

{
     "requestNo": "setApprovalForAll20210701002",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "currentOwnerUID": "0xd5a3e4dce2d7d8438104157ca3b53a1b1a2bd4b44e9bce45bb1d15bdfa7703d5",
    "list": [
            {
                    "approved": true,
                    "delegateUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b"
            }
    ]
}

Response Example

{
        "data": {
        "requestNo": "setApprovalForAll20210701002",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0x614f835be458fe5bfcdf2edcbed922da23e89b6347e158dd39aad92d6d5de74b",
                "txStatus": "SUCCESS",
                "tokenId": null
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string here tokenId returns null

  • Transfer NFT to account

    POST vip181/v3/uid/transfer

transfer NFT to account. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

2. Check whether the currentOwnerUID field of the request parameter is the UID of the current NFT owner. You can use query NFT owner interface to confirm the owner of the NFT.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
currentOwnerUID string Y UID of current owner, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ toUID string Y UID of target account, start with '0x', 32 bytes

Request Example

{
    "requestNo": "transfer20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "currentOwnerUID": "0x57795956418a28ba9a72181fe323fb509f9c6959362ff2e3a13ee0128218e6d6",
    "list": [
            {
                    "tokenId": "1",
                    "toUID": "0xe78e2e860ef455958517a359dd19e3f4093f41bba7653919bed8c91ceeddf777"
            }
    ]
}

Response Example

{
        "data": {
        "requestNo": "transfer20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0x69e9a019959e478b3766ce6c9cea472fb211985ccec51fbc0b124d001ca11dd7",
                "txStatus": "SUCCESS",
                "tokenId": "1"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Transfer NFT to address

    POST vip181/v3/address/transfer

transfer NFT to address. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

2. Check whether the currentOwnerUID field of the request parameter is the UID of the current NFT owner. You can use query NFT owner interface to confirm the owner of the NFT.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
currentOwnerUID string Y UID of current owner, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ toAddress string Y target address, start with '0x', 20 bytes

Request Example

{
    "requestNo": "transferAddress20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "currentOwnerUID": "0xe78e2e860ef455958517a359dd19e3f4093f41bba7653919bed8c91ceeddf777",
    "list": [
            {
                    "tokenId": "1",
                    "toAddress": "0xd4cd05fcceb154ddce38aa28ce5158bd34740ee6"
            }
    ]
}

Response Example


        "data": {
        "requestNo": "transferAddress20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0xcd08f28330381b1f120d834a398071c7e5bdcb21c860a2514c76722cd9efadad",
                "txStatus": "SUCCESS",
                "tokenId": "1"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Authorized transfer: from account to account

    POST vip181/v3/uid/uid/transferFrom

Authorized transfer: from account to account. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

2. Check whether the currentOwnerUID field of the request parameter is the UID of the current NFT owner. You can use query NFT owner interface to confirm the owner of the NFT.

3. Check whether the delegateUID field in the request parameters has been authorized by the current NFT owner. You can use the interface to query whether account A has all the authorizations of account B to determine whether the authorized account has been fully authorized. If all authorizations have been obtained, you can authorize the transfer, otherwise you need to call query approved authorized account interface to confirm the current NFT authorized account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
delegateUID string Y UID of authorized account, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ currentOwnerUID string Y UID of authorized account, start with '0x', 32 bytes
└ message string N comment
└ toUID string Y UID of target account, start with '0x', 32 bytes

Request Example

{
    "requestNo": "transferFromUID2UID20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "delegateUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b",
    "list": [
            {
                    "tokenId": "5",
                    "currentOwnerUID": "0x57795956418a28ba9a72181fe323fb509f9c6959362ff2e3a13ee0128218e6d6",
                    "message": "transfer",
                    "toUID": "0x2203b26196f5f41789a9285d50c5838de439ef7e93063465bfc9bbf19554b163"
            }
    ]
}

Response Example

{
        "data": {
        "requestNo": "transferFromUID2UID20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0x98aae3239cdf3659c5568fb93f2a3bb5196a332ff673c57c2cfe828298c586b7",
                "txStatus": "SUCCESS",
                "tokenId": "5"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Authorized transfer: from account to address

    POST vip181/v3/uid/address/transferFrom

Authorized transfer: from account to address. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

2. Check whether the currentOwnerUID field of the request parameter is the UID of the current NFT owner. You can use query NFT owner interface to confirm the owner of the NFT.

3. Check whether the delegateUID field in the request parameters has been authorized by the current NFT owner. You can use the interface to query whether account A has all the authorizations of account B to determine whether the authorized account has been fully authorized. If all authorizations have been obtained, you can authorize the transfer, otherwise you need to call query approved authorized account interface to confirm the current NFT authorized account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
delegateUID string Y UID of authorized account, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ currentOwnerUID string Y UID of authorized account, start with '0x', 32 bytes
└ message string N comment
└ toAddress string Y target address, start with '0x' ,20 bytes

Request Example

{
    "requestNo": "transferFromUID2Address20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "delegateUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b",
    "list": [
            {
                    "tokenId": "6",
                    "currentOwnerUID": "0x57795956418a28ba9a72181fe323fb509f9c6959362ff2e3a13ee0128218e6d6",
                    "message": "transfer",
                    "toAddress": "0x8c80140ad3b83926af555830a63309b98c25cd47"
            }
    ]
}

Response Example

{
        "data": {
        "requestNo": "transferFromUID2Address20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0x7a7afd96c4c274d3e50930f423acf621ee88ba575ccac6a9d585630c3809144d",
                "txStatus": "SUCCESS",
                "tokenId": "6"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Authorized transfer: from address to account

    POST vip181/v3/address/uid/transferFrom

Authorized transfer: from address to account. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

2. Check whether the currentOwnerAddress field of the request parameter is the address of the current NFT owner. You can use query NFT owner interface to confirm the owner of the NFT.

3. Check whether the delegateUID field in the request parameters has been authorized by the current NFT owner. You can use the interface to query whether account A has all the authorizations of account B to determine whether the authorized account has been fully authorized. If all authorizations have been obtained, you can authorize the transfer, otherwise you need to call query approved authorized account interface to confirm the current NFT authorized account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
delegateUID string Y UID of authorized account, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ currentOwnerAddress string Y address of current owner, start with '0x', 20 bytes
└ message string N comment
└ toUID string Y UID of target account, start with '0x', 32 bytes

Request Example

 {
    "requestNo": "transferFromAddress2UID20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "delegateUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b",
    "list": [
            {
                    "tokenId": "7",
                    "currentOwnerAddress": "0xc6914fa7e1409e0d2e85933331f9f0394163de52",
                    "message": "transfer",
                    "toUID": "0x2203b26196f5f41789a9285d50c5838de439ef7e93063465bfc9bbf19554b163"
            }
    ]
}

Response Example

 {
    "data": {
        "requestNo": "transferFromAddress2UID20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0xc1eb14603da797ee91a5f107e4b53425c9a070c0f9f0ddfd36d4366a21897ec3",
                "txStatus": "SUCCESS",
                "tokenId": "7"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Authorized transfer: from address to address

    POST vip181/v3/address/address/transferFrom

Authorized transfer: from address to address. Please repeat the request until the orderStatus becomes the final status.

Note: When the smart contract transaction fails, there will be an error message in the errorMsg field of the response result. Please check as follows:

1. Check whether the tokenId field in the request parameter exists in the current smart contract. You can use query NFT owner interface. If the address field in the response parameter returns 0x0000000000000000000000000000000000000000, it indicates that the current tokenId does not exist in the current smart contract.

2. Check whether the currentOwnerAddress field of the request parameter is the address of the current NFT owner. You can use query NFT owner interface to confirm the owner of the NFT.

3. Check whether the delegateUID field in the request parameters has been authorized by the current NFT owner. You can use the interface to query whether account A has all the authorizations of account B to determine whether the authorized account has been fully authorized. If all authorizations have been obtained, you can authorize the transfer, otherwise you need to call query approved authorized account interface to confirm the current NFT authorized account.

Request Parameters

Name Type Required Description
requestNo string Y the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
delegateUID string Y UID of authorized account, start with '0x', 32 bytes
+ list array Y request list, the maximum number of lists is 50
└ tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].
└ currentOwnerAddress string Y address of current owner, start with '0x', 20 bytes
└ message string N comment
└ toAddress string Y target address, start with '0x' ,20 bytes

Request Example


    "requestNo": "transferFromAddress2Address20210705001",
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "delegateUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b",
    "list": [
            {
                    "tokenId": "8",
                    "currentOwnerAddress": "0xc6914fa7e1409e0d2e85933331f9f0394163de52",
                    "message": "transfer",
                    "toAddress": "0x8c80140ad3b83926af555830a63309b98c25cd47"
            }
    ] 
}

Response Example

 {
    "data": {
        "requestNo": "transferFromAddress2Address20210705001",
        "orderStatus": "SUCCESS",
        "errorMsg": null,
        "errorMsgDetailList": null,
        "list": [
            {
                "clauseIndex": 0,
                "txID": "0xea2b6ee21d6f2f33b52b4f35d1981af0d7c606adf8793e9cabc73f522195557a",
                "txStatus": "SUCCESS",
                "tokenId": "8"
            }
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181BatchTxResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
requestNo string the maximum length is 50, which is generated by the requester to ensure that the request is idempotent
orderStatus string request status(PROCESSING, SUCCESS, FAILED)
errorMsg string transaction failure information
+ list array return list, the order is the same as request list
└ clauseIndex integer clause index of the blockchain transaction. For clauses, please refer to blockchain Multi-Task Transaction (MTT)
└ txID string blockchain transaction ID
└ txStatus string blockchain transaction status, Currently, only SUCCESS is supported. If it fails, the transaction failure information will be returned in the errorMsg field.
└ tokenId string consistent with the tokenId value passed in

  • Query NFT by index

    POST vip181/v3/query/tokenByIndex

Query NFT of the current smart contract according to the index number, only supported in smart contract 6.0 and later versions.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
index integer Y Index number, start from 0

Request Example

{
    "tokenContractAddress":"0x1e5976912bc2c939e9c08ea6ce9d91d52b241a57",
    "index":0
}

Response Example

{
    "data": {
        "tokenId": "1",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181GetTokenIdResponse"
    },
    "code": 1,
    "message": "success",
    "replaceMsg": null,
    "codeString": "success"
}

Response Params

Name Type Description
tokenId string tokenId, returns a decimal value

  • Query NFT of the specified account by index

    POST vip181/v3/query/uid/tokenOfOwnerByIndex

Query the NFT of the specified account according to the index number, only supported in smart contract 6.0 and later versions.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
ownerUID string Y queried UID of account，start with '0x', 32 bytes
index integer Y Index number, start from 0

Request Example

{
    "tokenContractAddress":"0x1e5976912bc2c939e9c08ea6ce9d91d52b241a57",
    "ownerUID":"0x712da6e1cc45d3a2bcf89058a296e8c5d3ca04e36e5252bd45b9c567ac32c522",
    "index":0
}

Response Example

{
    "data": {
        "tokenId": "100",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181GetTokenIdResponse"
    },
    "code": 1,
    "message": "success",
    "replaceMsg": null,
    "codeString": "success"
}

Response Params

Name Type Description
tokenId string tokenId, returns a decimal value

  • Query NFT of the specified address by index

    POST vip181/v3/query/address/tokenOfOwnerByIndex

Query the NFT of the specified address according to the index number, only supported in smart contract 6.0 and later versions.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
ownerAddress string Y address of account, start with '0x',20 bytes
index integer Y Index number, start from 0

Request Example

{
    "tokenContractAddress":"0x1e5976912bc2c939e9c08ea6ce9d91d52b241a57",
    "ownerAddress":"0xf4e2c3415fcfff89d3340f617e0f7977fb354490",
    "index":0
}

Response Example

{
    "data": {
        "tokenId": "100",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181GetTokenIdResponse"
    },
    "code": 1,
    "message": "success",
    "replaceMsg": null,
    "codeString": "success"
}

Response Params

Name Type Description
tokenId string tokenId, returns a decimal value

  • Query NFT based on the range of index

    POST vip181/v3/query/tokensByRange

Query NFT based on the range of index, only supported in smart contract 6.0 and later versions.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
offset integer Y Index number, start from 0
size integer Y The number displayed, up to 10

Request Example

{
    "tokenContractAddress":"0x1e5976912bc2c939e9c08ea6ce9d91d52b241a57",
    "offset":1,
    "size":3
}

Response Example

{
    "data": {
        "tokenIds": [
            "2",
            "3",
            "20"
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181GetTokenIdsResponse"
    },
    "code": 1,
    "message": "success",
    "replaceMsg": null,
    "codeString": "success"
}

Response Params

Name Type Description
tokenIds array[string] Collection of tokenIds

  • Query the specified account NFT based on the range of index

    POST vip181/v3/query/uid/tokensOfOwnerByRange

Query the specified account NFT based on the index number range, only supported in smart contract 6.0 and later versions.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
ownerUID string Y UID of account, start with '0x',32 bytes
offset integer Y Index number, start from 0
size integer Y The number displayed, up to 10

Request Example

{
    "tokenContractAddress":"0x1e5976912bc2c939e9c08ea6ce9d91d52b241a57",
    "ownerUID":"0x712da6e1cc45d3a2bcf89058a296e8c5d3ca04e36e5252bd45b9c567ac32c522",
    "offset":1,
    "size":3
}

Response Example

{
    "data": {
        "tokenIds": [
            "103",
            "104",
            "105"
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181GetTokenIdsResponse"
    },
    "code": 1,
    "message": "success",
    "replaceMsg": null,
    "codeString": "success"
}

Response Params

Name Type Description
tokenIds array[string] Collection of tokenIds

  • Query the specified Address NFT based on the range of index

    POST vip181/v3/query/address/tokensOfOwnerByRange

Query the specified Address NFT based on the index number range, only supported in smart contract 6.0 and later versions.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
ownerAddress string Y address of account, start with '0x',20 bytes
offset integer Y Index number, start from 0
size integer Y The number displayed, up to 10

Request Example

{
    "tokenContractAddress":"0x1e5976912bc2c939e9c08ea6ce9d91d52b241a57",
    "ownerAddress":"0xf4e2c3415fcfff89d3340f617e0f7977fb354490",
    "offset":1,
    "size":3
}

Response Example

{
    "data": {
        "tokenIds": [
            "103",
            "104",
            "105"
        ],
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181GetTokenIdsResponse"
    },
    "code": 1,
    "message": "success",
    "replaceMsg": null,
    "codeString": "success"
}

Response Params

Name Type Description
tokenIds array[string] Collection of tokenIds

  • Query NFT balance of the specified account

    POST vip181/v3/query/uid/balanceOf

Query NFT balance of the specified account.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
uid string Y queried UID of account，start with '0x', 32 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "uid":"0x2203b26196f5f41789a9285d50c5838de439ef7e93063465bfc9bbf19554b163"
}

Response Example

{
        "data": {
        "balance": "8",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QBalanceOfResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
balance string balance, returns the decimal value

  • Query tokenId of NFT according to the applicant account

    POST vip181/v3/query/uid/getApplication

Query tokenId of NFT according to the applicant account.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
applicantUID string Y UID of applicant account, start with '0x',32 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "applicantUID":"0xe78e2e860ef455958517a359dd19e3f4093f41bba7653919bed8c91ceeddf777"
}

Response Example

{
    "data": {
        "tokenId": "1",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QGetApplicationResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
tokenId string tokenId，returns the decimal value

  • Query tokenId of NFT according to the applicant address

    POST vip181/v3/query/address/getApplication

Query tokenId of NFT according to the applicant address.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
applicantAddress string Y the address of applicant account, start with '0x',20 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "applicantAddress":"0xf55ca42b56746f93fc2792484bf9648ce0d2b5ee"
}

Response Example

{
    "data": {
        "tokenId": "1",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QGetApplicationResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
tokenId string tokenId，returns the decimal value

  • Query approved authorized account

    POST vip181/v3/query/getApproved

Query approved authorized account.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "tokenId": "3"
}

Response Example

{
    "data": {
        "delegateAddress": "0xd4cd05fcceb154ddce38aa28ce5158bd34740ee6",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QGetApprovedResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
delegateAddress string the address of authorized account, start with '0x', 20 bytes

  • Query whether account A has all the authorizations of account B

    POST vip181/v3/query/uid/uid/isApprovedForAll

Query whether account A has all the authorizations of account B.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
operatorUID string Y UID of the account being queried, start with '0x', 32 bytes
ownerUID string Y UID of current owner account,start with '0x',32 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "operatorUID": "0x56f386ef92baec301bfdf2ccfb5e143725116585f95d55b80eab8d40a94ed25b",
    "ownerUID": "0xd5a3e4dce2d7d8438104157ca3b53a1b1a2bd4b44e9bce45bb1d15bdfa7703d5"
}

Response Example

{
    "data": {
        "approved": true,
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QIsApprovedForAllResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
approved boolean If approved

  • Query the owner of NFT

    POST vip181/v3/query/ownerOf

return the owner of NFT.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "tokenId": "1"
}

Response Example

{
    "data": {
        "address": "0xd4cd05fcceb154ddce38aa28ce5158bd34740ee6",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QOwnerOfResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
address string the address of current owner account, start with '0x',20 bytes

  • Query total supply of smart contract

    POST vip181/v3/query/totalSupply

Return total supply of smart contract.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336"
}

Response Example

{
    "data": {
        "totalSupply": "18",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QTotalSupplyResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
totalSupply string total supply, returns a decimal value

  • Query NFT name

    POST vip181/v3/query/name

return NFT name.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336"
}

Response Example

{
    "data": {
        "name": "name_vet",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QNameResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
name string NFT name

  • Query NFT base url

    POST vip181/v3/query/metadataBaseURI

Query NFT base url.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336"
}

Response Example

{
    "data": {
        "metadataBaseURI": "https://www.vechain.com/",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QMetabaseURIResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
metadataBaseURI string base url

  • Query mintable status of smart contract

    POST vip181/v3/query/mintable

return mint status.

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336"
}

Response Example

{
    "data": {
        "mintable": true,
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QMintableResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
mintable boolean Whether to allow minting

  • Query NFT symbol

    POST vip181/v3/query/symbol

Return NFT symbol

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336"
}

Response Example

{
    "data": {
        "symbol": "VET-Symbol",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QSymbolResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
symbol string NFT symbol

  • Query NFT url

    POST vip181/v3/query/tokenURI

Return NFT url

Request Parameters

Name Type Required Description
tokenContractAddress string Y smart contract address, start with '0x',20 bytes
tokenId string Y tokenId, It supports decimal and hexadecimal. If it starts at '0x', it is hexadecimal. Id value range is [0,2256-1].

Request Example

{
    "tokenContractAddress":"0x0589a3e0d043fdcccf9c8ef88a77259666b6c336",
    "tokenId": "1"
}

Response Example

{
    "data": {
        "uri": "https://www.vechain.com/0x0000000000000000000000000000000000000000000000000000000000000001",
        "@clazz": "com.vechain.tconchain.model.vip181.response.VIP181QTokenURIResponse"
    },
    "code": 1,
    "message": "success",
    "codeString": "success"
}

Response Params

Name Type Description
uri string NFT url


Appendix

 

Q: How to get the appid and appkey of the project

A: Log in to the system with an administrator account, click Developer Center -> Server Application, and copy APPID and APPIKEY. Each account can support up to 10 pairs of appid and appkey

appidappkey_en.png

 

 

Q: How to get the UID of the administrator account

A: Log in to the system with an administrator account, click Console -> Business Contract , Owner UID is what you want to get.

OWNERUID.png

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk