Skip to main content

state_call

Description#

Executes a runtime API function on the Acala blockchain, allowing direct invocation of runtime-level methods that are not exposed as dedicated RPC endpoints. Runtime APIs provide access to specialized functionality implemented in the chain's runtime logic, such as metadata retrieval, transaction validation, fee calculations, and custom chain-specific operations. This method acts as a bridge between the JSON-RPC interface and the Substrate runtime's internal API surface. The runtime API is invoked at a specific block state, either the latest state or a historical state identified by block hash, enabling queries against any point in chain history.

Request Example#

curl -s https://api-acala.n.dwellir.com/YOUR_API_KEY -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"state_call","params":["Metadata_metadata_at_version", "0x0c", null]}'

Parameters#

ParameterTypeRequiredDescription
methodstringYesRuntime API method name (e.g., "Metadata_metadata_at_version", "TransactionPaymentApi_query_info")
datastringYesSCALE-encoded parameters in hexadecimal format, specific to the called method
block_hashstringNoBlock hash to query at. Omit for latest state

Response Format#

Returns SCALE-encoded data in hexadecimal format. The encoding structure depends entirely on the called runtime API method's return type. Client applications must use runtime metadata and appropriate decoding libraries to interpret the response correctly. The raw hexadecimal response requires knowledge of the expected return type structure.

Common Runtime APIs#

Standard runtime APIs available on Substrate chains include:

  • Metadata_metadata_at_version: Retrieve runtime metadata for a specific metadata version
  • TransactionPaymentApi_query_info: Estimate transaction fees for an extrinsic
  • AccountNonceApi_account_nonce: Get the current nonce for an account
  • BlockBuilder_apply_extrinsic: Simulate extrinsic execution without submission
  • Core_version: Get the runtime version information
  • Core_execute_block: Execute a full block (used by validators)

Acala may expose additional custom runtime APIs for DeFi-specific calculations or queries.

Use Cases#

  • Metadata Retrieval: Fetch specific versions of runtime metadata for compatibility
  • Fee Estimation: Calculate exact transaction fees before signing and submitting
  • Nonce Queries: Get account nonces for transaction construction
  • Custom Calculations: Access chain-specific computational logic for DeFi operations
  • Transaction Simulation: Validate transaction viability without submitting to the pool
  • Historical Queries: Execute runtime logic against historical blockchain states

Best Practices#

Always use established Substrate client libraries (Polkadot.js API, SubXT) rather than manually constructing runtime API calls. These libraries handle SCALE encoding/decoding, metadata interpretation, and type safety automatically. When calling runtime APIs at historical block states, ensure you have access to an archive node. Runtime API method signatures can change across runtime upgrades, so verify compatibility between your client's expectations and the chain's current runtime version.

Technical Considerations#

Runtime API calls are executed within the Wasm runtime environment on the node, consuming computational resources. Complex or expensive runtime API calls may take longer to execute than simple state queries. The runtime API surface is defined by the chain's runtime implementation and can be extended through runtime upgrades. Always check the runtime metadata to discover available APIs and their exact signatures.