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

# Account queries

> Query MultiversX account, balance, token, NFT, guardian, and storage data through Gateway shard routing.

Use Gateway account endpoints to read MultiversX address state without choosing a shard observer.

## Base URL

```text theme={"system"}
https://rust-gateway.xoxno.com
```

Responses use the MultiversX Gateway body shape: `data`, `error`, and `code`.

## Endpoint Groups

| Need              | Endpoint                                                                                        |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| Full account      | `GET /address/{address}`                                                                        |
| Balance           | `GET /address/{address}/balance`                                                                |
| Nonce             | `GET /address/{address}/nonce`                                                                  |
| Username          | `GET /address/{address}/username`                                                               |
| Computed shard    | `GET /address/{address}/shard`                                                                  |
| Code hash         | `GET /address/{address}/code-hash`                                                              |
| Storage keys      | `GET /address/{address}/keys`, `GET /address/{address}/key/{key}`, `POST /address/iterate-keys` |
| ESDT and NFT data | `GET /address/{address}/esdt`, `GET /address/{address}/nft/{tokenIdentifier}/nonce/{nonce}`     |
| Guardian data     | `GET /address/{address}/guardian-data`                                                          |
| Bulk accounts     | `POST /address/bulk`                                                                            |

## Query Options

Most account endpoints accept historical state selectors:

| Param             | Use                                       |
| ----------------- | ----------------------------------------- |
| `onFinalBlock`    | Query latest finalized block.             |
| `onStartOfEpoch`  | Query state at an epoch start.            |
| `blockNonce`      | Query at a block nonce.                   |
| `blockHash`       | Query at a block hash.                    |
| `blockRootHash`   | Query at a state root.                    |
| `hintEpoch`       | Provide epoch hint for historical lookup. |
| `forced-shard-id` | Override automatic routing.               |

## Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://rust-gateway.xoxno.com/address/erd1..."
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    const address = "erd1...";
    const res = await fetch(`https://rust-gateway.xoxno.com/address/${address}`);
    if (!res.ok) throw new Error(`gateway failed: ${res.status}`);

    const body = await res.json();
    if (body.error) throw new Error(body.error);

    console.log(body.data.account.balance, body.data.account.nonce);
    ```
  </Tab>

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

    address = "erd1..."
    res = requests.get(f"https://rust-gateway.xoxno.com/address/{address}", timeout=10)
    res.raise_for_status()

    body = res.json()
    if body.get("error"):
        raise RuntimeError(body["error"])

    account = body["data"]["account"]
    print(account["balance"], account["nonce"])
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={"system"}
    // Run inside an async function with reqwest and serde_json.
    let address = "erd1...";
    let body: serde_json::Value = reqwest::Client::new()
        .get(format!("https://rust-gateway.xoxno.com/address/{address}"))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    if body["error"].as_str().unwrap_or("") != "" {
        return Err(format!("gateway error: {}", body["error"]).into());
    }

    println!(
        "{} {}",
        body["data"]["account"]["balance"], body["data"]["account"]["nonce"]
    );
    ```
  </Tab>
</Tabs>

## Success Response

```json theme={"system"}
{
  "data": {
    "account": {
      "address": "erd1...",
      "nonce": 42,
      "balance": "1000000000000000000"
    }
  },
  "error": "",
  "code": "successful"
}
```

## Edge Cases

| Case                            | Behavior                                              | Fix                                                          |
| ------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
| HTTP `200` with `error`         | Observer returned an operation-level failure.         | Treat the response as failed.                                |
| Historical selector unavailable | Selected observer may not have the requested history. | Retry with supported selectors or without historical params. |
| `/address/{address}/shard`      | Computed locally from the address.                    | Use it to debug routing without observer dependency.         |
| Bulk read                       | Addresses are grouped by shard.                       | Keep request size bounded in your client.                    |

## Verify

* HTTP status is `200`.
* Response body has `error: ""`.
* Expected field exists under `data`.
* Historical queries return data for the intended block selector.

## Related Pages

* [Gateway quickstart](/gateway/quickstart)
* [Shard routing](/gateway/shard-routing)
* [Caching and deduplication](/gateway/caching-and-dedup)
* [Gateway API reference](/api-reference/overview)