JSON-RPC API

To interact with the Golem-Base Database Chain (DB-Chain) — whether by reading data or sending transactions that create or modify data—a software application must connect to a Golem-Base node.

Each DB-Chain client (based on op-geth) implements the standard JSON-RPC specification, widely used across all EVM-based blockchains. This ensures a consistent set of methods that applications can rely on, regardless of the specific node. In addition to this standard interface, DB-Chain provides extensions to the API that support data querying capabilities.

JSON-RPC is a stateless, lightweight remote procedure call (RPC) protocol. It defines various data structures and the rules for processing them. The protocol is transport-agnostic, meaning it can be used within the same process, over sockets, HTTP, or other messaging environments. It uses JSON (RFC 4627) as its data format. For more details on the JSON-RPC specification, visit the specification.

As per the JSON-RPC specification, all requests and responses follow a common schema structure described below. This shared schema eliminates the need to repeat these details for each endpoint. The only parts that vary between endpoints are the params in the request and the result in the response.

JSON-RPC API Request:

Field	Type	Description
jsonrpc	string	Version of the JSON-RPC protocol. Must be "2.0"
id	string	Request identifier. Can be any string or number. Used to match responses with requests
method	string	Name of the method to invoke
params	array	Array of parameters to pass to the method

JSON-RPC API Response:

Field	Type	Description
jsonrpc	string	Version of the JSON-RPC protocol. Must be "2.0"
id	string	Request identifier matching the request
result	any	The result of the method call. Type depends on the method
error	object	Error object if the request failed. Contains code and message

Creating/Updating/Deleting Entities

Mutation operations are described together because they are supported in the same way and can even be combined in a single transaction.

To create, update, delete, or extend entities, you need to send a standard transaction to the following address:

0x0000000000000000000000000000000060138453

This transaction must follow a specific data structure and is sent using a regular web3 JSON-RPC endpoint, such as eth_sendTransaction.

There are four types of entity mutations:

• Create – Create a new entity.
• Update – Modify an existing entity's payload and annotations.
• Delete – Remove an existing entity.
• Extend – Extend the BTL(blocks to live) of an existing entity.

Request params

params
transactionObject	object	JSON object with specified schema

transactionObject
from	string	The address the transaction is sent from.
to	string	The target address. For entity mutations, this must be 0x0000000000000000000000000000000060138453.
gas	number	(Optional) The maximum amount of gas to consume in the transaction.
gasPrice	number	(Optional) The price of gas for the transaction.
value	number	(Optional) The value should be skipped in our case.
nonce	number	(Optional) A sequential number issued by the sender's account.
data	string	A RLP(Recursive Length Prefix)-encoded storageTransaction structure described below encoded using

storageTransaction	array of arrays, each internal array described below
Create	array	Array of createObject of schema described below describing entities to be created
	createObject	Array with the following parameters in sequence
	BTL	string	Blocks-to-live in blocks, current block time of Golem-Base is 2 seconds expressed as Hex number
	Payload	any	The actual data to be stored in bytes
	StringAnnotations	object	Key-value pairs with string values for indexing in form of list values
	NumericAnnotations	object	Key-value pairs with string values for indexing in form of list values
Update	array	Array of updateObject of schema described below describing entities to be updated
	updateObject	Array with the following parameters in sequence
	EntityKey	string	The key (ID) of the entity to update
	BTL	string	Blocks-to-live in blocks, current block time of Golem-Base is 2 seconds expressed as Hex number
	Payload	any	The actual data to be stored in bytes
	StringAnnotations	object	Key-value pairs with string values for indexing in form of list values
	NumericAnnotations	object	Key-value pairs with string values for indexing in form of list values
Delete	array	Array of string, i.e. IDs (key hashes) of entities to be deleted
Extend	array	Array of extendObject described below providing dta related to extend expiration of given entitiy
	extendObject	Array with the following parameters in sequence
	EntityKey	string	The key (ID) of the entity to update
	NumberOfBlocks	string	Number of blocks to extend the BTL by expressed as Hex number

Response result

result	string
	The hash of the sent transaction.

Emitted Event Logs

Each mutation operation emits a corresponding event that can be retrieved from the transaction receipt or monitored via a WebSocket connection.

	GolemBaseStorageEntityCreated
