Skip to main content
Grid exposes a JSON-RPC 2.0 endpoint over HTTPS. The CLI, the Rust SDK, and any third-party integration call the same surface.

​
How to call it

A JSON-RPC call is a POST of a JSON body to a single URL. The endpoint depends on the network you target. For DevNet:
DevNet access. Ask your Gen Labs contact for the RPC URL and a bearer token, then substitute them for <DEVNET_RPC_URL> and <your-jwt> in the examples below.
curl -s -X POST <DEVNET_RPC_URL> \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"gen_getVersion","params":{}}'
Find the endpoint for your network in Network status.

​
Envelope

Every request follows JSON-RPC 2.0: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "gen_<methodName>",
  "params": { /* method-specific */ }
}
Successful responses: 
{ "jsonrpc": "2.0", "id": 1, "result": { /* method-specific */ } }
Errors: 
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params" } }
Method names are camelCase with a gen_ prefix (gen_getActivation, not gen_GetActivation).

​
Error model

Errors fall into three layers, checked in this order:
  1. Transport errors: the request never reached the validator. HTTP status codes apply (502, 504). Retry with backoff.
  2. JSON-RPC errors: the request was malformed. Standard codes: -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error. Do not retry without fixing the request.
  3. Application errors: the request was valid but the operation failed (insufficient balance, unknown account, etc.). Returned as a result payload with a status field, not as an error. Treat as a state to handle, not a retry signal.

​
Binary payloads

Methods that take or return raw bytes (gen_submitActivation, gen_view, gen_simulateActivation, gen_getStorageAt) represent those bytes as base64-encoded strings in JSON-RPC. The Rust SDK handles the encoding for you.

​
Versioning

Two version fields matter, both returned by gen_getVersion:
  • release_version: the validator’s release.
  • rpc_protocol_version: the wire-protocol version. Pin against this in production; minor revisions can add fields, breaking changes increment the version.
Clients may pass an X-Gen-Protocol-Version header (e.g. 0.1.0) on any request. When present, the server validates it and rejects mismatches with error code -32001. When absent, no validation occurs.

​
Methods

Sixteen public methods, grouped by domain. Click any method to expand its parameters, response shape, and an example request.

​
Activations

Sends a signed activation to the network.Parameters
​
payload
Base64Bytes
required
Arbitrary binary data encoded as a base64 string.
Result
​
result
ActivationId
required
Activation ID assigned to the submitted activation
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_submitActivation", "params": {"request": "<...>"}}'
Simulates an activation without submitting it to the network. The activation is executed locally and all continuations are followed BFS-style. State queries are resolved against the specified block height (if provided).Parameters
​
block_index
U64String | null
​
payload
Base64Bytes
required
Arbitrary binary data encoded as a base64 string.
Result
​
activation_results
SimulationActivationResult[]
required
Per-activation results in BFS execution order.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_simulateActivation", "params": {"request": "<...>"}}'
Returns activation details by id. Returns JSON-RPC NOT_FOUND if the activation does not exist.Parameters
​
activation_id
ActivationId
required
Result
​
activation
ActivationInfo
required
Activation details returned by the API.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getActivation", "params": {"request": "<...>"}}'
Returns trace details by id.Parameters
​
trace_id
TransactionId
required
Result
​
activations
ActivationId[]
required
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getTrace", "params": {"request": "<...>"}}'
Executes a read-only activation payload. No state changes occur.Parameters
​
payload
Base64Bytes
required
Arbitrary binary data encoded as a base64 string.
Result
​
bytes
Base64Bytes
required
Opaque result bytes encoded as base64 on the wire.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_view", "params": {"request": "<...>"}}'

​
Accounts and balances

Returns account details by address.Parameters
​
account
GvmAccount
required
Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity_id || 0u32_LE).
Result
​
components
GvmComponentId[]
required
Components installed on the account.
​
owner
ComponentOwner
required
Owner of the account.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getAccount", "params": {"request": "<...>"}}'
Returns the routed fungible balance for an account.Parameters
​
account
GvmAccount
required
Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity_id || 0u32_LE).
​
gvm_contract
GvmContract | null
Result
​
result
Amount
required
Balance amount for the requested contract, or the configured GEN contract when omitted
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getBalance", "params": {"request": "<...>"}}'
Returns all configured fungible balances for an account.Parameters
​
account
GvmAccount
required
Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity_id || 0u32_LE).
Result
​
balances
object
required
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getBalances", "params": {"request": "<...>"}}'

​
Blocks

Returns an aggregated closed block for a given block index.Parameters
​
block_index
U64String
required
A u64 value serialized as a decimal string to preserve precision.
Result
​
block_index
U64String
required
A u64 value serialized as a decimal string to preserve precision.
​
order_events
BlockOrderEvent[]
required
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getBlock", "params": {"request": "<...>"}}'
Returns the latest finalized block index known to this RPC unit.Parameters
​
request
GetCurrentBlockIndexRequest
required
Request for the GetCurrentBlockIndex RPC.
Result
​
block_index
U64String
required
A u64 value serialized as a decimal string to preserve precision.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getCurrentBlockIndex", "params": {"request": "<...>"}}'

​
Contracts and components

Returns contract metadata and ABI.Parameters
​
contract
GvmContract
required
Result
​
abis
Abi[]
required
ABIs for all components in the contract.
​
details
ContractDetails
required
Contract details (code ID, owner).
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getContract", "params": {"request": "<...>"}}'
Returns component metadata and ABI.Parameters
​
component_id
GvmComponentId
required
Identifies a specific applicative GVM component instance (component entity + header). Contains the storage key plus applicative information for validations and orientation in the GVM.Serde/JSON uses the structured component_entity_id + header representation of this type.For human-readable CLI input/output, [fmt::Display] and [FromStr] use two or four comma-separated bech32m parts (HRP grd@), not a single bech32m string.

​
Equality and Hashing Semantics

GvmComponentId uses custom equality, hashing, and ordering: if either component has ContractVersion::LATEST, the version comparison is skipped. This allows latest-version matching to act as a wildcard that matches any version, which is useful for checks where the exact version shouldn’t matter.Important: The version field is NOT included in hashing or equality comparisons when Latest is involved, ensuring consistent behavior with HashMap/HashSet lookups.
Result
​
abi
Abi
required
ABI for the component.
​
component_id
GvmComponentId
required
Resolved component identifier (includes index when resolved via default route).
​
owner
ComponentOwner
required
Owner of the component.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getComponent", "params": {"request": "<...>"}}'
Returns contract ABIs by contract ID.Parameters
​
contract
GvmContract
required
Result
​
abis
Abi[]
required
ABIs for all components in the contract.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getAbiByContractId", "params": {"request": "<...>"}}'
Returns contract ABIs by contract code ID.Parameters
​
contract_code_id
GvmContractCodeId
required
Result
​
abis
Abi[]
required
ABIs for all components in the contract code.
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getAbiByContractCodeId", "params": {"request": "<...>"}}'
Returns the raw storage value for a component at a given key.Parameters
​
component_id
ComponentId
required
​
key
H256
required
256-bit hash value. Encoded as a 0x-prefixed, 64-character hex string.
Result
​
result
Base64Bytes | null
required
Base64Bytes or null if the key is missing
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getStorageAt", "params": {"request": "<...>"}}'

​
Node

Returns the artifact release version and developer-owned RPC protocol version.Parameters
​
request
GetVersionRequest
required
Request for the GetVersion RPC.
Result
​
release_version
string
required
​
rpc_protocol_version
string
required
Example request
curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getVersion", "params": {"request": "<...>"}}'