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

# Reading Contracts

> Call view functions and read state from deployed Ralph contracts.

Ralph contracts on Alephium expose two ways to read data **contract state** (raw field values stored on-chain) and **view functions** (computed results from calling a read-only function). This guide covers both.

## Get contract state

Returns the raw storage fields of a deployed contract. No transaction needed this is a direct state read.

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{contract-address}/state" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "address": "27Gsc5...",
  "bytecode": "0101010...",
  "codeHash": "b2d71c...",
  "initialStateHash": "c3e82d...",
  "immFields": [
    {
      "type": "ByteVec",
      "value": "546f6b656e"
    }
  ],
  "mutFields": [
    {
      "type": "U256",
      "value": "1000000000000000000"
    }
  ],
  "asset": {
    "attoAlphAmount": "1000000000000000000",
    "tokens": []
  }
}
```

`immFields` are set at deployment and never change. `mutFields` change as the contract executes transactions. Field order matches the order they are declared in the Ralph source code.

## Field types

| Type      | Description              | Example value           |
| --------- | ------------------------ | ----------------------- |
| `U256`    | Unsigned 256-bit integer | `"1000000000000000000"` |
| `I256`    | Signed 256-bit integer   | `"-500"`                |
| `Bool`    | Boolean                  | `true`                  |
| `ByteVec` | Hex-encoded byte array   | `"546f6b656e"`          |
| `Address` | Base58 Alephium address  | `"1DrDyTr9..."`         |

## Call a view function

View functions run contract code without broadcasting a transaction. Use this to get computed values token balances, prices, ownership checks anything the contract calculates rather than stores directly.

```bash theme={null}
curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/call-contract" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group": 0,
    "address": "27Gsc5...",
    "methodIndex": 0,
    "args": []
  }'
```

```json theme={null}
{
  "returns": [
    {
      "type": "U256",
      "value": "1000000000000000000"
    }
  ],
  "gasUsed": 1000,
  "contracts": [],
  "txInputs": [],
  "txOutputs": [],
  "events": [],
  "debugMessages": []
}
```

`methodIndex` is the zero-based index of the function in the contract. If the contract has three public functions, they are `0`, `1`, and `2` in declaration order.

## Call a view function with arguments

Pass arguments in the `args` array using the same type names as the field types above:

```bash theme={null}
curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/call-contract" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group": 0,
    "address": "27Gsc5...",
    "methodIndex": 1,
    "args": [
      {
        "type": "Address",
        "value": "1DrDyTr9RpRsQnDnXo2YRiPzPW4ooHX5LLoqXrqfMrpQH"
      }
    ]
  }'
```

```json theme={null}
{
  "returns": [
    {
      "type": "U256",
      "value": "500000000000000000"
    }
  ],
  "gasUsed": 1200,
  "contracts": [],
  "events": []
}
```

## Call multiple functions in one request

Use `multicall-contract` to batch several calls into a single round trip:

```bash theme={null}
curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/multicall-contract" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {
        "group": 0,
        "address": "27Gsc5...",
        "methodIndex": 0,
        "args": []
      },
      {
        "group": 0,
        "address": "27Gsc5...",
        "methodIndex": 1,
        "args": [
          {
            "type": "Address",
            "value": "1DrDyTr9..."
          }
        ]
      }
    ]
  }'
```

```json theme={null}
{
  "results": [
    {
      "returns": [{ "type": "U256", "value": "1000000000000000000" }],
      "gasUsed": 1000
    },
    {
      "returns": [{ "type": "U256", "value": "500000000000000000" }],
      "gasUsed": 1200
    }
  ]
}
```

Results are returned in the same order as the `calls` array.

## Get contract bytecode

Returns the compiled bytecode of a contract by its code hash. Useful for verifying a deployed contract matches a known build:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{code-hash}/code" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "bytecode": "0101010...",
  "codeHash": "b2d71c..."
}
```

## Get parent and sub-contracts

Ralph supports hierarchical contract relationships. A factory contract can deploy child contracts you can navigate that tree:

**Get the parent of a contract:**

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{address}/parent" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "parent": "28Hsc7..."
}
```

**Get sub-contracts deployed by a contract:**

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{address}/sub-contracts?start=0&limit=20" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "subContracts": ["29Itd8...", "30Jue9..."],
  "nextStart": 20
}
```

**Get the total sub-contract count:**

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{address}/sub-contracts/current-count" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "count": 42
}
```

## Read contract events

Events emitted by a contract are queryable by contract address. Use `start` and `limit` to paginate:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}?start=0&limit=20" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "events": [
    {
      "blockHash": "00000000ab3c...",
      "txId": "503a2c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [
        {
          "type": "Address",
          "value": "1DrDyTr9..."
        },
        {
          "type": "U256",
          "value": "1000000000000000000"
        }
      ]
    }
  ],
  "nextStart": 20
}
```

`eventIndex` maps to the order events are declared in the Ralph contract. `nextStart` is the offset to pass to fetch the next page store it between requests rather than calculating it yourself.

## Get the current event count

Before paginating events, check how many exist so you can page backwards from the latest:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}/current-count" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "count": 384
}
```

To fetch the most recent 20 events set `start` to `count - 20`.

## Parameters reference

| Parameter        | Type    | Description                                    |
| ---------------- | ------- | ---------------------------------------------- |
| contract-address | string  | Base58 address of the deployed contract        |
| code-hash        | string  | 32-byte hex hash of the contract bytecode      |
| group            | integer | Group number the contract belongs to (0–3)     |
| methodIndex      | integer | Zero-based index of the function to call       |
| args             | array   | Function arguments as typed value objects      |
| start            | integer | Pagination offset for sub-contracts and events |
| limit            | integer | Results per page (max 100)                     |

## Next steps

<CardGroup cols={2}>
  <Card title="Contract events" icon="bolt" href="/smart-contracts/events">
    Subscribe to and query events from Ralph contracts
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/guides/error-handling">
    Retry logic and error code reference
  </Card>
</CardGroup>