# Thorest API 1.3.2

RESTful API to access VeChain Thor Network

License: LGPL 3.0 (opens new window)

# 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

Name	Type	Description
batchCallResult	[callResult]	return batch call result

CallResult

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

Event

Name	Type	Description	Example
address	string	the address of contract which produces the event (bytes20)	0x7567d83b7b8d80addcb281a71d54fc7b3364ffed
topics	[string]		[0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8]
data	string		0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8

Transfer

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

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

Clause

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

TxMeta

Name	Type	Description	Example
blockID	string	block identifier (bytes32)	0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215
blockNumber	integer(uint32)	block number (height)	325324
blockTimestamp	integer(uint64)	block unix timestamp	1533267900

rawTx

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

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`

ReceiptMeta

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

Outputs

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

Event

Name	Type	Description	Example
address	string	the address of contract which produces the event (bytes20)	0x7567d83b7b8d80addcb281a71d54fc7b3364ffed
topics	[string]		[0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8]
data	string		0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8

Transfer

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. 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	block ID or number, or 'best' stands for latest block	`best` (latest 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	Description
200	OK

# Response Body


{
  "number": 325324,
  "id": "0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215",
  "size": 373,
  "parentID": "0x0004f6cb730dbd90fed09d165bfdf33cc0eed47ec068938f6ee7b7c12a4ea98d",
  "timestamp": 1533267900,
  "gasLimit": 11253579,
  "beneficiary": "0xb4094c25f86d628fdd571afc4077f0d0196afb48",
  "gasUsed": 21000,
  "totalScore": 1029988,
  "txsRoot": "0x89dfd9fcd10c9e53d68592cf8b540b280b72d381b868523223992f3e09a806bb",
  "txsFeatures": 0,
  "stateRoot": "0x86bcc6d214bc9d8d0dedba1012a63c8317d19ce97f60c8a2ef5c59bbd40d4261",
  "receiptsRoot": "0x15787e2533c470e8a688e6cd17a1ee12d8457778d5f82d2c109e2d6226d8e54e",
  "signer": "0xab7b27fc9e7d29f9f2e5bd361747a5515d0cc2d1",
  "isTrunk": true,
  "transactions": [
    "0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477"
  ]
}

Code	Description
200	OK

Related Models :

Block

Name	Type	Description	Example
number	integer(uint32)	block number (height)	325324
id	string(bytes32)	block identifier	0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215
size	integer(uint32)	RLP encoded block size in bytes	373
parentID	string(bytes32)	parent block ID	0x0004f6cb730dbd90fed09d165bfdf33cc0eed47ec068938f6ee7b7c12a4ea98d
timestamp	integer(uint64)	block unix timestamp	1533267900
gasLimit	integer(uint64)	block gas limit (max allowed accumulative gas usage of transactions)	11253579
beneficiary	string(bytes32)	address of account to receive block reward	0xb4094c25f86d628fdd571afc4077f0d0196afb48
gasUsed	integer(uint64)	accumulative gas usage of transactions	21000
totalScore	integer(uint64)	sum of all ancestral blocks' score	1029988
txsRoot	string(bytes32)	root hash of transactions in the block	0x89dfd9fcd10c9e53d68592cf8b540b280b72d381b868523223992f3e09a806bb
txsFeatures	integer(uint32)	supported txs features bitset	0
stateRoot	string(byte32)	root hash of accounts state	0x86bcc6d214bc9d8d0dedba1012a63c8317d19ce97f60c8a2ef5c59bbd40d4261
receiptsRoot	string(byte32)	root hash of transaction receipts	0x15787e2533c470e8a688e6cd17a1ee12d8457778d5f82d2c109e2d6226d8e54e
signer	string(byte20)	the one who signed this block	0xab7b27fc9e7d29f9f2e5bd361747a5515d0cc2d1
transactions	array	transaction IDs	[0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477]
isTrunk	boolean	whether the block is on the trunk	`true` or `false`. if it is `false`, the block is branch block

TxWithReceipt

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
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 output data	see more in outputs

Clause

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

Outputs

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

Event

Name	Type	Description	Example
address	string	the address of contract which produces the event (bytes20)	0x7567d83b7b8d80addcb281a71d54fc7b3364ffed
topics	[string]		[0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8]
data	string		0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8

Transfer

Name	Type	Description	Example
sender	string	address that sends tokens	0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d
recipient	string	address that receives tokens	0x5034aa590125b64023a0262112b98d72e3c8e40e
amount	string	amount of tokens	0x47fdb3c3f456c0000

# Logs

Access to event & transfer logs

# POST /logs/event

# Summary:

Filter event logs Event logs are produced by OP_LOG in EVM.

# Request body

{
  "range": {
    "unit": "block",
    "from": 0,
    "to": 100000
  },
  "options": {
    "offset": 0,
    "limit": 10
  },
  "criteriaSet": [
    {
      "address": "0x0000000000000000000000000000456E65726779",
      "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "topic1": "0x0000000000000000000000005034aa590125b64023a0262112b98d72e3c8e40e"
    }
  ],
  "order": "asc"
}

Relate Models :

EventFilter

Name	Type	Description
range	FilterRange	Defines the filter range
options	FilterOptions	Define the filter option
criteriaSet	[EventCriteria]	Set criteria to filter
order	string	order of filters, defaults to `asc` (`asc` or `desc`)

EventCriteria

criteria to filter out event. All fields are joined with and operator. null field are ignored. e.g.

{
  "address": "0x0000000000000000000000000000456E65726779",
  "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
}

matches events emitted by 0xe59d475abe695c7f67a8a2321f33a856b0b4c71d and with topic0 equals 0xddf252ad1be2c89b…523b3ef.

Name	Type	Description
address	string	address of event emitter
topic0	string
topic1	string
topic2	string
topic3	string
topic4	string

FilterRange

defines the range to filter in. e.g.

{
  "range": {
    "unit": "block",
    "from": 10,
    "to": 1000
  }
}

refers to the range from block 10 to block 1000. null stands for the full range.

Name	Type	Description	Example
unit	string	defines the unit of `from` and `to`. `block` means block number, `time` means block timestamp, default to `block` .	block
from	integer (uint64)	indicating the start point	0
to	integer (uint64)	indicating the end point	1000

FilterOptions

pass these parameters if you need filtered results paged. e.g.

{
  "options": {
    "offset": 0,
    "limit": 10   
  }
}

the above refers that page offset is 0, and the page size is 10. pass options null if you don't need to demand paging.

Name	Type	Description	Example
offset	integer	offset in matched record set	0
limit	integer	limit of records to output	10

# Responses

Curl

curl -X POST "https://sync-testnet.vechain.org/logs/event" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"range\":{\"unit\":\"block\",\"from\":0,\"to\":100000},\"options\":{\"offset\":0,\"limit\":10},\"criteriaSet\":[{\"address\":\"0x0000000000000000000000000000456E65726779\",\"topic0\":\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"topic1\":\"0x0000000000000000000000005034aa590125b64023a0262112b98d72e3c8e40e\"}],\"order\":\"asc\"}"

Request URL

https://sync-testnet.vechain.org/logs/event

Code	Description
200	OK

# Response Body

[ 
   { 
      "address":"0x0000000000000000000000000000456e65726779",
      "topics":[ 
         "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
         "0x0000000000000000000000005034aa590125b64023a0262112b98d72e3c8e40e",
         "0x0000000000000000000000005034aa590125b64023a0262112b98d72e3c8e40e"
      ],
      "data":"0x00000000000000000000000000000000000000000000124bc0ddd92e55fff280",
      "meta":{ 
         "blockID":"0x000060716a6decc7127d221e8a53cd7b33992db6236490f79d47585f9ae7ca14",
         "blockNumber":24689,
         "blockTimestamp":1530261290,
         "txID":"0x0ee8df3a9de6787ec0848ea8951ed8899bb053b6b4af167228dd7c0c012f5346",
         "txOrigin":"0x5034aa590125b64023a0262112b98d72e3c8e40e",
         "clauseIndex":0
      }
   },
   { 
      ........
   },   
   { 
      "address":"0x0000000000000000000000000000456e65726779",
      "topics":[ 
         "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
         "0x0000000000000000000000005034aa590125b64023a0262112b98d72e3c8e40e",
         "0x000000000000000000000000ebdb7c7bd6b46e9611101057e5b98a89697d38a7"
      ],
      "data":"0x00000000000000000000000000000000000000000000180863c9a3f1c3a40000",
      "meta":{ 
         "blockID":"0x000089c7b155093311a0ab543f46f2f52f83ca87cbfb04c26507ad134f25f6d2",
         "blockNumber":35271,
         "blockTimestamp":1530367110,
         "txID":"0x7234d0e34abe1e7e612fcd3aae108087ef5d85707333afecfa24b5ad31a7a4aa",
         "txOrigin":"0x5034aa590125b64023a0262112b98d72e3c8e40e",
         "clauseIndex":1
      }
   }
]

# POST /logs/transfer

# Summary:

Filter transfer logs which are recorded on VET transferring.

# Request body

{
  "range": {
    "unit": "block",
    "from": 0,
    "to": 100000
  },
  "options": {
    "offset": 0,
    "limit": 10
  },
  "criteriaSet": [
    {
      "txOrigin": "0xe59d475abe695c7f67a8a2321f33a856b0b4c71d",
      "sender": "0xe59d475abe695c7f67a8a2321f33a856b0b4c71d",
      "recipient": "0x7567d83b7b8d80addcb281a71d54fc7b3364ffed"
    }
  ],
  "order": "asc"
}

Relate Models :

TransferFilter

Name	Type	Description
range	FilterRange	Defines the filter range
options	FilterOptions	Define the filter option
criteriaSet	[TransferCriteria]	Set criteria to filter
order	string	order of filters, defaults to `asc` (`asc` or `desc`)

TransferCriteria

Name	Type	Example
txOrigin	string	0xe59d475abe695c7f67a8a2321f33a856b0b4c71d
sender	string	0xe59d475abe695c7f67a8a2321f33a856b0b4c71d
recipient	string	0x7567d83b7b8d80addcb281a71d54fc7b3364ffed

FilterRange

defines the range to filter in. e.g.

{
  "range": {
    "unit": "block",
    "from": 10,
    "to": 1000
  }
}

refers to the range from block 10 to block 1000. null stands for the full range.

Name	Type	Description	Example
unit	string	defines the unit of `from` and `to`. `block` means block number, `time` means block timestamp, default to `block` .	block
from	integer (uint64)	indicating the start point	0
to	integer (uint64)	indicating the end point	1000

FilterOptions

pass these parameters if you need filtered results paged. e.g.

{
  "options": {
    "offset": 0,
    "limit": 10   
  }
}

the above refers that page offset is 0, and the page size is 10. pass options null if you don't need to demand paging.

Name	Type	Description	Example
offset	integer	offset in matched record set	0
limit	integer	limit of records to output	10

# Responses

Curl

curl -X POST "https://sync-testnet.vechain.org/logs/transfer" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"range\":{\"unit\":\"block\",\"from\":0,\"to\":100000},\"options\":{\"offset\":0,\"limit\":10},\"criteriaSet\":[{\"txOrigin\":\"0xe59d475abe695c7f67a8a2321f33a856b0b4c71d\",\"sender\":\"0xe59d475abe695c7f67a8a2321f33a856b0b4c71d\",\"recipient\":\"0x7567d83b7b8d80addcb281a71d54fc7b3364ffed\"}],\"order\":\"asc\"}"

Request URL

https://sync-testnet.vechain.org/logs/transfer

Code	Description
200	OK

# Response Body

[
  {
    "sender": "0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d",
    "recipient": "0x5034aa590125b64023a0262112b98d72e3c8e40e",
    "amount": "0x47fdb3c3f456c0000",
    "meta": {
      "blockID": "0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215",
      "blockNumber": 325324,
      "blockTimestamp": 1533267900,
      "txID": "0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477",
      "txOrigin": "0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d",
      "clauseIndex": 0
    }
  }
]

# Node

Access to node status info

# GET /node/network/peers

# Summary:

Retrieve connected peers

# Responses

Curl

curl -X GET "https://sync-testnet.vechain.org/node/network/peers" -H "accept: application/json"

Request URL

https://sync-testnet.vechain.org/node/network/peers

Code	Description
200	OK

# Response Body

[
  {
    "name": "thor/v1.1.3-48c1764-dev/linux/go1.11.5",
    "bestBlockID": "0x003b2e48a9973803462b9e1f90bb7dd03c01f4c7c99f75374c95a23826312a53",
    "totalScore": 375388137,
    "peerID": "a6607628a9ba139aaf5ccc4959c7faad52c6512da65276817eb6ee1f8387a2176f75f02eb9dc11e71168edc0e15a9e2050576b5f30fc18ad13c8dda4d94b62ec",
    "netAddr": "117.50.5.155:42896",
    "inbound": true,
    "duration": 413
  },
  {
    "name": "thor/v1.1.3-48c1764-dev/linux/go1.11.5",
    "bestBlockID": "0x003b2e63b4031966a4364d96d9ca8d1b89e7b6ededd5082778bac43cae4d4f3e",
    "totalScore": 375390675,
    "peerID": "ee6c337416d080aed6aa78380d6f5da4ac9e90df3c1f1c7188aed9f9ef64d18d82c558ac50d0c53220db682874d010fe42dfaca5ad2ff7d876f25f76a8ab702b",
    "netAddr": "128.1.35.68:11235",
    "inbound": false,
    "duration": 53232
  },
  {
   ........
   }
]

Related Model :

PeerStats

Name	Type	Example
name	string	thor/v1.0.0-6680b98-dev/linux/go1.10.3
bestBlockID	string	0x000087b3a4d4cdf1cc52d56b9704f4c18f020e1b48dbbf4a23d1ee4f1fa5ff94
totalScore	integer	68497
peerID	string	50e122a505ee55b84331068acfd857e37ad58f463a0fab9aaff2c1e4b2e2d22ae71dc14fdaf6eead74bd3f60594644aa35c588f9ca6be3341e2ce18ddc413321
netAddr	string	128.1.39.120:11235
inbound	boolean	false
duration	integer	28

# Subscriptions

subscribe interested subject

# GET /subscriptions/block

# Summary:

(Websocket) Subscribe new blocks

# Parameters

Parameter	Type	Required	Description	Example
pos	string	Optional	a saved block ID for resuming the subscription. best block ID is assumed if omitted.

# Responses

Code	Description
200	OK

# Response Body

{
  "number": 325324,
  "id": "0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215",
  "size": 373,
  "parentID": "0x0004f6cb730dbd90fed09d165bfdf33cc0eed47ec068938f6ee7b7c12a4ea98d",
  "timestamp": 1533267900,
  "gasLimit": 11253579,
  "beneficiary": "0xb4094c25f86d628fdd571afc4077f0d0196afb48",
  "gasUsed": 21000,
  "totalScore": 1029988,
  "txsRoot": "0x89dfd9fcd10c9e53d68592cf8b540b280b72d381b868523223992f3e09a806bb",
  "txsFeatures": 0,
  "stateRoot": "0x86bcc6d214bc9d8d0dedba1012a63c8317d19ce97f60c8a2ef5c59bbd40d4261",
  "receiptsRoot": "0x15787e2533c470e8a688e6cd17a1ee12d8457778d5f82d2c109e2d6226d8e54e",
  "signer": "0xab7b27fc9e7d29f9f2e5bd361747a5515d0cc2d1",
  "transactions": [
    "0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477"
  ],
  "obsolete": true
}

Related Model :

BlockSubscriptions

Name	Type	Description	Example
number	integer(uint32)	block number (height)	325324
id	string(bytes32)	block identifier	0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215
size	integer(uint32)	RLP encoded block size in bytes	373
parentID	string(bytes32)	parent block ID	0x0004f6cb730dbd90fed09d165bfdf33cc0eed47ec068938f6ee7b7c12a4ea98d
timestamp	integer(uint64)	block unix timestamp	1533267900
gasLimit	integer(uint64)	block gas limit (max allowed accumulative gas usage of transactions)	11253579
beneficiary	string(bytes32)	address of account to receive block reward	0xb4094c25f86d628fdd571afc4077f0d0196afb48
gasUsed	integer(uint64)	accumulative gas usage of transactions	21000
totalScore	integer(uint64)	sum of all ancestral blocks' score	1029988
txsRoot	string(bytes32)	root hash of transactions in the block	0x89dfd9fcd10c9e53d68592cf8b540b280b72d381b868523223992f3e09a806bb
txsFeatures	integer(uint32)	supported txs features bitset	0
stateRoot	string(byte32)	root hash of accounts state	0x86bcc6d214bc9d8d0dedba1012a63c8317d19ce97f60c8a2ef5c59bbd40d4261
receiptsRoot	string(byte32)	root hash of transaction receipts	0x15787e2533c470e8a688e6cd17a1ee12d8457778d5f82d2c109e2d6226d8e54e
signer	string(byte20)	the one who signed this block	0xab7b27fc9e7d29f9f2e5bd361747a5515d0cc2d1
transactions	array	transaction IDs	[0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477]
obsolete	boolean	indicates whether the block containing this data become branch block	`true` or `false`. if it is `false`, the block is branch block

# GET /subscriptions/event

# Summary:

(Websocket) Subscribe new events which satisfy criteria in query.

# Parameters

Parameter	Type	Required	Description
pos	string	Optional	a saved block ID for resuming the subscription. best block ID is assumed if omitted.
addr	string	Optional	address of event emitter
t0	string	Optinal	topic0 of event
t1	string	Optinal	topic1 of event
t2	string	Optinal	topic2 of event
t3	string	Optinal	topic3 of event
t4	string	Optinal	topic4 of event

# Responses

Code	Description
200	OK

# Response Body

{
  "address": "0x7567d83b7b8d80addcb281a71d54fc7b3364ffed",
  "topics": [
    "0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8"
  ],
  "data": "0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8",
  "obsolete": true,
  "meta": {
    "blockID": "0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215",
    "blockNumber": 325324,
    "blockTimestamp": 1533267900,
    "txID": "0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477",
    "txOrigin": "0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d",
    "clauseIndex": 0
  }
}

Related Models :

eventSubscriptions

Name	Type	Description	Example
address	string	the address of contract which produces the event (bytes20)	0x7567d83b7b8d80addcb281a71d54fc7b3364ffed
topics	[string]		[0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8]
data	string		0x4de71f2d588aa8a1ea00fe8312d92966da424d9939a511fc0be81e65fad52af8
obsolete	boolean	indicates whether the block containing this data become branch block	false
meta	LogMeta	event or transfer log meta info

LogMeta

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
clauseIndex	integer(uint32)	index of clause which generates this log	0

# GET /subscriptions/transfer

# Summary:

(Websocket) Subscribe new transfers which satisfy criteria in query.

# Parameters

Parameter	Type	Required	Description
pos	string	Optional	a saved block ID for resuming the subscription. best block ID is assumed if omitted.
txOrigin	string	Optional	signer address of tx which contains the transfer
sender	string	Optional	address of token sender
recipient	string	Optional	address of token recipient

# Responses

Code	Description
200	OK

# Response Body

{
  "sender": "0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d",
  "recipient": "0x5034aa590125b64023a0262112b98d72e3c8e40e",
  "amount": "0x47fdb3c3f456c0000",
  "obsolete": true,
  "meta": {
    "blockID": "0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215",
    "blockNumber": 325324,
    "blockTimestamp": 1533267900,
    "txID": "0x284bba50ef777889ff1a367ed0b38d5e5626714477c40de38d71cedd6f9fa477",
    "txOrigin": "0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d",
    "clauseIndex": 0
  }
}

Related Models :

TransferSubscriptions

Name	Type	Description	Example
sender	string	address that sends tokens	0xdb4027477b2a8fe4c83c6dafe7f86678bb1b8a8d
recipient	string	address that receives tokens	0x5034aa590125b64023a0262112b98d72e3c8e40e
amount	string	amount of tokens	0x47fdb3c3f456c0000
obsolete	boolean	indicates whether the block containing this data become branch block	false
meta	LogMeta	event or transfer log meta info

LogMeta

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
clauseIndex	integer(uint32)	index of clause which generates this log	0

# GET /subscriptions/beat

# Summary:

(Websocket) Subscribe block chain's beats which contain summary of new blocks, and bloom filters that composited with affected addresses.

# Parameters

Parameter	Type	Required	Description	Example
pos	string	Optional	a saved block ID for resuming the subscription. best block ID is assumed if omitted.

# Responses

Code	Description
200	OK

# Response Body

{
  "number": 325324,
  "id": "0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215",
  "parentID": "0x0004f6cb730dbd90fed09d165bfdf33cc0eed47ec068938f6ee7b7c12a4ea98d",
  "timestamp": 1533267900,
  "txsFeatures": 0,
  "bloom": "0x000208001010800200c011000000020002040040008000100........02044020000000008000021000000000",
  "k": 3,
  "obsolete": true
}

Related Model :

Beat

Name	Type	Description	Example
number	integer (uint32)	block number (height)	325324
id	string (bytes32)	block identifier	0x0004f6cc88bb4626a92907718e82f255b8fa511453a78e8797eb8cea3393b215
parentID	string (bytes32)	parent block ID	0x0004f6cb730dbd90fed09d165bfdf33cc0eed47ec068938f6ee7b7c12a4ea98d
timestamp	integer (uint64)	block unix timestamp	1533267900
txsFeatures	integer (uint32)	supported txs features bitset	0
bloom	string (hex)	the bloom filter composited with affected addresses	0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
k	integer (uint32)	the number of hash functions for bloom filter	3

# Debug

Debug utilities

# POST /debug/tracers

# Summary:

Create a tracer for a clause

# Request body

{
  "name": "",
  "target": "0x000dabb4d6f0a80ad7ad7cd0e07a1f20b546db0730d869d5ccb0dd2a16e7595b/0/0"
}

Related Model :

TracerOption

Name	Type	Description	Example
name	string	name of tracer. Empty name stands for default struct logger tracer.	4byte, call, noop, prestate
target	string	the unified path of target to be traced. Currently, only clause is supported. Format: `blockID`/ (`txIndex` or `txId`)/ `clauseIndex`	0x000dabb4d6f0a80ad7ad7cd0e07a1f20b546db0730d869d5ccb0dd2a16e7595b

# Responses

Code	Description
200	OK

# POST /debug/storage-range

# Summary:

Retrieve storage range of the account with given address

# Request body

{
  "address": "0xa4627036e2095eb71c2341054daa63577c062498",
  "keyStart": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "maxResult": 10,
  "target": "0x000edefb448685f9c72fc2b946980ef51d8d208bbaa4d3fdcf0c57d4847aca2e/0/0"
}

Related Model :

storageRangeOption

Name	Type	Description	Example
address	string	address of account	0xa4627036e2095eb71c2341054daa63577c062498
keyStart	string		0x0000000000000000000000000000000000000000000000000000000000000000
maxResult	number		10
target	string		0x000edefb448685f9c72fc2b946980ef51d8d208bbaa4d3fdcf0c57d4847aca2e

# Responses

Code	Description
200	OK

# Response Body

{
  "nextKey": null,
  "storage": {
    "0x33e423980c9b37d048bd5fadbd4a2aeb95146922045405accc2f468d0ef96988": {
      "key": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "value": "0x00000000000000000000000000000000000000000000000000000000000000c8"
    }
  }
}

Related Model :

storageRange

Name	Type	Description	Example
nextKey	string		null
storage	object

← Custom Network