Signature	GolemBaseStorageEntityCreated(bytes32 entityKey, uint256 expirationBlock)
Topic	0xce4b4ad6891d716d0b1fba2b4aeb05ec20edadb01df512263d0dde423736bbb9
Topics	[GolemBaseStorageEntityCreated, entityKey]
Data	The expiration block number

	GolemBaseStorageEntityUpdated
Signature	GolemBaseStorageEntityUpdated(uint256 entityKey, uint256 newExpirationBlock)
Topic	0xf371f40aa6932ad9dacbee236e5f3b93d478afe3934b5cfec5ea0d800a41d165
Topics	[GolemBaseStorageEntityUpdated, entityKey]
Data	The new expiration block number

	GolemBaseStorageEntityDeleted
Signature	GolemBaseStorageEntityDeleted(uint256 entityKey)
Topic	0x0297b0e6eaf1bc2289906a8123b8ff5b19e568a60d002d47df44f8294422af93
Topics	[GolemBaseStorageEntityDeleted, entityKey]
Data	Empty

	GolemBaseStorageEntityBTLExtended
Signature	GolemBaseStorageEntityBTLExtended(uint256 entityKey, uint256 oldExpirationBlock, uint256 newExpirationBlock)
Topic	0x835bfca6df78ffac92635dcc105a6a8c4fd715e054e18ef60448b0a6dce30c8d
Topics	[GolemBaseStorageEntityBTLExtended, entityKey]
Data	Contains both the old and new expiration block numbers

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_sendRawTransaction","params":[rlp-signed*({
    from: "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
    to: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
    gas: "0x76c0", // 30400
    gasPrice: "0x9184e72a000", // 10000000000000
    value: "0x9184e72a", // 2441406250
    data:
      rlp**(
        [
          // Creates
          [
            [
              hex(BTL),
              hex(payload),
              [
                hex(stringAnnotaionKey1),
                hex(stringAnnotationValue1),
                ...
              ],
              [
                hex(numericAnnotationKey1),
                hex(numericAnnotationValue1),
                ...
              ],
            ],
            ...
          ],
          // Updates
          [...],
          // Deletes
          [...],
          // Extends
          [...]
        ]),
  })],"id":1,"jsonrpc":"2.0"}'

// Here's an example of creating entities; updating is similar.

const creates: GolemBaseCreate[] = [
  {
    data: encoder.encode("foo"),
    btl: 25,
    stringAnnotations: [new Annotation("key", "foo")],
    numericAnnotations: [new Annotation("ix", 1)]
  },
  {
    data: encoder.encode("bar"),
    btl: 2,
    stringAnnotations: [new Annotation("key", "bar")],
    numericAnnotations: [new Annotation("ix", 2)]
  },
  {
    data: encoder.encode("qux"),
    btl: 50,
    stringAnnotations: [new Annotation("key", "qux")],
    numericAnnotations: [new Annotation("ix", 2)]
  }
];
const receipts = await client.createEntities(creates);

// Here's an example of deleting entities:

await client.deleteEntities([entityKey1, entityKey2]);

// Here's an example of extending entities:

await client.extendEntities([
  {
    entityKey: entityKey1,
    numberOfBlocks: 40,
  },
  {
    entityKey: entityKey2,
    numberOfBlocks: 40,
  }
]);

# Creating an entity:

create_receipt = await client.create_entities(
    [GolemBaseCreate(b"hello from fred", 60,
        [Annotation("first", "Fred"), Annotation("last","Fiddlebits"), Annotation("first","Frederick")],
        [Annotation("favorite", 10), Annotation("next", 11)]
    )]
)

# Updating an entity is similar

# Deleting an entity:

await client.delete_entities([GolemBaseDelete(entity_key)])

# Extending an entity:

await client.extend_entities(
  [GolemBaseExtend(entity_key, 60)]
)

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
  "id": 1
}

*rlp-signed

The transaction object to be sent to the blockchain must be signed with the user's private key and then encoded using RLP. This can be done via the eth_signTransaction endpoint. For more information, see: eth_signTransaction documentation.

**rlp

RLP (Recursive Length Prefix) is a serialization format used in Ethereum and other blockchain networks to encode structured data. It's designed to be space-efficient and deterministic, making it ideal for blockchain applications.

Command Line RLP Encoding Options:

rlp (Node.js package)ethereum-utils (Python package)cast (Foundry tool)eth-utils (Go package)

