Read methods
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.
| Method | Returns |
|---|---|
arkiv_query | One page of the entities that match a query, and how many match |
arkiv_getEntity | One entity by key, or null |
arkiv_getBlockTiming | The 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.
arkiv_query
Section titled “arkiv_query”Finds the entities that match a query and returns the fields you select:
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" } ]}EOFThe 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:
| Field | Description |
|---|---|
select | The fields to return. Defaults to { "key": true } |
limit | The page size, from 1 to 100. Defaults to 100 |
offset | How many matches to skip before the page. Defaults to 0 |
Select fields
Section titled “Select fields”Every select field is a boolean, and off unless you set it:
| Field | Returns |
|---|---|
key | The entity key. On when you leave out select |
owner, creator | The owner and the account that created the entity |
createdAt, updatedAt, expiresAt | Block numbers, as hex |
creationFlags | { "readonly", "permissionlessExtension", "raw" } |
attributes | Every attribute with its value |
attributeSchema | Every attribute’s name, type and indexed, without values |
count | How 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 } }]Response
Section titled “Response”{ "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:
| Type | JSON value |
|---|---|
bool | true or false |
i32 | A number |
u64, u256 | A hex quantity, such as "0x2a" |
dec | A decimal string, such as "4.5" |
str | A string |
addr, key, bytes | Hex bytes |
Paginate
Section titled “Paginate”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.
Errors
Section titled “Errors”The node rejects a query it can’t run with one of these error codes:
| Code | Cause |
|---|---|
-32001 | The query doesn’t parse. data holds the position, what was expected and what was found |
-32002 | A condition uses the wrong type for its operator, such as STARTSWITH on an i32, or BETWEEN bounds of two types |
-32003 | A value is invalid, such as an i32 out of range |
-32004 | The query goes over a node limit, such as its length or nesting depth |
A limit outside 1 to 100 fails with -32602, invalid params.
arkiv_getEntity
Section titled “arkiv_getEntity”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.
arkiv_getBlockTiming
Section titled “arkiv_getBlockTiming”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.