> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart contract queries

> Query smart contract view functions and read on-chain state through the VM.

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

```json theme={"system"}
{
  "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

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    curl -X POST "https://rust-gateway.xoxno.com/vm-values/int" \
      -H "Content-Type: application/json" \
      -d '{
        "scAddress": "erd1qqqqqqqqqqqqqpgqfzydqmdw7m2vazsp6u5p95yxz76t2p9rd8ss0zp9ts",
        "funcName": "getBalance",
        "args": ["b13a017423c366caff8cecfb77a12610a130f4888134122c7937feae0d6d7d4e"]
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

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

  <Tab title="Rust">
    ```rust theme={"system"}
    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:#?}");
    ```
  </Tab>
</Tabs>

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