Smart contract queries

Call read-only smart contract functions (view functions) without submitting a transaction. The Gateway routes the query to the shard hosting the smart contract.

VM query endpoints

Method	Path	Returns
POST	`/vm-values/query`	Full VM response (all return data, gasUsed, returnCode)
POST	`/vm-values/hex`	First return value as hex string
POST	`/vm-values/string`	First return value as UTF-8 string
POST	`/vm-values/int`	First return value as decimal big-integer string

Request body

{
  "scAddress": "erd1qqqqqqqqqqqqqpgq...",
  "funcName": "getBalance",
  "args": ["hex-encoded-arg1", "hex-encoded-arg2"],
  "caller": "erd1...",
  "value": "0"
}

Field	Type	Required	Description
`scAddress`	string	yes	Bech32 address of the smart contract
`funcName`	string	yes	View function name
`args`	string[]	no	Hex-encoded arguments
`caller`	string	no	Simulated caller address
`value`	string	no	Simulated EGLD value sent

Arguments must be hex-encoded. To pass the number 100, encode it as "64" (hex representation of 100).

Choose the right endpoint

/vm-values/query: returns the full response (multiple return values, gas used, return code).
/vm-values/hex: returns raw bytes (e.g., reading a storage mapper).
/vm-values/string: returns string data (e.g., token names).
/vm-values/int: returns numeric values (e.g., balances, counters).

Read a token balance from a smart contract

cURL
TypeScript
Python
Rust

curl -X POST "https://rust-gateway.xoxno.com/vm-values/int" \
  -H "Content-Type: application/json" \
  -d '{
    "scAddress": "erd1qqqqqqqqqqqqqpgqfzydqmdw7m2vazsp6u5p95yxz76t2p9rd8ss0zp9ts",
    "funcName": "getBalance",
    "args": ["b13a017423c366caff8cecfb77a12610a130f4888134122c7937feae0d6d7d4e"]
  }'

const res = await fetch("https://rust-gateway.xoxno.com/vm-values/int", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    scAddress: "erd1qqqqqqqqqqqqqpgqfzydqmdw7m2vazsp6u5p95yxz76t2p9rd8ss0zp9ts",
    funcName: "getBalance",
    args: ["b13a017423c366caff8cecfb77a12610a130f4888134122c7937feae0d6d7d4e"],
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://rust-gateway.xoxno.com/vm-values/int",
    json={
        "scAddress": "erd1qqqqqqqqqqqqqpgqfzydqmdw7m2vazsp6u5p95yxz76t2p9rd8ss0zp9ts",
        "funcName": "getBalance",
        "args": ["b13a017423c366caff8cecfb77a12610a130f4888134122c7937feae0d6d7d4e"],
    },
)
print(res.json())

let body: serde_json::Value = reqwest::Client::new()
    .post("https://rust-gateway.xoxno.com/vm-values/int")
    .json(&serde_json::json!({
        "scAddress": "erd1qqqqqqqqqqqqqpgqfzydqmdw7m2vazsp6u5p95yxz76t2p9rd8ss0zp9ts",
        "funcName": "getBalance",
        "args": ["b13a017423c366caff8cecfb77a12610a130f4888134122c7937feae0d6d7d4e"]
    }))
    .send()
    .await?
    .json()
    .await?;

println!("{body:#?}");

Historical queries

Add ?blockNonce=12345678 or ?blockHash=abcdef... to query VM state at a specific block.

POST /vm-values/int?blockNonce=12345678

Historical VM queries require full-history observer nodes. The Gateway routes to full-history observers when block parameters are present.

​VM query endpoints

​Request body

​Choose the right endpoint

​Read a token balance from a smart contract

​Historical queries

VM query endpoints

Request body

Choose the right endpoint

Read a token balance from a smart contract

Historical queries