# Install the rlp package
npm install -g rlp

# Encode a list (array)
rlp encode '["item1", "item2", 123]'

# Encode nested structures
rlp encode '[["nested", "list"], "simple", 456]'

# Install ethereum-utils
pip install ethereum-utils

# Use the rlp command
rlp encode '["Hello", "World"]'

# Install Foundry (includes cast)
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Encode RLP data
cast --to-rlp '["Hello", "World"]'

# Install eth-utils
go install github.com/ethereum/go-ethereum/cmd/rlp@latest

# Encode data
rlp encode '["Hello", "World"]'

Example RLP Encoding for Storage Transaction:

# Encode a storage transaction structure
# 1 new object, 2 deleted and 2 BTL-extended
rlp encode '[
  [["0x1234", "0x5678", ["0x1235", "0x9876"], ["0xabcd", "0xefgh"]],
  [],
  ["0xdelete1", "0xdelete2"],
  [["0xextend1", "0x1000"], ["0xextend2", "0x2000"]]
]'

Querying Entities

To support efficient querying of entities in the GolemBase DBChain, we have introduced a set of dedicated API endpoints specifically designed for this purpose. These endpoints are unique to DBChains and enable users to retrieve both the payload and metadata of stored entities.

golembase_getStorageValue

Retrieves the payload of the entity identified by the given ID, where the ID corresponds to the hash of the entity's key.

Note: The returned payload is Base64-encoded. You must decode it to obtain the actual value.

Request params

params
entityId	string	The hash of the entity's key (hex string with 0x prefix)

Response result

result	string
	Base64-encoded payload of the entity

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getStorageValue","params":["0x5af98a2edd5c779515359a0a023bad597c6b59877b970ab5e16b3ba000dcab74"],"id":1,"jsonrpc":"2.0"}'

// Value comes back as a Uint8Array, and needs to be decoded
const decoder = new TextDecoder();
const value: any = decoder.decode(await client.getStorageValue(entityKey));

