Skip to content

An Arkiv node answers the standard Ethereum JSON-RPC methods plus three arkiv_* methods that read entities. The SDK’s public client calls them for you. Call them directly when you work in a language without an SDK.

MethodReturns
arkiv_queryOne page of the entities that match a query, and how many match
arkiv_getEntityOne entity by key, or null
arkiv_getBlockTimingThe current block, its time and the block duration

The examples send requests to Rabdi’s RPC, https://rpc.rabdi.db-chain.testnet.arkiv.network, with your access key at the end of the URL. Its chain ID is 7794095. Set ARKIV_ACCESS_KEY before you run them. Without a key, the requests go to the public RPC, which is heavily rate limited.

Use of the public RPC is subject to the Arkiv Terms of Use and Privacy Policy.

Finds the entities that match a query and returns the fields you select:

Terminal window
curl "https://rpc.rabdi.db-chain.testnet.arkiv.network/$ARKIV_ACCESS_KEY" \
-H "content-type: application/json" \
--data @- <<'EOF'
{
"jsonrpc": "2.0",
"id": 1,
"method": "arkiv_query",
"params": [
"arkiv.schema = str('my-app.posts') AND category = str('news')",
{ "select": { "key": true, "attributes": true }, "limit": "0xa" }
]
}
EOF

The first parameter is the query. See the query language for its syntax. Anyone can write entities with any attributes, so filter on your project’s tag or on $owner.

The second parameter is optional. Every field in it is optional too:

FieldDescription
selectThe fields to return. Defaults to { "key": true }
limitThe page size, from 1 to 100. Defaults to 100
offsetHow many matches to skip before the page. Defaults to 0

Every select field is a boolean, and off unless you set it:

FieldReturns
keyThe entity key. On when you leave out select
owner, creatorThe owner and the account that created the entity
createdAt, updatedAt, expiresAtBlock numbers, as hex
creationFlags{ "readonly", "permissionlessExtension", "raw" }
attributesEvery attribute with its value
attributeSchemaEvery attribute’s name, type and indexed, without values
countHow many entities the query matches, as the response’s count

attributes also takes an object of names, to return only those: { "attributes": { "title": true } }.

count isn’t a field of each entity. It counts every match at the block, whatever the limit, and every page repeats it. With count as the only field, data is empty:

[
"arkiv.schema = str('my-app.posts') AND category = str('news')",
{ "select": { "count": true } }
]
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"data": [
{
"key": "0x9f2c…",
"attributes": [
{ "name": "arkiv.schema", "type": "str", "value": "my-app.posts" },
{ "name": "category", "type": "str", "value": "news" },
{ "name": "score", "type": "dec", "value": "4.5" }
]
}
],
"blockNumber": "0x1bc",
"count": "0x2a"
}
}

An entity holds only the fields you selected. A field you didn’t select is left out, not set to null. blockNumber is the block the page was read at, and count is there only if you selected it.

An attribute’s type decides how its value is written:

TypeJSON value
booltrue or false
i32A number
u64, u256A hex quantity, such as "0x2a"
decA decimal string, such as "4.5"
strA string
addr, key, bytesHex bytes

To get the next page, send the same query again with an offset. Add ORDER BY $key ASC so every page uses one order. This asks for the third page of 10:

[
"arkiv.schema = str('my-app.posts') ORDER BY $key ASC",
{ "limit": "0xa", "offset": "0x14" }
]

Each request reads the latest block. An entity created or deleted between two requests shifts the matches after it, so a row can repeat or be missed. A page with fewer rows than limit is the last, and an offset past the end returns an empty page. To read every match once, page by key: add $key > key(0x…) with the last key of the previous page.

The node rejects a query it can’t run with one of these error codes:

CodeCause
-32001The query doesn’t parse. data holds the position, what was expected and what was found
-32002A condition uses the wrong type for its operator, such as STARTSWITH on an i32, or BETWEEN bounds of two types
-32003A value is invalid, such as an i32 out of range
-32004The query goes over a node limit, such as its length or nesting depth

A limit outside 1 to 100 fails with -32602, invalid params.

Reads one entity by key at the latest block, with every field except attributeSchema:

{
"jsonrpc": "2.0",
"id": 1,
"method": "arkiv_getEntity",
"params": ["0x9f2c…"]
}

The result has the shape of an entity in arkiv_query. It’s null when no live entity has the key: it never existed, or it was deleted or has expired.

Takes no parameters and returns the latest block:

{ "current_block": 582143, "current_block_time": 1742721127, "duration": 2 }

current_block_time is a Unix time in seconds. duration is the number of seconds since the previous block.