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. DevNet requires a bearer token. Ask your Gen Labs contact for one and substitute it for <your-jwt> in the examples below.

curl -s -X POST https://devnet.genlabs.co/rpc/ \
  -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:

Transport errors - the request never reached the validator. HTTP status codes apply (502, 504). Retry with backoff.
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.
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

gen_submitActivation

Sends a signed activation to the network.Parameters

Base64Bytes

required

Arbitrary binary data encoded as a base64 string.

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

gen_simulateActivation

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

U64String | null

Base64Bytes

required

Arbitrary binary data encoded as a base64 string.

Result

SimulationActivationResult[]

required

Per-activation results in BFS execution order.

Show item properties

Base64Bytes

required

Borsh-serialized activation envelope.

ActivationId

required

ID of the activation that was executed.

EntityId

required

Entity targeted by this activation.

OperationResult[]

required

Per-operation results (changes, events, continuations).

Show item properties

StorageChange[]

required

Storage changes made by this operation.

Show item properties

H256

required

Global storage key (32 bytes), serialized as a 0x-prefixed hex string.

Base64Bytes

required

Storage value as base64 bytes.

ActivationId[]

required

Continuations (internal activation IDs) created by this operation.

Event[]

required

Events emitted by this operation.

Show item properties

string

required

Human-readable name describing the payload.

string

required

Logical subsystem that emitted the event (e.g., "Gvm").

integer (uint32)

required

Operation index that produced this event.

Base64Bytes

required

Raw payload bytes of the event payload (base64 on the wire).

string

required

RFC3339 timestamp describing when the event was emitted.

integer (uint16)

required

Event schema version.

ComponentId

required

The component that was the target of this operation.

ExecutionOutcome

required

Execution outcome (success or failure with message).

Example request

curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_simulateActivation", "params": {"request": "<...>"}}'

gen_getActivation

Returns activation details by id. Returns JSON-RPC NOT_FOUND if the activation does not exist.Parameters

ActivationId

required

Result

ActivationInfo

required

Activation details returned by the API.

Show properties

object

required

Activation body/details (schema depends on activation type).

string

required

Activation type discriminator (e.g., "GVM").

ActivationId[]

required

Continuation activation IDs, if any.

U64String

required

Block index where the activation ended.

Event[]

required

Domain-specific events emitted during execution.

Show item properties

string

required

Human-readable name describing the payload.

string

required

Logical subsystem that emitted the event (e.g., "Gvm").

integer (uint32)

required

Operation index that produced this event.

Base64Bytes

required

Raw payload bytes of the event payload (base64 on the wire).

string

required

RFC3339 timestamp describing when the event was emitted.

integer (uint16)

required

Event schema version.

EntityId

required

Sender entity.

ConsumedGas

required

Gas consumed by this activation, broken down by resource type.

Show properties

U128String

required

A u128 value serialized as a decimal string to preserve precision.

U128String

required

A u128 value serialized as a decimal string to preserve precision.

U128String

required

A u128 value serialized as a decimal string to preserve precision.

ActivationId | null

Parent activation ID, if any.

U64String

required

Block index where the activation started.

ActivationStatus

required

Typed execution status.

EntityId

required

Target entity.

Example request

curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getActivation", "params": {"request": "<...>"}}'

gen_getTrace

Returns trace details by id.Parameters

TransactionId

required

Result

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

gen_view

Executes a read-only activation payload. No state changes occur.Parameters

Base64Bytes

required

Arbitrary binary data encoded as a base64 string.

Result

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

gen_getAccount

Returns account details by address.Parameters

GvmAccount

required

Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity_id || 0u32_LE).

Result

GvmComponentId[]

required

Components installed on the account.

Show item properties

EntityId

required

Unique 256-bit identifier for an entity in the Grid VM.Encoded as a 0x-prefixed, 64-character hex string on the JSON-RPC wire.

GvmComponentHeader

required

Shared header for GVM component metadata.This header is used both on the host and in the VM as the canonical representation of GVM component identity.

Show properties

GvmComponentCodeId

required

Uniquely represents a single code artifact.A code artifact is identified by the push that uploaded it and the role index within that push. This is used to identify executable code in the GVM.

Show properties

ComponentTypeIndex

required

Index of a role within a GVM system.

GvmContractCodeId

required

GvmContract

required

GvmComponentIndex

required

Index of a component within a GVM system.0 is reserved for the account component, while values greater than 0 represent explicit user component indices.

ContractVersion

required

Version of a GVM system implementation.

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

gen_getBalance

