Cartesi Query Reference

Complete reference for querying the L{CORE} Cartesi rollup.

Base URL

Environment	URL
Local	`http://localhost:10000`
Production	`http://${CARTESI_NODE_IP}:10000`

Query Format

URL Structure

http://<node>:10000/inspect/<url-encoded-json>

Important: The payload must be URL-encoded JSON, NOT hex-encoded.

Encoding Example

# Python URL encoding
python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"all_provider_schemas\",\"params\":{}}'))"

# Output: %7B%22type%22%3A%22all_provider_schemas%22%2C%22params%22%3A%7B%7D%7D

Response Format

All queries return:

{
  "status": "Accepted",
  "exception_payload": null,
  "reports": [
    {
      "payload": "0x..."  // Hex-encoded JSON result
    }
  ],
  "processed_input_count": 42
}

Decoding Response

// JavaScript
const response = await fetch(url)
const json = await response.json()
const hexPayload = json.reports[0].payload
const data = JSON.parse(
  Buffer.from(hexPayload.slice(2), 'hex').toString('utf8')
)

# Python
import requests
response = requests.get(url)
hex_payload = response.json()['reports'][0]['payload']
data = bytes.fromhex(hex_payload[2:]).decode('utf-8')

Query Types

all_provider_schemas

List all registered provider schemas.

Request:

curl "http://${CARTESI_NODE_IP}:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"all_provider_schemas\",\"params\":{}}'))")"

Response payload:

[
  {
    "schema_id": "coingecko-btc-price",
    "name": "CoinGecko BTC Price",
    "provider_type": "http",
    "bucket_definitions": {}
  }
]

provider_schema

Get a specific provider schema.

Parameters:

Parameter	Type	Required	Description
`schema_id`	string	Yes	Schema identifier

Request:

curl "http://${CARTESI_NODE_IP}:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"provider_schema\",\"params\":{\"schema_id\":\"coingecko-btc-price\"}}'))")"

Response payload:

{
  "schema_id": "coingecko-btc-price",
  "name": "CoinGecko BTC Price",
  "provider_type": "http",
  "bucket_definitions": {
    "price": {
      "boundaries": [0, 10000, 25000, 50000, 100000],
      "labels": ["<10k", "10k-25k", "25k-50k", "50k-100k", ">100k"]
    }
  },
  "data_keys": ["price", "timestamp"],
  "freshness_half_life": 3600
}

attestations_by_owner

Get all attestations for a specific address.

Parameters:

Parameter	Type	Required	Description
`owner`	string	Yes	Ethereum address

Request:

curl "http://${CARTESI_NODE_IP}:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"attestations_by_owner\",\"params\":{\"owner\":\"0x1234567890abcdef1234567890abcdef12345678\"}}'))")"

Response payload:

[
  {
    "attestation_id": "att-001",
    "schema_id": "coingecko-btc-price",
    "owner": "0x1234...",
    "encrypted_data": "0x...",
    "bucket_values": {
      "price": "25k-50k"
    },
    "timestamp": 1704067200,
    "block_number": 12345678
  }
]

attestation

Get a specific attestation by ID.

Parameters:

Parameter	Type	Required	Description
`attestation_id`	string	Yes	Attestation identifier

Request:

curl "http://${CARTESI_NODE_IP}:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"attestation\",\"params\":{\"attestation_id\":\"att-001\"}}'))")"

Response payload:

{
  "attestation_id": "att-001",
  "schema_id": "coingecko-btc-price",
  "owner": "0x1234...",
  "encrypted_data": "0x...",
  "bucket_values": {
    "price": "25k-50k"
  },
  "timestamp": 1704067200
}

check_access

Check if a requester has access to an owner's data.

Parameters:

Parameter	Type	Required	Description
`owner`	string	Yes	Data owner address
`requester`	string	Yes	Requesting address

Request:

curl "http://${CARTESI_NODE_IP}:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"check_access\",\"params\":{\"owner\":\"0x1234...\",\"requester\":\"0x5678...\"}}'))")"

Response payload:

{
  "has_access": true,
  "grants": [
    {
      "grant_id": "grant-001",
      "schema_id": "coingecko-btc-price",
      "expires_at": 1735689600
    }
  ]
}

grants_by_owner

List all access grants given by an owner.

Parameters:

Parameter	Type	Required	Description
`owner`	string	Yes	Grant owner address

Request:

curl "http://${CARTESI_NODE_IP}:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"grants_by_owner\",\"params\":{\"owner\":\"0x1234...\"}}'))")"

Response payload:

[
  {
    "grant_id": "grant-001",
    "requester": "0x5678...",
    "schema_id": "coingecko-btc-price",
    "created_at": 1704067200,
    "expires_at": 1735689600
  }
]

health

Check Cartesi node health.

Request:

curl "http://${CARTESI_NODE_IP}:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"health\",\"params\":{}}'))")"

Response payload:

{
  "status": "healthy",
  "database": "ok",
  "processed_inputs": 1234
}

Error Handling

Query Errors

When a query fails:

{
  "status": "Rejected",
  "exception_payload": "0x...",  // Hex-encoded error message
  "reports": []
}

Common Errors

Error	Description
`Unknown query type`	Invalid `type` parameter
`Missing required parameter`	Required param not provided
`Schema not found`	Schema ID doesn't exist
`Attestation not found`	Attestation ID doesn't exist

Helper Scripts

Bash Helper

#!/bin/bash
# lcore-query.sh

CARTESI_URL="${CARTESI_URL:-http://localhost:10000}"

query() {
  local payload="$1"
  local encoded=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$payload'))")
  curl -s "${CARTESI_URL}/inspect/${encoded}" | jq '.reports[0].payload' -r | xxd -r -p
}

# Usage
query '{"type":"all_provider_schemas","params":{}}'

JavaScript Helper

async function queryCartesi(type, params = {}) {
  const payload = JSON.stringify({ type, params })
  const encoded = encodeURIComponent(payload)
  const url = `${CARTESI_URL}/inspect/${encoded}`

  const response = await fetch(url)
  const json = await response.json()

  if (json.status !== 'Accepted') {
    throw new Error(`Query rejected: ${json.exception_payload}`)
  }

  const hex = json.reports[0].payload.slice(2)
  return JSON.parse(Buffer.from(hex, 'hex').toString('utf8'))
}

// Usage
const schemas = await queryCartesi('all_provider_schemas')

Python Helper

import urllib.parse
import requests

def query_cartesi(query_type, params=None):
    params = params or {}
    payload = {"type": query_type, "params": params}
    encoded = urllib.parse.quote(json.dumps(payload))
    url = f"{CARTESI_URL}/inspect/{encoded}"

    response = requests.get(url)
    data = response.json()

    if data["status"] != "Accepted":
        raise Exception(f"Query rejected: {data['exception_payload']}")

    hex_payload = data["reports"][0]["payload"][2:]
    return json.loads(bytes.fromhex(hex_payload).decode())

# Usage
schemas = query_cartesi("all_provider_schemas")

Base URL​

Query Format​

URL Structure​

Encoding Example​

Response Format​

Decoding Response​

Query Types​

all_provider_schemas​

provider_schema​

attestations_by_owner​

attestation​

check_access​

grants_by_owner​

health​

Error Handling​

Query Errors​

Common Errors​

Helper Scripts​

Bash Helper​

JavaScript Helper​

Python Helper​

Base URL

Query Format

URL Structure

Encoding Example

Response Format

Decoding Response

Query Types

all_provider_schemas

provider_schema

attestations_by_owner

attestation

check_access

grants_by_owner

health

Error Handling

Query Errors

Common Errors

Helper Scripts

Bash Helper

JavaScript Helper

Python Helper