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

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)

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

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

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`

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
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