value = await client.get_storage_value(GenericBytes.from_hex_string(hash))

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": "eyJwcm9wZXJ0aWVzIjp7ImdvbGVtIjp7ImFjdGl2aXR5Ijp7ImNhcHMiOnsiZGVwbG95Ijp7InJlcG9ydC1wcm9ncmVzcyI6dHJ1ZX0sInRyYW5zZmVyIjp7InByb3RvY29sIjpbImdmdHAiLCJodHRwcyIsImh0dHAiXSwicmVwb3J0LXByb2dyZXNzIjp0cnVlfX19LCJjb20iOnsicGF5bWVudCI6eyJkZWJpdC1ub3RlcyI6eyJhY2NlcHQtdGltZW91dD8iOjI0MH0sInBsYXRmb3JtIjp7ImVyYzIwLW1haW5uZXQtZ2xtIjp7ImFkZHJlc3MiOiIweGQzNDYyMjVmZmZhMjZkZDJiYWExMmVlODJkNGVhMmQ2ZDMxMGM1N2QifSwiZXJjMjAtcG9seWdvbi1nbG0iOnsiYWRkcmVzcyI6IjB4ZDM0NjIyNWZmZmEyNmRkMmJhYTEyZWU4MmQ0ZWEyZDZkMzEwYzU3ZCJ9fSwicHJvdG9jb2wiOnsidmVyc2lvbiI6M319LCJwcmljaW5nIjp7Im1vZGVsIjp7IkB0YWciOiJsaW5lYXIiLCJsaW5lYXIiOnsiY29lZmZzIjpbNi45NDQ0NDQ0NDQ0NDQ0NDVlLTYsMS4zODg4ODg4ODg4ODg4ODllLTYsMC4wXX19fSwic2NoZW1lIjp7IkB0YWciOiJwYXl1IiwicGF5dSI6eyJkZWJpdC1ub3RlIjp7ImludGVydmFsLXNlYz8iOjEyMH0sInBheW1lbnQtdGltZW91dC1zZWM/IjoxMjB9fSwidXNhZ2UiOnsidmVjdG9yIjpbImdvbGVtLnVzYWdlLmNwdV9zZWMiLCJnb2xlbS51c2FnZS5kdXJhdGlvbl9zZWMiXX19LCJpbmYiOnsiY3B1Ijp7ImFyY2hpdGVjdHVyZSI6Ing4Nl82NCIsImJyYW5kIjoiQU1EIFJ5emVuIDcgUFJPIDg3MDBHRSB3LyBSYWRlb24gNzgwTSBHcmFwaGljcyIsImNhcGFiaWxpdGllcyI6WyJzc2UzIiwicGNsbXVscWRxIiwibW9uaXRvciIsInNzc2UzIiwiZm1hIiwiY21weGNoZzE2YiIsInNzZTQxIiwic3NlNDIiLCJtb3ZiZSIsInBvcGNudCIsImFlc25pIiwieHNhdmUiLCJvc3hzYXZlIiwiYXZ4IiwiZjE2YyIsInJkcmFuZCIsImZwdSIsInZtZSIsImRlIiwicHNlIiwidHNjIiwibXNyIiwicGFlIiwibWNlIiwiY3g4IiwiYXBpYyIsInNlcCIsIm10cnIiLCJwZ2UiLCJtY2EiLCJjbW92IiwicGF0IiwicHNlMzYiLCJjbGZzaCIsIm1teCIsImZ4c3IiLCJzc2UiLCJzc2UyIiwiaHR0IiwiZnNnc2Jhc2UiLCJibWkxIiwiYXZ4MiIsInNtZXAiLCJibWkyIiwicmVwX21vdnNiX3N0b3NiIiwiaW52cGNpZCIsInJkdG0iLCJyZHRhIiwicmRzZWVkIiwiYWR4Iiwic21hcCIsImNsZmx1c2hvcHQiLCJzaGEiLCJhdng1MTJmIiwiYXZ4NTEyZHEiLCJhdng1MTJfaWZtYSIsImF2eDUxMmNkIiwiYXZ4NTEyYnciLCJhdng1MTJ2bCIsImNsd2IiLCJ1bWlwIiwicGt1Iiwib3Nwa2UiLCJyZHBpZCJdLCJjb3JlcyI6OCwibW9kZWwiOiJTdGVwcGluZyAyIEZhbWlseSAzNSBNb2RlbCAyMjkiLCJ0aHJlYWRzIjoxLCJ2ZW5kb3IiOiJBdXRoZW50aWNBTUQifSwibWVtIjp7ImdpYiI6NS4wfSwic3RvcmFnZSI6eyJnaWIiOjIwLjB9fSwibm9kZSI6eyJkZWJ1ZyI6eyJzdWJuZXQiOiJwdWJsaWMifSwiaWQiOnsibmFtZSI6InRlc3RuZXQtZ29sZW1iYXNlLTEtSEVMIn0sIm5ldCI6eyJpcy1wdWJsaWMiOnRydWV9fSwicnVudGltZSI6eyJjYXBhYmlsaXRpZXMiOlsiaW5ldCIsInZwbiIsIm1hbmlmZXN0LXN1cHBvcnQiLCJzdGFydC1lbnRyeXBvaW50Il0sIm5hbWUiOiJ2bSIsInZlcnNpb24iOiIwLjQuMiJ9LCJzcnYiOnsiY2FwcyI6eyJtdWx0aS1hY3Rpdml0eSI6dHJ1ZSwicGF5bG9hZC1tYW5pZmVzdCI6dHJ1ZX19fX0sImNvbnN0cmFpbnRzIjoiKCZcbiAgKGdvbGVtLnNydi5jb21wLmV4cGlyYXRpb24+MTc1MDA3MDU5NDA1NilcbiAgKGdvbGVtLm5vZGUuZGVidWcuc3VibmV0PXB1YmxpYylcbikiLCJwcm92aWRlcklkIjoiMHhkMzQ2MjI1ZmZmYTI2ZGQyYmFhMTJlZTgyZDRlYTJkNmQzMTBjNTdkIiwiZXhwaXJhdGlvbiI6IjIwMjUtMDYtMThUMTA6NTA6MTguMTQ3NzQxNTU4WiIsInRpbWVzdGFtcCI6IjIwMjUtMDYtMThUMDk6NTA6MTguMTQ3NzQxNTU4WiJ9",
  "id": 1
}

golembase_getEntityMetaData

Retrieves the metadata of the entity identified by the given ID, where the ID corresponds to the hash of the entity's key. The metadata includes the Block-to-Live (BTL) value and annotations, which can be either numeric or text-based.

