States

A state is a variable or view that can change over time. A state is always the same at the same block height.

The Call-API provides access to state variables using a REST API.
The OpenAPI Documentation is available at https://vechain.energy/docs/api/call (opens in a new tab)

The example uses a public contract and calls a function with an argument.

Example Conditions

Source Code

The VTHO contract's source code is available on GitHub:
https://github.com/vechain/thor/blob/f58c17ae50f1ec8698d9daf6e05076d17dcafeaf/builtin/gen/energy.sol (opens in a new tab)

Contract address

The public VTHO contract is used. Address is identical on Test and MainNet.

0x0000000000000000000000000000456E65726779

ABI

Definition of the balanceOf that returns the VTHO balance for a given address.

{
    "constant": true,
    "inputs": [
        {
            "name": "_owner",
            "type": "address"
        }
    ],
    "name": "balanceOf",
    "outputs": [
        {
            "name": "balance",
            "type": "uint256"
        }
    ],
    "payable": false,
    "stateMutability": "view",
    "type": "function"
}

Function definition

function balanceOf(address _owner) public view returns(uint256 balance) {}

Connex Example

const result = await connex.thor
  .account(CONTRACT_ADDRESS)
  .method(abi)
  .call(address);
  
console.log(result.decoded.balance)

Reading a single variable with a GET-Request

With the GET-Request a quick access is given that supports a direct integration into existing web-applications. Several comfort functions like redirects and base64 decoding is available. Read the OpenAPI Documentation for more details (opens in a new tab).

The URL of the request is a combination of the network, contract address and function signature:

const ENDPOINT = 'https://call.api.vechain.energy'
const NETWORK = 'main'
const CONTRACT_ADDRESS = '0x0000000000000000000000000000456E65726779'
const ARG1_ADDRESS = '0x0000000000000000000000000000000000000000'
const FUNCTION_CALL = `balanceOf(address ${ARG1_ADDRESS}) public view returns(uint256 balance)`
 
const url = `${ENDPOINT}/${NETWORK}/${CONTRACT_ADDRESS}/${encodeURI(FUNCTION_CALL)}`
 
const result = await window.fetch(url)
const balance = await result.json()

Example Link:

https://api.vechain.energy/v1/call/main/0x0000000000000000000000000000456E65726779/balanceOf(address%200x0000000000000000000000000000000000000000)%20public%20view%20returns(uint256%20balance) (opens in a new tab)

curl

curl 'https://api.vechain.energy/v1/callmain/0x0000000000000000000000000000456E65726779/balanceOf(address%200x0000000000000000000000000000000000000000)%20public%20view%20returns(uint256%20balance)'

Endpoint

https://vechain.energy/docs/api/call (opens in a new tab)

Reading a structure with a GET-Request

A struct contains multiple attributes that are assigned to a single variable.

A signature needs to wrap the struct with ( and ).

For example https://github.com/vechain/b32/blob/0abac3a31290a01ecb94131ccb25b7fea3ad66f7/ABIs/vesea_profiles.json (opens in a new tab)

Its signature output will be:

… returns (profile(address profileAddress, string name, bool blacklisted, bool verified, bool payWithVSea, uint256 profileTypeId, address pfpContract, uint256 pfpTokenId, uint256 blockCreated))

The result is a list of values:

[
    "0x0000000000000000000000000000000000000000",
    "",
    false,
    false,
    false,
    "0",
    "0x0000000000000000000000000000000000000000",
    "0",
    "0"
]

Example-Link: https://api.vechain.energy/v1/call/main/0xdaeda865296CeE66dc6863f9e93751f00B3606Fb/getProfile%20(address%200xdaeda865296CeE66dc6863f9e93751f00B3606Fb)%20returns%20(profile(address%20profileAddress,%20string%20name,%20bool%20blacklisted,%20bool%20verified,%20bool%20payWithVSea,%20uint256%20profileTypeId,%20address%20pfpContract,%20uint256%20pfpTokenId,%20uint256%20blockCreated)) (opens in a new tab)

Reading multiple variables in one Request

Multiple states from different sources can be loaded. The request is always for a single network.

const ENDPOINT = 'https://api.vechain.energy/v1/call'
const NETWORK = 'main'
const CONTRACT_ADDRESS = '0x0000000000000000000000000000456E65726779'
const ARG1_ADDRESS = '0x0000000000000000000000000000000000000000'
const FUNCTION_CALL = `balanceOf(address ${ARG1_ADDRESS}) public view returns(uint256 balance)`
 
const url = `${ENDPOINT}/${NETWORK}`
const body = { clauses:
    [
        { to: CONTRACT_ADDRESS, signature: FUNCTION_CALL },
        { to: CONTRACT_ADDRESS, signature: FUNCTION_CALL }
    ] }
 
const result = await window.fetch(url, { method: 'POST', body: JSON.stringify(body) })
const balances = await result.json()

curl

curl 'https://api.vechain.energy/v1/call/main' \
  --data-raw '{"clauses":[{"to":"0x0000000000000000000000000000456E65726779","signature":"balanceOf(address 0x0000000000000000000000000000000000000000) public view returns(uint256 balance)"},{"to":"0x0000000000000000000000000000456E65726779","signature":"balanceOf(address 0x0000000000000000000000000000000000000000) public view returns(uint256 balance)"}]}'

Signature

The function signature is a comfort functionality to provide a human readable version that can be manually written. The signature is the function head with the parameters written instead of variable names.

There are some limits to this type that come especially with the complexity of lists. An alternative way of accessing data is using the ABI.

ABI

const ENDPOINT = 'https://api.vechain.energy/v1/call'
const NETWORK = 'main'
const CONTRACT_ADDRESS = '0x0000000000000000000000000000456E65726779'
const ARG1_ADDRESS = '0x0000000000000000000000000000000000000000'
const ABI = {
    "constant": true,
    "inputs": [
        { "name": "_owner", "type": "address" }
    ],
    "name": "balanceOf",
    "outputs": [
        { "name": "balance", "type": "uint256" }
    ],
    "payable": false,
    "stateMutability": "view",
    "type": "function"
}
 
const url = `${ENDPOINT}/${NETWORK}`
const body = { clauses:
    [
        { to: CONTRACT_ADDRESS, abi: ABI, args: [ARG1_ADDRESS] },
        { to: CONTRACT_ADDRESS, abi: ABI, args: [ARG1_ADDRESS] }
    ] }
 
const result = await window.fetch(url, { method: 'POST', body: JSON.stringify(body) })
const balances = await result.json()

curl

curl 'https://api.vechain.energy/v1/call/main' \
  --data-raw '{"clauses":[{"to":"0x0000000000000000000000000000456E65726779","abi":{"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"balanceOf","outputs":[{"name":"balance","type":"uint256"}],"payable":false,"stateMutability":"view","type":"function"},"args":["0x0000000000000000000000000000000000000000"]},{"to":"0x0000000000000000000000000000456E65726779","abi":{"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"balanceOf","outputs":[{"name":"balance","type":"uint256"}],"payable":false,"stateMutability":"view","type":"function"},"args":["0x0000000000000000000000000000000000000000"]}]}'

Endpoint Documentation

https://vechain.energy/docs/api/call (opens in a new tab)

Examples

Options Events & Logs