Returns the routed fungible balance for an account.Parameters

GvmAccount

required

Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity_id || 0u32_LE).

GvmContract | null

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

gen_getBalances

Returns all configured fungible balances for an account.Parameters

GvmAccount

required

Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity_id || 0u32_LE).

Result

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

gen_getBlock

Returns an aggregated closed block for a given block index.Parameters

U64String

required

A u64 value serialized as a decimal string to preserve precision.

Result

U64String

required

A u64 value serialized as a decimal string to preserve precision.

BlockOrderEvent[]

required

Show item properties

ActivationId

required

Activation ID for which this event is recorded.

EntityId

required

Entity ID on which this activation was executed.

BlockOrderEventKind

required

Event payload (start or end).

U64String

required

Lamport timestamp associated with this event.

Example request

curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getBlock", "params": {"request": "<...>"}}'

gen_getCurrentBlockIndex

Returns the latest finalized block index known to this RPC unit.Parameters

GetCurrentBlockIndexRequest

required

Request for the GetCurrentBlockIndex RPC.

Result

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

gen_getContract

Returns contract metadata and ABI.Parameters

GvmContract

required

Result

Abi[]

required

ABIs for all components in the contract.

ContractDetails

required

Contract details (code ID, owner).

Show properties

GvmContractCodeId

required

The contract code identifier.

ComponentOwner

required

The owner of the contract.

Example request

curl -s -X POST $RPC_URL \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getContract", "params": {"request": "<...>"}}'

gen_getComponent

Returns component metadata and ABI.Parameters

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.

Show properties

EntityId

required

Unique 256-bit identifier for an entity in the Grid VM.Encoded as a 0x-prefixed, 64-character hex string on the JSON-RPC wire.

GvmComponentHeader

required

Shared header for GVM component metadata.This header is used both on the host and in the VM as the canonical representation of GVM component identity.

Show properties

GvmComponentCodeId

required

Uniquely represents a single code artifact.A code artifact is identified by the push that uploaded it and the role index within that push. This is used to identify executable code in the GVM.

Show properties

ComponentTypeIndex

required

Index of a role within a GVM system.

GvmContractCodeId

required

GvmContract

required

GvmComponentIndex

required

Index of a component within a GVM system.0 is reserved for the account component, while values greater than 0 represent explicit user component indices.

ContractVersion

required

Version of a GVM system implementation.

Result

Abi

required

ABI for the component.

GvmComponentId

required

Resolved component identifier (includes index when resolved via default route).

Show properties

EntityId

required

Unique 256-bit identifier for an entity in the Grid VM.Encoded as a 0x-prefixed, 64-character hex string on the JSON-RPC wire.

GvmComponentHeader

required

Shared header for GVM component metadata.This header is used both on the host and in the VM as the canonical representation of GVM component identity.

Show properties

GvmComponentCodeId

required

Uniquely represents a single code artifact.A code artifact is identified by the push that uploaded it and the role index within that push. This is used to identify executable code in the GVM.

Show properties

ComponentTypeIndex

required

Index of a role within a GVM system.

GvmContractCodeId

required

GvmContract

required

GvmComponentIndex

required

Index of a component within a GVM system.0 is reserved for the account component, while values greater than 0 represent explicit user component indices.

ContractVersion

required

Version of a GVM system implementation.

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

gen_getAbiByContractId

Returns contract ABIs by contract ID.Parameters

GvmContract

required

Result

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

gen_getAbiByContractCodeId

Returns contract ABIs by contract code ID.Parameters

GvmContractCodeId

required

Result

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

gen_getStorageAt

Returns the raw storage value for a component at a given key.Parameters

ComponentId

required

H256

required

256-bit hash value. Encoded as a 0x-prefixed, 64-character hex string.

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

gen_getVersion

Returns the artifact release version and developer-owned RPC protocol version.Parameters

GetVersionRequest

required

Request for the GetVersion RPC.

Result

string

required

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

RPC

SDK

Contracts

AI

CLI

Troubleshooting

JSON-RPC API

How to call it

Envelope

Error model

Binary payloads

Versioning

Methods

Activations

Accounts and balances

Blocks

Contracts and components

Equality and Hashing Semantics

Node

​How to call it

​Envelope

​Error model

​Binary payloads

​Versioning

​Methods

​Activations

​Accounts and balances

​Blocks

​Contracts and components

​Equality and Hashing Semantics

​Node

How to call it

Envelope

Error model

Binary payloads

Versioning

Methods

Activations

Accounts and balances

Blocks

Contracts and components

Equality and Hashing Semantics

Node