Request params

params
entityId	string	The hash of the entity's key (hex string with 0x prefix)

Response result

result	object
expiresAtBlock	number	Block number at which the entity expires
owner	string	Address of the entity owner
numericAnnotations	array of {key, value} objects with numeric values	Array of numeric annotations
stringAnnotations	array of {key, value} objects with text values	Array of string annotations

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getEntityMetaData","params":["0x69b4dff7af9e2969bde9eb772c3ac8a186b8dd7c764464b5f811f2ee32342009"],"id":1,"jsonrpc":"2.0"}'

const metadata: EntityMetaData = await client.getEntityMetaData(hash);

value = await client.get_entity_metadata(GenericBytes.from_hex_string(hash))

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": {
    "expiresAtBlock": 309137,
    "owner": "0x1fd9ab6f69590ed958400542fe0f47acb7f6472f",
    "numericAnnotations": [],
    "stringAnnotations": [{ "key": "golem_marketplace_type", "value": "Offer" }]
  },
  "id": 1
}

golembase_getEntitiesToExpireAtBlock

Retrieves a list of entity IDs that are scheduled to expire at the specified block number.

Request params

params
blockNumber	number	The block number at which to check for expiring entities

Response result

result	array
	List of entity IDs (hex strings with 0x prefix)

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getEntitiesToExpireAtBlock","params":[309137],"id":1,"jsonrpc":"2.0"}'

const entities: Hex[] = await client.getEntitiesToExpireAtBlock(309137n);

value = await client.get_entities_to_expire_at_block(metadata.expires_at_block)

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    "0x69b4dff7af9e2969bde9eb772c3ac8a186b8dd7c764464b5f811f2ee32342009",
    "0x5af98a2edd5c779515359a0a023bad597c6b59877b970ab5e16b3ba000dcab74"
  ],
  "id": 1
}

golembase_getEntitiesForStringAnnotationValue

Retrieves a list of entity IDs that have a specific string annotation value.

Request params

params
annotationKey	string	The annotation key to search for
annotationValue	string	The value of the string annotation to search for

Response result

result	array
	List of entity IDs (hex strings with 0x prefix)

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getEntitiesForStringAnnotationValue","params":["golem_marketplace_type", "Offer"],"id":1,"jsonrpc":"2.0"}'

// Not presently available in the TypeScript SDK

# Not presently available in the TypeScript SDK

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    "0x69b4dff7af9e2969bde9eb772c3ac8a186b8dd7c764464b5f811f2ee32342009",
    "0x5af98a2edd5c779515359a0a023bad597c6b59877b970ab5e16b3ba000dcab74"
  ],
  "id": 1
}

golembase_getEntitiesForNumericAnnotationValue

Retrieves a list of entity IDs that have a specific numeric annotation value.

Request params

params
annotationKey	string	The annotation key to search for
annotationValue	number	The value of the numeric annotation to search for

Response result

result	array
	List of entity IDs (hex strings with 0x prefix)

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getEntitiesForNumericAnnotationValue","params":["golem_cpu_cores", 8],"id":1,"jsonrpc":"2.0"}'

// Not presently available in the TypeScript SDK

# Not presently available in the TypeScript SDK

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    "0x69b4dff7af9e2969bde9eb772c3ac8a186b8dd7c764464b5f811f2ee32342009",
    "0x5af98a2edd5c779515359a0a023bad597c6b59877b970ab5e16b3ba000dcab74"
  ],
  "id": 1
}

golembase_getEntityCount

Retrieves the total number of entities currently stored in the database.

Request params

params
(none)		No parameters required

Response result

result	number
	Total number of entities in the database

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getEntityCount","params":[],"id":1,"jsonrpc":"2.0"}'

const count: number = await client.getEntityCount();

value = await client.get_entity_count()

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": 1250,
  "id": 1
}

golembase_getAllEntityKeys

Retrieves a list of all entity keys currently stored in the database.

Request params

params
(none)		No parameters required

Response result

result	array
	List of entity keys (hex strings with 0x prefix)

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getAllEntityKeys","params":[],"id":1,"jsonrpc":"2.0"}'

const keys: Hex[] = await client.getAllEntityKeys();

