VECHAIN Docs
Search
⌃K

Thorest API

RESTful API to access VeChain Thor Network
License: LGPL 3.0

Accounts

Access to account objects

GET /accounts/{address}

Summary:
Retrieve account detail includes balance, energy and hasCode. If the account with hasCode is true then ,it is a contract.
Historical account detail can be queried by specifying revision query string.
Parameters
Parameter
Type
Required
Description
Example
address
string
Yes
address of account
0x5034aa590125b64023a0262112b98d72e3c8e40e
revision
string
Optional
can be block number or id (best block is assumed if omitted).
3877527 (block# 3877527) 0x003dc697f70205861a70fd3e52a24a542613b564bf6d8b7b4149c6b3ee6e015d (block#3877527 ID)
Responses
  • curl
curl -X GET "https://sync-testnet.vechain.org/accounts/0x5034aa590125b64023a0262112b98d72e3c8e40e?revision=0x003dc697f70205861a70fd3e52a24a542613b564bf6d8b7b4149c6b3ee6e015d" -H "accept: application/json"
  • Request url
https://sync-testnet.vechain.org/accounts/0x5034aa590125b64023a0262112b98d72e3c8e40e?revision=0x003dc697f70205861a70fd3e52a24a542613b564bf6d8b7b4149c6b3ee6e015d
Code
Description
200
OK
Response Body
{
"balance": "0x1e1fb2aca578373db2",
"energy": "0x45dc094003ac610617eb81",
"hasCode": false
}
Related Model :
Account
Name
Type
Description
Example
balance
string
balance in unit WEI, presented with hex string
0x47ff1f90327aa0f8e
energy
string
energy in unit WEI, presented with hex string
0x47ff1f90327aa0f8e
hasCode
boolean
whether the account has code
true or false

POST /accounts/*

Summary:
Execute a batch of codes
Parameters
Parameter
Type
Required
Description
Example
address
string
Yes
address of account
0x5034aa590125b64023a0262112b98d72e3c8e40e
key
string
Yes
the key(position) to access account storage
revision
string
Optional
can be block number or id (best block is assumed if omitted).
3877527 (block# 3877527) 0x003b2a97095a93d92b8dd45db88f0f90beaec398717ffd1d356b519c35ead4d0 (block#3877527 ID)
Responses
  • Curl
curl -X POST "https://sync-testnet.vechain.org/accounts/*?revision=best" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"clauses\":[{\"to\":\"0x5034aa590125b64023a0262112b98d72e3c8e40e\",\"value\":\"0xde0b6b3a7640000\",\"data\":\"0x5665436861696e2054686f72\"}],\"gas\":50000,\"gasPrice\":\"1000000000000000\",\"caller\":\"0x7567d83b7b8d80addcb281a71d54fc7b3364ffed\",\"provedWork\":\"1000\",\"gasPayer\":\"0xd3ae78222beadb038203be21ed5ce7c9b1bff602\",\"expiration\":1000,\"blockRef\":\"0x00000000851caf3c\"}"
  • Request URL
https://sync-testnet.vechain.org/accounts/*?revision=best
Code
Description
200
OK
Response Body
[
{
"data": "0x",
"events": [],
"transfers": [
{
"sender": "0x7567d83b7b8d80addcb281a71d54fc7b3364ffed",
"recipient": "0x5034aa590125b64023a0262112b98d72e3c8e40e",
"amount": "0xde0b6b3a7640000"
}
],
"gasUsed": 0,
"reverted": false,
"vmError": ""
}
]
Related Models :
BatchCallResult
CallResult
Event
Transfer
Name
Type
Description
batchCallResult
[callResult]
return batch call result
Name
Type
Description
Example
data
string
the output data
0x103556a73c10e38ffe2fc4aa50fc9d46ad0148f07e26417e117bd1ece9d948b5
events
[Event]
event output
see more in Event
transfers
[Transfer]
transfer output
see more in Transfer
gasUsed
integer (uint64)
gas used during execution
21000
reverted
boolean
whether the execution is reverted or not
false
vmError
string
error message will return when the execution is true
insufficient balance for transfer
Name
Type
Description
Example
address
string
the address of contract which produces the event (bytes20)
0x7567d83b7b8d80addcb281a71d54fc7b3364ffed
topics
[string]
[0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8]
data
string
0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8
Name
Type
Description
Example
sender
string
address that sends tokens
0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d
recipient
string
address that receives tokens
0x5034aa590125b64023a0262112b98d72e3c8e40e
amount
string
amount of tokens
0x47fdb3c3f456c0000

GET /accounts/{address}/code

Summary:
Retrieve account code if any. Here the code is runtime bytecodes.
Parameters
Parameter
Type
Required
Description
Example
address
string
Yes
address of account
0x5034aa590125b64023a0262112b98d72e3c8e40e
revision
string
Optional
can be block number or id (best block is assumed if omitted).
3877527 (block# 3877527) 0x003b2a97095a93d92b8dd45db88f0f90beaec398717ffd1d356b519c35ead4d0 (block#3877527 ID)
Responses
  • Curl
curl -X GET "https://sync-testnet.vechain.org/accounts/0x5034aa590125b64023a0262112b98d72e3c8e40e/code" -H "accept: application/json"
  • Request URL
https://sync-testnet.vechain.org/accounts/0x5034aa590125b64023a0262112b98d72e3c8e40e/code
Code
Description
200
OK
Response Body
{
"code": "0x"
}
Related Model :
Code
Name
Type
Description
Example
code
string
Runtime bytecodes
0x6060604052600080fd00a165627a7a72305820c23d3ae2dc86ad130561a2829d87c7cb8435365492bd1548eb7e7fc0f3632be90029

GET /accounts/{address}/storage/{key}

Summary:
Retrieve account storage value for given key.
Parameters
Parameter
Type
Required
Description
Example
address
string
Yes
address of account
0x5034aa590125b64023a0262112b98d72e3c8e40e
key
string
Yes
the key(position) to access account storage
0x0000000000000000000000000000000000000000000000000000000000000001
revision
string
Optional
can be block number or id (best block is assumed if omitted).
3877527 (block# 3877527) 0x003b2a97095a93d92b8dd45db88f0f90beaec398717ffd1d356b519c35ead4d0 (block#3877527 ID)
Responses
  • Curl
curl -X GET "https://sync-testnet.vechain.org/accounts/0x5034aa590125b64023a0262112b98d72e3c8e40e/storage/0x0000000000000000000000000000000000000000000000000000000000000001" -H "accept: application/json"
  • Request URL
https://sync-testnet.vechain.org/accounts/0x5034aa590125b64023a0262112b98d72e3c8e40e/storage/0x0000000000000000000000000000000000000000000000000000000000000001
Code
Description
200
OK
Response Body
{
"value": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
Related Model :
Storage
Name
Type
Description
Example
value
string
account storage value
0x0000000000000000000000000000000000000000000000000000000000000001

Transaction

Access to transactions

GET /transactions/{id}

Summary:
by ID. When pending is true, a pending tx with null meta might be returned.
Parameters
Parameter
Type
Required
Description
Example
id
string
Yes
ID of transaction
0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a
raw
boolean
Optional
whether retrieve a raw transaction
true or false. false is assumed if omitted
head
string
Optional
ID of head block. best block is assumed if omitted
0x003dc697f70205861a70fd3e52a24a542613b564bf6d8b7b4149c6b3ee6e015d
pending
boolean
Optional
whether to return tx, even it's pending
true or false
Responses
  • Curl
// raw = true
curl -X GET "https://sync-testnet.vechain.org/transactions/0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a?raw=true" -H "accept: application/json"
// pending = true
curl -X GET "https://sync-testnet.vechain.org/transactions/0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a?pending=true" -H "accept: application/json"
  • Request URL
// raw = true
https://sync-testnet.vechain.org/transactions/0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a?raw=true
// pending = true
https://sync-testnet.vechain.org/transactions/0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a?pending=true
Code
Description
200
OK
Response Body
// raw = false ; when pending = true it will return empty meta
{
"id": "0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a",
"chainTag": 39,
"blockRef": "0x003dc6957dcea347",
"expiration": 32,
"clauses": [
{
"to": "0xf2e7617c45c42967fde0514b5aa6bba56e3e11dd",
"value": "0x1b1ae4d6e2ef500000",
"data": "0x"
},
{
"to": "0x0000000000000000000000000000456e65726779",
"value": "0x0",
"data": "0xa9059cbb000000000000000000000000f2e7617c45c42967fde0514b5aa6bba56e3e11dd00000000000000000000000000000000000000000000010f0cf064dd59200000"
}
],
"gasPriceCoef": 255,
"gas": 100000,
"origin": "0x4f6fc409e152d33843cf4982d414c1dd0879277e",
"delegator": null,
"nonce": "0xf2ed7cd2567c6dd4",
"dependsOn": null,
"size": 225,
"meta": {
"blockID": "0x003dc696cfdf49b068b8e5c0b31f0c8a1d604ca1def69f5505f6e05db882f9d0",
"blockNumber": 4048534,
"blockTimestamp": 1570514180
}
}
//raw = true ; when pending = true it will return empty meta
{
"raw": "0xf8df27873dc6957dcea34720f87fe094f2e7617c45c42967fde0514b5aa6bba56e3e11dd891b1ae4d6e2ef50000080f85c940000000000000000000000000000456e6572677980b844a9059cbb000000000000000000000000f2e7617c45c42967fde0514b5aa6bba56e3e11dd00000000000000000000000000000000000000000000010f0cf064dd5920000081ff830186a08088f2ed7cd2567c6dd4c0b841de30c83b6d9200a9e0d0c2c25e4344c1867160057aafff4d4e10bee67d355f4b4222cefa6a70dcd336c48b1dbc42e9ac9bdbfb801416c519dedecd359cdd7b2300",
"meta": {
"blockID": "0x003dc696cfdf49b068b8e5c0b31f0c8a1d604ca1def69f5505f6e05db882f9d0",
"blockNumber": 4048534,
"blockTimestamp": 1570514180
}
}
Related Models :
TxWithMeta
Clause
TxMeta
rawTx
Name
Type
Description
Example
id
string
identifier of the transaction
0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477
origin
string
the one who signed the transaction
0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d
delegator
string
the delegator who paid the gas fee
null
size
integer(uint32)
byte size of the transaction that is RLP encoded
130
chainTag
integer (uint8)
last byte of genesis block ID
39
blockRef
string
8 bytes prefix of some block ID
0x0004f6cb730dbd90
expiration
integer (uint32)
expiration relative to blockRef, in unit block
720
clauses
[Clause]
an array of Clause objects each of which contains fields To, Value and Data
gasPriceCoef
integer (uint8)
coefficient used to calculate the final gas price
0
gas
integer (uint64)
max amount of gas can be consumed to execute this transaction
21000
dependsOn
string (bytes32)
ID of the transaction on which the current transaction depends on. can be null.
null
nonce
string
random nonce
0x29c257e36ea6e72a
meta
{TxMeta}
transaction meta info
Name
Type
Description
Example
to
string
recipient of clause, null for contract deployment (bytes32)
0x5034aa590125b64023a0262112b98d72e3c8e40e
value
string
hex form of token to be transferred
0x47fdb3c3f456c0000
data
string
input data(bytes)
0x
Name
Type
Description
Example
blockID
string
block identifier (bytes32)
0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215
blockNumber
integer(uint32)
block number (height)
325324
blockTimestamp
integer(uint64)
block unix timestamp
1533267900
Name
Type
Description
Example
raw
string
hex form of encoded transaction
0xf86981ba800adad994000000000000000000000000000000000000746f82271080018252088001c0b8414792c9439594098323900e6470742cd877ec9f9906bca05510e421f3b013ed221324e77ca10d3466b32b1800c72e12719b213f1d4c370305399dd27af962626400

GET /transactions/{id}/receipt

Summary:
Retrieve transaction receipt by ID.
Parameters
Parameter
Type
Required
Description
Example
id
string
Yes
ID of transaction
0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477
head
string
Optional
ID of head block. best block is assumed if omitted
0x003dc697f70205861a70fd3e52a24a542613b564bf6d8b7b4149c6b3ee6e015d
Responses
  • Curl
curl -X GET "https://sync-testnet.vechain.org/transactions/0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a/receipt" -H "accept: application/json"
  • Request URL
https://sync-testnet.vechain.org/transactions/0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a/receipt
Code
Description
200
OK
Response Body
{
"gasUsed": 52646,
"gasPayer": "0x4f6fc409e152d33843cf4982d414c1dd0879277e",
"paid": "0x5b53854239a6e0000",
"reward": "0x1b65db2d77b210000",
"reverted": false,
"meta": {
"blockID": "0x003dc696cfdf49b068b8e5c0b31f0c8a1d604ca1def69f5505f6e05db882f9d0",
"blockNumber": 4048534,
"blockTimestamp": 1570514180,
"txID": "0xc61b01eae38e5511e5104656f553e1cc350847716cf090f70ff6a0410ac5d85a",
"txOrigin": "0x4f6fc409e152d33843cf4982d414c1dd0879277e"
},
"outputs": [
{
"contractAddress": null,
"events": [],
"transfers": [
{
"sender": "0x4f6fc409e152d33843cf4982d414c1dd0879277e",
"recipient": "0xf2e7617c45c42967fde0514b5aa6bba56e3e11dd",
"amount": "0x1b1ae4d6e2ef500000"
}
]
},
{
"contractAddress": null,
"events": [
{
"address": "0x0000000000000000000000000000456e65726779",
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x0000000000000000000000004f6fc409e152d33843cf4982d414c1dd0879277e",
"0x000000000000000000000000f2e7617c45c42967fde0514b5aa6bba56e3e11dd"
],
"data": "0x00000000000000000000000000000000000000000000010f0cf064dd59200000"
}
],
"transfers": []
}
]
}
Related Models :
Receipt
ReceiptMeta
Outputs
Event
Transfer
Name
Type
Description
Example
gasUsed
integer (uint64)
gas used during execution
21000
gasPayer
string
address of account who paid used gas
0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d
paid
string
hex form of amount of paid energy
0x1236efcbcbb340000
reward
string
hex form of amount of reward
0x576e189f04f60000
reverted
boolean
true means the transaction was reverted
false
output
array
include event output data and transfer ouput data
see more in outputs
meta
receiptMeta
includes blockID,blockNumber,blockTimestamp,txID and txOrigin
Name
Type
Description
Example
blockID
string
block identifier (bytes32)
0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215
blockNumber
integer(uint32)
block number (height)
325324
blockTimestamp
integer(uint64)
block unix timestamp
1533267900
txID
string
transaction identifier
0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477
txOrigin
string
transaction origin(signer)
0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d
Name
Type
Description
Example
contractAddress
string
deployed contract address, if the corresponding clause is a contract deployment clause
null
events
event
event output
see more in event
transfers
transfer
transfer output
see more in transfer
Name
Type
Description
Example
address
string
the address of contract which produces the event (bytes20)
0x7567d83b7b8d80addcb281a71d54fc7b3364ffed
topics
[string]
[0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8]
data
string
0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8
Name
Type
Description
Example
sender
string
address that sends tokens
0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d
recipient
string
address that receives tokens
0x5034aa590125b64023a0262112b98d72e3c8e40e
amount
string
amount of tokens
0x47fdb3c3f456c0000

POST /transactions

Summary:
Use this method to commit transaction in raw.
Request body
Name
Type
Description
Example
raw
string
hex form of encoded transaction
0xf86981ba800adad994000000000000000000000000000000000000746f82271080018252088001c0b8414792c9439594098323900e6470742cd877ec9f9906bca05510e421f3b013ed221324e77ca10d3466b32b1800c72e12719b213f1d4c370305399dd27af962626400
Related Model :
rawTx
Name
Type
Description
Example
raw
string
hex form of encoded transaction
0xf86981ba800adad994000000000000000000000000000000000000746f82271080018252088001c0b8414792c9439594098323900e6470742cd877ec9f9906bca05510e421f3b013ed221324e77ca10d3466b32b1800c72e12719b213f1d4c370305399dd27af962626400
Responses
  • Curl
curl -X POST "https://sync-testnet.vechain.org/transactions" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"raw\":\"0xf87c278743b11e180ba16912dfde94f2e7617c45c42967fde0514b5aa6bba56e3e11dd872386f26fc1000080808252088088dd0e2a8c3986a7c5c0b841b610b19940246633b63b4f8cb8abdf10ea4086e5649cbf3554829ad4458f12a717b0840bcab1d30f83148a001d8cffab11fea7ac4a21b02ee00e6a0479d03f0401\"}"
  • Request URL
https://sync-testnet.vechain.org/transactions
Code
Description
200
OK
Response Body
{
"id": "0x605f10b7fea015db47c21bcc4d85578a621e88b1e8442644c8765b93439a6069"
}
Related Model :
TxID
Name
Type
Description
Example
id
string
identifier of the transaction
0x605f10b7fea015db47c21bcc4d85578a621e88b1e8442644c8765b93439a6069

Blocks

Access to blocks

GET /blocks/{revision}

Summary:
by ID or number, or 'best' for latest block or 'finalized' for finalized block. If expanded query option is true, all transactions along with their receipts will be embedded under transactions field instead of ids.
Parameters
Parameter
Type
Required
Description
Example
revision
string
required
'best' for latest block; 'finalized' for finalized block;block ID or block number
best (latest block ) finalized (finalized block) 3877527 (block# 3877527) 0x003b2a97095a93d92b8dd45db88f0f90beaec398717ffd1d356b519c35ead4d0 (block#3877527 ID)
expanded
boolean
optional
whether the returned block is expanded.
true or false
Responses
  • Curl
//expanded = false
curl -X GET "https://sync-testnet.vechain.org/blocks/best" -H "accept: application/json"
//expanded = true
curl -X GET "https://sync-testnet.vechain.org/blocks/best?expanded=true" -H "accept: application/json"
  • Request URL
//expanded = false
https://sync-testnet.vechain.org/blocks/best
//expanded = true
https://sync-testnet.vechain.org/blocks/best?expanded=true
Code