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

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

{
  "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.

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": []
  }'

{
  "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:

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"
      }
    ]
  }'

{
  "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:

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..."
          }
        ]
      }
    ]
  }'

{
  "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:

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

{
  "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:

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

{
  "parent": "28Hsc7..."
}

Get sub-contracts deployed by a contract:

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

{
  "subContracts": ["29Itd8...", "30Jue9..."],
  "nextStart": 20
}

Get the total sub-contract count:

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

{
  "count": 42
}

Read contract events

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

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

{
  "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:

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

{
  "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)

Guides

Get contract state

Field types

Call a view function

Call a view function with arguments

Call multiple functions in one request

Get contract bytecode

Get parent and sub-contracts

Read contract events

Get the current event count

Parameters reference

Next steps

Contract events

Error handling

​Get contract state

​Field types

​Call a view function

​Call a view function with arguments

​Call multiple functions in one request

​Get contract bytecode

​Get parent and sub-contracts

​Read contract events

​Get the current event count

​Parameters reference

​Next steps

Contract events

Error handling

Get contract state

Field types

Call a view function

Call a view function with arguments

Call multiple functions in one request

Get contract bytecode

Get parent and sub-contracts

Read contract events

Get the current event count

Parameters reference

Next steps