keys = await client.get_all_entity_keys()

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    "0x69b4dff7af9e2969bde9eb772c3ac8a186b8dd7c764464b5f811f2ee32342009",
    "0x5af98a2edd5c779515359a0a023bad597c6b59877b970ab5e16b3ba000dcab74",
    "0x1d5c05dbad706beadaba8e9bc9d3360d337b31cf6463d03b00e4feb5f84dba12",
    "0x441b4d66d91051763cfc44a3e8d399c77e3ca901513a9b0e63c3155208f9b688"
  ],
  "id": 1
}

golembase_getEntitiesOfOwner

Retrieves a list of entity IDs owned by a specific address.

Request params

params
owner	string	The address of the entity owner (hex string with 0x prefix)

Response result

result	array
	List of entity IDs (hex strings with 0x prefix)

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getEntitiesOfOwner","params":["0x1fd9ab6f69590ed958400542fe0f47acb7f6472f"],"id":1,"jsonrpc":"2.0"}'

const entities: Hex[] = await client.getEntitiesOfOwner(address);

entities = client.get_entities_of_owner(client.get_account_address())

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    "0x69b4dff7af9e2969bde9eb772c3ac8a186b8dd7c764464b5f811f2ee32342009",
    "0x5af98a2edd5c779515359a0a023bad597c6b59877b970ab5e16b3ba000dcab74"
  ],
  "id": 1
}

golembase_queryEntities

Retrieves a list of key-value pairs, where the key is the entity ID that matches the specified query criteria, and the value is the Base64-encoded payload of the entity. This endpoint supports flexible querying based on various features.

There is only one parameter, query, which represents the entire query expression. The following query features are supported:

• Equality comparisons for both string and numeric annotations
  Examples: name = "test", age = 123

• Logical operators for combining conditions
  Supported operators:
  && (AND), e.g., name = "test" && age = 30
|| (OR), e.g., status = "active" || status = "pending"

• Parentheses for grouping expressions and controlling evaluation order
  Example: (type = "document" || type = "image") && status = "approved"

• Numeric values must be represented as unsigned integers

Request params

params
query	string	The query string to search for entities

Response result

result	array of key-value pairs
key	entity ID (hex strings with 0x prefix)
value	entity's payload (Base64-encoded)

Example request:

cURLTypeScriptPythonRust

curl https://kaolin.holesky.golem-base.io/rpc \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_queryEntities","params":["golem_marketplace_type=\"Offer\""],"id":1,"jsonrpc":"2.0"}'

const result:any = await client.queryEntities('golem_marketplace_type="Offer"');

query_result = await client.query_entities('app = "demo"')

