Skip to content

gRPC API

Torii's gRPC API provides high-performance access to indexed world data through binary serialization and streaming capabilities. It's designed for applications requiring low latency and efficient data fetching.

Quick Start

Endpoint: http://localhost:8080 (gRPC protocol)

Protocol Type Definitions: torii/proto/types

Client Libraries:

Core Concepts

Query Structure

Both Retrieve and Subscribe queries use the Query message with these fields:

struct Query {
  clause: Clause;                  // What to query
  limit: uint32;                   // Max results (pagination)
  offset: uint32;                  // Skip results (pagination)
  dont_include_hashed_keys: bool;  // Performance optimization
  order_by: Vec<OrderBy>;          // Sort order
  entity_models: Vec<String>;      // Filter models
  entity_updated_after: uint64;    // Incremental updates
}

Clause Types

Keys Clause - Query by entity keys:

{
    "Keys": {
        "keys": ["0x127fd..."],
        "pattern_matching": "FixedLen",
        "models": ["dojo_starter-Position"]
    }
}

Member Clause - Query by field values:

{
    "Member": {
        "model": "dojo_starter-Moves",
        "member": "remaining",
        "operator": "Gt",
        "value": { "Primitive": { "U32": 10 } }
    }
}

Composite Clause - Combine multiple queries:

{
    "Composite": {
        "operator": "And",
        "clauses": [
            /* multiple clauses */
        ]
    }
}

Query Examples

Basic Entity Query

Get all entities with any key:

{
    "clause": {
        "Keys": {
            "keys": [""],
            "pattern_matching": "VariableLen",
            "models": []
        }
    },
    "limit": 50
}

Field-Based Query

Find players with moves remaining:

{
    "clause": {
        "Member": {
            "model": "dojo_starter-Moves",
            "member": "remaining",
            "operator": "Gt",
            "value": { "Primitive": { "U32": 0 } }
        }
    }
}

Position Range Query

Find entities in coordinate range:

{
    "clause": {
        "Composite": {
            "operator": "And",
            "clauses": [
                {
                    "Member": {
                        "model": "dojo_starter-Position",
                        "member": "x",
                        "operator": "Gte",
                        "value": { "Primitive": { "U32": 0 } }
                    }
                },
                {
                    "Member": {
                        "model": "dojo_starter-Position",
                        "member": "x",
                        "operator": "Lt",
                        "value": { "Primitive": { "U32": 100 } }
                    }
                }
            ]
        }
    }
}

Pagination & Sorting

Basic Pagination with limit and offset

{
    "limit": 25,
    "offset": 50,
    "clause": null
}

Ordered Results with order_by

{
    "order_by": [
        {
            "model": "dojo_starter-Moves",
            "member": "remaining",
            "direction": "Desc"
        }
    ]
}

Model Filtering with entity_models

{
    "entity_models": ["dojo_starter-Position", "dojo_starter-Moves"]
}

Operators & Values

Comparison Operators

  • Eq, Neq - Equal, not equal
  • Gt, Gte - Greater than, greater than or equal
  • Lt, Lte - Less than, less than or equal
  • In, NotIn - In list, not in list

Value Types

{
  "Primitive": {
    "U32": 42,           // Numbers
    "Bool": true,        // Booleans
    "felt252": [...]     // Byte arrays for felt252
  }
}

Pattern Matching

  • FixedLen - Exact key match
  • VariableLen - Prefix match (at least these keys)

Performance Tips

Query Optimization:

  • Set dont_include_hashed_keys: true for better performance if you don't need entity IDs
  • Use specific models in entity_models to reduce data transfer
  • Prefer VariableLen pattern matching for flexible key queries

Incremental Updates:

  • Use entity_updated_after with timestamps for efficient polling
  • Combine with subscriptions for real-time updates

Pagination:

  • Use reasonable limit values (25-100 entities)
  • Implement pagination for large datasets

Subscriptions

gRPC supports streaming subscriptions for real-time updates:

  • Entity Updates: Subscribe to changes in specific entities
  • Event Streams: Monitor world events as they occur
  • Model Changes: Track updates to specific model types

Best Practices

Connection Management:

  • Use connection pooling for high-throughput applications
  • Handle reconnection logic for streaming subscriptions
  • Set appropriate timeouts for long-running queries

Query Design:

  • Start with simple queries and add complexity as needed
  • Use composite queries sparingly - prefer multiple simple queries
  • Test query performance with realistic data volumes

Data Handling:

  • Process results incrementally for large datasets
  • Cache frequently accessed entities locally
  • Use model filtering to minimize bandwidth