---
# System prepended metadata

title: Exposing runtime APIs through RPC methods
tags: [' substrate', evergreen-note]

---



Issue: https://github.com/paritytech/substrate/pull/13095
PR: https://github.com/paritytech/substrate/pull/13119

---

We want to implement the following RPC methods that expose staking and nomination pools runtime APIs: 
- `pointsToBalance {pool_id, points}`
- `balanceToPoints {pool_id, balance}`
- `nominationsQuota`

https://forum.parity.io/t/remove-rpcs-that-can-be-replaced-by-state-call/1070

**Goal**: expose new runtime API methods (`pointsToBalance`, `balanceToPoints`, `nominationsQuota`) for external clients to query nomination pools and staking related data easily via the `state_call` RPC call. This will help clients (more specifically wallets) to query dynamic on-chain data, instead of having to re-implement logic locally that may eventually change.

Historically, exposing a runtime API to clients would require implementing the whole RPC machinery as well (see to this [commit](https://github.com/paritytech/substrate/pull/13095/commits/b7a682fbf376778b03f5dc2db22ca0fd65f8b559)). However, [as of recently](https://forum.parity.io/t/remove-rpcs-that-can-be-replaced-by-state-call/1070), runtime API calls should be exposed to external clients via the `state_call` . Not all the custom RPC calls are deprecated, as some RPC methods target the client and not the runtime.

[This is PR](https://github.com/paritytech/substrate/pull/11831/files) a good example of how to expose a runtime API as an RPC method. In a nutshell:
1. Define a trait `SomethingApi` within a [`sp_api::decl_runtime_apis!`](https://paritytech.github.io/substrate/master/sp_api/macro.decl_runtime_apis.html) macro;
2. Implement the trait within a [`sp_api::impl_runtime_apis`](https://paritytech.github.io/substrate/master/sp_api/macro.impl_runtime_apis.html) in the node. The implementation of the `SomethingApi` trait may call into a pallet's state/method.  

#### How to call runtime APIs through `state_call`

The node exposes a json [RPC method called `state`](https://polkadot.js.org/docs/substrate/rpc#state) that allows clients to query runtime APIs. Its definition is the following:

```
- call(method: `Text`, data: `Bytes`, at?: `BlockHash`): `Bytes`[​]

-   **interface**: `api.rpc.state.call`
-   **jsonrpc**: `state_call`
-   **summary**: Perform a call to a builtin on the chain
```

The `params` of the `state_call` RPC call is a vector of strings, where the first string is the name of the runtime API call (in camel case), followed by the name of the method to call (in snake case). For example, `StakingApi_nominations_quota` calls into the `nominations_quota` of the `StakingApi` runtime API. The following strings are hex encoded strings of the runtime API inputs (empty if no input is required). E.g. 

```bash
$ curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "state_call", "params": ["StakingApi_nominations_quota", ""]}' http://node:9944

{"jsonrpc":"2.0","result":"0x10000000","id":1}
```

The results are hex encoded and can be decoded using [`polkadot/util`](https://github.com/polkadot-js/common/tree/master/packages/util#readme). In the case above, the `BN` is 16.