// Under Construction, coming soon!

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "key": "0x1168417031fbef13f27f375d33384cfe70e35afac5f9da9c20b64634c7d18f32",
      "value": "eyJwcm9wZXJ0aWVzIjp7ImdvbGVtIjp7ImFjdGl2aXR5Ijp7ImNhcHMiOnsiZGVwbG95Ijp7InJlcG9ydC1wcm9ncmVzcyI6dHJ1ZX0sInRyYW5zZmVyIjp7InByb3RvY29sIjpbImh0dHAiLCJodHRwcyIsImdmdHAiXSwicmVwb3J0LXByb2dyZXNzIjp0cnVlfX19LCJjb20iOnsicGF5bWVudCI6eyJkZWJpdC1ub3RlcyI6eyJhY2NlcHQtdGltZW91dD8iOjI0MH0sInBsYXRmb3JtIjp7ImVyYzIwLW1haW5uZXQtZ2xtIjp7ImFkZHJlc3MiOiIweDk5N2JhYzQ4OWJkZWVjNmM5ZDQ0OGZkNDgwYzZjNjFjODA5NTg0ZTkifSwiZXJjMjAtcG9seWdvbi1nbG0iOnsiYWRkcmVzcyI6IjB4OTk3YmFjNDg5YmRlZWM2YzlkNDQ4ZmQ0ODBjNmM2MWM4MDk1ODRlOSJ9fSwicHJvdG9jb2wiOnsidmVyc2lvbiI6M319LCJwcmljaW5nIjp7Im1vZGVsIjp7IkB0YWciOiJsaW5lYXIiLCJsaW5lYXIiOnsiY29lZmZzIjpbNi45NDQ0NDQ0NDQ0NDQ0NDVlLTYsMS4zODg4ODg4ODg4ODg4ODllLTYsMC4wXX19fSwic2NoZW1lIjp7IkB0YWciOiJwYXl1IiwicGF5dSI6eyJkZWJpdC1ub3RlIjp7ImludGVydmFsLXNlYz8iOjEyMH0sInBheW1lbnQtdGltZW91dC1zZWM/IjoxMjB9fSwidXNhZ2UiOnsidmVjdG9yIjpbImdvbGVtLnVzYWdlLmNwdV9zZWMiLCJnb2xlbS51c2FnZS5kdXJhdGlvbl9zZWMiXX19LCJpbmYiOnsiY3B1Ijp7ImFyY2hpdGVjdHVyZSI6Ing4Nl82NCIsImJyYW5kIjoiQU1EIFJ5emVuIDcgUFJPIDg3MDBHRSB3LyBSYWRlb24gNzgwTSBHcmFwaGljcyIsImNhcGFiaWxpdGllcyI6WyJzc2UzIiwicGNsbXVscWRxIiwibW9uaXRvciIsInNzc2UzIiwiZm1hIiwiY21weGNoZzE2YiIsInNzZTQxIiwic3NlNDIiLCJtb3ZiZSIsInBvcGNudCIsImFlc25pIiwieHNhdmUiLCJvc3hzYXZlIiwiYXZ4IiwiZjE2YyIsInJkcmFuZCIsImZwdSIsInZtZSIsImRlIiwicHNlIiwidHNjIiwibXNyIiwicGFlIiwibWNlIiwiY3g4IiwiYXBpYyIsInNlcCIsIm10cnIiLCJwZ2UiLCJtY2EiLCJjbW92IiwicGF0IiwicHNlMzYiLCJjbGZzaCIsIm1teCIsImZ4c3IiLCJzc2UiLCJzc2UyIiwiaHR0IiwiZnNnc2Jhc2UiLCJibWkxIiwiYXZ4MiIsInNtZXAiLCJibWkyIiwicmVwX21vdnNiX3N0b3NiIiwiaW52cGNpZCIsInJkdG0iLCJyZHRhIiwicmRzZWVkIiwiYWR4Iiwic21hcCIsImNsZmx1c2hvcHQiLCJzaGEiLCJhdng1MTJmIiwiYXZ4NTEyZHEiLCJhdng1MTJfaWZtYSIsImF2eDUxMmNkIiwiYXZ4NTEyYnciLCJhdng1MTJ2bCIsImNsd2IiLCJ1bWlwIiwicGt1Iiwib3Nwa2UiLCJyZHBpZCJdLCJjb3JlcyI6OCwibW9kZWwiOiJTdGVwcGluZyAyIEZhbWlseSAzNSBNb2RlbCAyMjkiLCJ0aHJlYWRzIjoxLCJ2ZW5kb3IiOiJBdXRoZW50aWNBTUQifSwibWVtIjp7ImdpYiI6Mi4wfSwic3RvcmFnZSI6eyJnaWIiOjIwLjB9fSwibm9kZSI6eyJkZWJ1ZyI6eyJzdWJuZXQiOiJwdWJsaWMifSwiaWQiOnsibmFtZSI6InRlc3RuZXQtZ29sZW1iYXNlLTAtSEVMIn0sIm5ldCI6eyJpcy1wdWJsaWMiOnRydWV9fSwicnVudGltZSI6eyJuYW1lIjoid2FzbXRpbWUiLCJ2ZXJzaW9uIjoiMC4yLjEifSwic3J2Ijp7ImNhcHMiOnsibXVsdGktYWN0aXZpdHkiOnRydWUsInBheWxvYWQtbWFuaWZlc3QiOmZhbHNlfX19fSwiY29uc3RyYWludHMiOiIoJlxuICAoZ29sZW0uc3J2LmNvbXAuZXhwaXJhdGlvbj4xNzUwMTExNTg2MDUzKVxuICAoZ29sZW0ubm9kZS5kZWJ1Zy5zdWJuZXQ9cHVibGljKVxuKSIsInByb3ZpZGVySWQiOiIweDVlMTczNjI1YWU0MDYyNTZhMTAzOWVhNTJlODE5ZDVjOTE1NGM0NDEiLCJleHBpcmF0aW9uIjoiMjAyNS0wNi0yMFQxMjoxMjowNi40NDA5MDg3MDdaIiwidGltZXN0YW1wIjoiMjAyNS0wNi0yMFQxMToxMjowNi40NDA5MDg3MDdaIn0="
    },
    {
      "key": "0x88d2c5394f7e0d7f73f792d8d184bfd971bb12c340214202b3c0420fbad3ec7b",
      "value": "eyJwcm9wZXJ0aWVzIjp7ImdvbGVtIjp7ImFjdGl2aXR5Ijp7ImNhcHMiOnsiZGVwbG95Ijp7InJlcG9ydC1wcm9ncmVzcyI6dHJ1ZX0sInRyYW5zZmVyIjp7InByb3RvY29sIjpbImh0dHBzIiwiZ2Z0cCIsImh0dHAiXSwicmVwb3J0LXByb2dyZXNzIjp0cnVlfX19LCJjb20iOnsicGF5bWVudCI6eyJkZWJpdC1ub3RlcyI6eyJhY2NlcHQtdGltZW91dD8iOjI0MH0sInBsYXRmb3JtIjp7ImVyYzIwLW1haW5uZXQtZ2xtIjp7ImFkZHJlc3MiOiIweDVlMTczNjI1YWU0MDYyNTZhMTAzOWVhNTJlODE5ZDVjOTE1NGM0NDEifSwiZXJjMjAtcG9seWdvbi1nbG0iOnsiYWRkcmVzcyI6IjB4NWUxNzM2MjVhZTQwNjI1NmExMDM5ZWE1MmU4MTlkNWM5MTU0YzQ0MSJ9fSwicHJvdG9jb2wiOnsidmVyc2lvbiI6M319LCJwcmljaW5nIjp7Im1vZGVsIjp7IkB0YWciOiJsaW5lYXIiLCJsaW5lYXIiOnsiY29lZmZzIjpbNi45NDQ0NDQ0NDQ0NDQ0NDVlLTYsMS4zODg4ODg4ODg4ODg4ODllLTYsMC4wXX19fSwic2NoZW1lIjp7IkB0YWciOiJwYXl1IiwicGF5dSI6eyJkZWJpdC1ub3RlIjp7ImludGVydmFsLXNlYz8iOjEyMH0sInBheW1lbnQtdGltZW91dC1zZWM/IjoxMjB9fSwidXNhZ2UiOnsidmVjdG9yIjpbImdvbGVtLnVzYWdlLmNwdV9zZWMiLCJnb2xlbS51c2FnZS5kdXJhdGlvbl9zZWMiXX19LCJpbmYiOnsiY3B1Ijp7ImFyY2hpdGVjdHVyZSI6Ing4Nl82NCIsImNvcmVzIjoxNCwidGhyZWFkcyI6MX0sIm1lbSI6eyJnaWIiOjIuMH0sInN0b3JhZ2UiOnsiZ2liIjoyMC4wfX0sIm5vZGUiOnsiZGVidWciOnsic3VibmV0IjoicHVibGljIn0sImlkIjp7Im5hbWUiOiJ0ZXN0bmV0LWdvbGVtYmFzZS0wLURFIn0sIm5ldCI6eyJpcy1wdWJsaWMiOnRydWV9fSwicnVudGltZSI6eyJuYW1lIjoid2FzbXRpbWUiLCJ2ZXJzaW9uIjoiMC4yLjEifSwic3J2Ijp7ImNhcHMiOnsibXVsdGktYWN0aXZpdHkiOnRydWUsInBheWxvYWQtbWFuaWZlc3QiOmZhbHNlfX19fSwiY29uc3RyYWludHMiOiIoJlxuICAoZ29sZW0uc3J2LmNvbXAuZXhwaXJhdGlvbj4xNzUwMTExNTg2MDUzKVxuICAoZ29sZW0ubm9kZS5kZWJ1Zy5zdWJuZXQ9cHVibGljKVxuKSIsInByb3ZpZGVySWQiOiIweDVlMTczNjI1YWU0MDYyNTZhMTAzOWVhNTJlODE5ZDVjOTE1NGM0NDEiLCJleHBpcmF0aW9uIjoiMjAyNS0wNi0yMFQxMjoxMjowNi40NDA5MDg3MDdaIiwidGltZXN0YW1wIjoiMjAyNS0wNi0yMFQxMToxMjowNi40NDA5MDg3MDdaIn0="
    }
  ],
  "id": 1
}