Querying Data

You can query entities stored on Arkiv with standard JSON-RPC 2.0 calls. This page covers the methods, query syntax, operators, pagination, and utility endpoints.

Endpoint

Property	Value
Chain ID	7738577 (0x7614d1)
HTTP RPC	https://rpc.tiramisu.db-chain.testnet.arkiv.network
Explorer	tiramisu.explorer.arkiv.network

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

Note

This is the Tiramisu testnet endpoint. To inspect a transaction, block, or entity, open the explorer.

Request Format

All methods use standard JSON-RPC 2.0:

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"METHOD_NAME","params":[]}'

arkiv_getEntity

This method reads one entity by key, at the tip or as of a past block.

Parameters

Index	Type	Required	Description
0	string	Yes	Entity key, 32-byte hex
1	number	No	Block number to read as of

This method returns every field on the entity. There is no select option, because the read already names a single entity. If the key never existed, was deleted, or expired, this method returns null.

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"arkiv_getEntity","params":["0x9f2c..."]}'

arkiv_query

This method queries entities from the indexed store.

Parameters

Index	Type	Required	Description
0	string	Yes	Query expression
1	object/null	No	Query options

Query Syntax

A query is a bare boolean expression, no SELECT or WHERE. Keywords are case-insensitive. A comment starts with -- and runs to the end of the line.

For example, this query matches every open ticket with a priority of 3 or higher:

-- open tickets, priority 3 or higher
status = str('open') AND priority >= 3

Operators:

Operator	Description
AND	Logical AND
OR	Logical OR
NOT	Complement, evaluated against the set of live entities
=	Equality
<, >, <=, >=	Numeric comparisons (ordered types only: i32, u64, u256, dec)
STARTSWITH	String prefix match (the language’s only pattern operator)

Caution

!= is reserved in the grammar but not implemented at this version. It fails to parse. Write NOT (attr = value) for the complement instead. This also matches entities that never set the attribute, because it is the full complement, not a typed not-equal.

Value literals:

Every value carries a type tag. The tag is part of what the predicate asserts. For example, level >= i32(10) matches only entities whose level is an i32.

Two things are untagged: a bare boolean (true / false) and a bare number. An untagged number defaults to i32. You must give every other value an explicit type tag:

Type	Literal form
String	str('open')
32-bit integer	i32(10) or bare 10
64-bit unsigned integer	u64(1200000)
256-bit unsigned integer	u256(1000000)
Fixed-point decimal	dec('3.5')
Address	addr(0xAbC...)
Entity key	key(0x123...)
Fixed 32 bytes	bytes32(0x...)
Boolean	bare true / false

Match everything:

*

Synthetic attributes (use with $ prefix):

Attribute	Type	Filterable
$key	key	Yes
$owner	addr	Yes
$creator	addr	Yes
$expiresAt	u64	Yes
$createdAt	u64	Yes
$contentType	str	Yes
$updatedAt	n/a	No (returned by projections only)
$creationFlags	n/a	No (returned by projections only)
$payload	n/a	No (bytes carry no index)

Caution

exists(...) and typeof(...) are reserved in the grammar but not implemented at this version: they fail to parse.

Options

Field	Type	Description
select	object	Which fields to return. Defaults to { "key": true }
limit	hex string	Page size. Node maximum is 200
cursor	string	Pagination cursor from a previous response
atBlock	hex string	Query at a specific block (for example, "0x1bc"). Defaults to the head

select fields (all default to false except key, which defaults to true when select is omitted):

key, owner, creator, createdAt, updatedAt, expiresAt, creationFlags, contentType, payload, attributeSchema, attributes

attributes can also take an object of names, to fetch only those. For example: { "attributes": { "status": true } }.

Response Structure

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "data": [
      {
        "key": "0x9f2c...",
        "owner": "0xabc...",
        "creator": "0xabc...",
        "createdAt": "0x191",
        "updatedAt": "0x1bb",
        "expiresAt": "0x2000",
        "creationFlags": { "readonly": false, "permissionlessExtension": false, "raw": 0 },
        "contentType": "application/json",
        "payload": "0x7b226d657373616765223a2268656c6c6f227d",
        "attributes": [
          { "name": "status", "type": "str", "value": "active" },
          { "name": "rarity", "type": "i32", "value": 5 }
        ]
      }
    ],
    "blockNumber": "0x1bc",
    "cursor": "0x2a"
  }
}

Note

If you select a field, it appears in the response. If you do not select a field, it does not appear at all. The response never sends an unselected field as null.

payload is hex-encoded bytes. Decode it to read the entity content. createdAt, updatedAt and expiresAt are hex block numbers. When no more pages remain, cursor is omitted.

The type of an attribute decides the JSON encoding of its value:

• i32: a JSON number
• u64 and u256: a 0x hex quantity
• dec: a decimal string
• The byte-shaped types: 0x bytes
• str: a plain string

Query Examples

By attribute:

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"arkiv_query",
    "params":[
      "type = str('\''nft'\'') AND status = str('\''active'\'')",
      {"limit":"0xa","select":{"key":true,"attributes":true}}
    ]
  }'

By owner:

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":10,
    "method":"arkiv_query",
    "params":[
      "$owner = addr(0x2222222222222222222222222222222222222222)",
      null
    ]
  }'

Numeric range:

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":12,
    "method":"arkiv_query",
    "params":["price >= i32(100) AND price <= i32(1000)", null]
  }'

Prefix match with negation:

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":13,
    "method":"arkiv_query",
    "params":["name STARTSWITH str('\''test'\'') AND NOT (status = str('\''deleted'\''))", null]
  }'

Metadata only (omit payload):

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":14,
    "method":"arkiv_query",
    "params":[
      "*",
      {
        "limit":"0xa",
        "select":{
          "key":true,"attributes":true,"payload":false,
          "contentType":true,"expiresAt":true,
          "creator":true,"owner":true
        }
      }
    ]
  }'

Pagination

Use the returned cursor in the next request:

{
  "method": "arkiv_query",
  "params": [
    "type = str('nft')",
    { "cursor": "0x2a", "limit": "0x2" }
  ]
}

When cursor is absent from the response, there are no more pages.

arkiv_getEntityCount

This method returns the total number of entities that match an optional query, at the tip or a past block.

Parameters

Index	Type	Required	Description
0	object/null	No	{ "query"?: string, "block"?: number }. Defaults to every entity at the tip

curl https://rpc.tiramisu.db-chain.testnet.arkiv.network \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"arkiv_getEntityCount","params":[]}'

Result: a plain JSON number (for example, 18427).

arkiv_getBlockTiming

This method returns the timing for the current head block. It takes no parameters.

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

• current_block_time: Unix timestamp in seconds
• duration: seconds since the previous block