# Resource filtering pattern Heimdahl uses a consistent pattern-based filtering approach across all data types, with specific actions for accessing historical data and subscribing to real-time updates. This document explains our filtering pattern syntax, how to use it effectively, and why we chose this approach over alternative filtering methods. ### Pattern Structure Heimdahl provides a consistent pattern structure across interfaces, with slight naming differences between command line and REST API and SDKs. #### Command Line Interface ``` {resource} {action} {pattern} ``` Where: * `{resource}` is the primary data category (event, transfer, swap) - singular form * `{action}` is either `list` (for historical data) or `subscribe` (for real-time updates) * `{pattern}` is a structured filtering expression using dot notation #### REST API Interface ``` /{resources_plural}/{action}/{pattern} ``` Where: * `{resources_plural}` is the primary data category in plural form (events, transfers, swaps) to follow RESTful conventions * `{action}` is either `list` (for historical data) or `subscribe` (for real-time updates) * `{pattern}` is the same structured filtering expression as used in the command line ### Actions Heimdahl provides two primary actions for each resource type: * **list**: Retrieves historical data matching the specified pattern * **subscribe**: Creates a real-time subscription for new data matching the pattern ### Pattern Syntax By Resource Type Each resource type has a specific pattern format that reflects its unique properties: #### Event Pattern ``` event list {chain}.{network}.{token_address}.{event_name} event subscribe {chain}.{network}.{token_address}.{event_name} ``` Examples: ``` event list base.mainnet.0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.Transfer event subscribe base.mainnet.0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.Transfer ``` The first query returns historical Transfer events, while the second creates a real-time subscription. #### Transfer Pattern ``` transfer list {chain}.{network}.{symbol}.{sender_addr}.{receiver_addr}.{size} transfer subscribe {chain}.{network}.{symbol}.{sender_addr}.{receiver_addr}.{size} ``` Examples: ``` transfer list base.mainnet.usdc.all.all.all transfer subscribe base.mainnet.usdc.all.all.all ``` The first query returns historical USDC transfers, while the second subscribes to new transfers as they occur. #### Swap Pattern ``` swap list {chain}.{network}.{symbol1}.{symbol2}.{size} swap subscribe {chain}.{network}.{symbol1}.{symbol2}.{size} ``` Examples: ``` swap list ethereum.mainnet.usdc.weth.all swap subscribe ethereum.mainnet.usdc.weth.all ``` The first query returns historical USDC-WETH swaps, while the second creates a real-time subscription. ### Using the `all` Placeholder The keyword `all` serves as a wildcard for any field you don't want to filter on. This allows for flexible queries that can be refined as needed: **CLI examples:** ``` transfer list base.mainnet.usdc.all.all.all # All historical USDC transfers on Base mainnet transfer subscribe base.mainnet.usdc.0x123...abc.all.all # Subscribe to new USDC transfers from a specific address swap list ethereum.mainnet.all.weth.all # All historical swaps involving WETH on Ethereum mainnet ``` **REST API examples:** ``` /transfers/list/base.mainnet.usdc.all.all.all # All historical USDC transfers on Base mainnet /transfers/subscribe/base.mainnet.usdc.0x123...abc.all.all # Subscribe to new USDC transfers from a specific address /swaps/list/ethereum.mainnet.all.weth.all # All historical swaps involving WETH on Ethereum mainnet ``` ### Examples Below are examples showing both CLI and REST API usage for the same queries: #### Events for a Specific Contract **CLI:** ``` event list ethereum.mainnet.0x6B175474E89094C44Da98b954EedeAC495271d0F.Transfer ``` **REST API:** ``` /events/list/ethereum.mainnet.0x6B175474E89094C44Da98b954EedeAC495271d0F.Transfer ``` #### Real-time Transfer Monitoring by Token **CLI:** ``` transfer subscribe ethereum.mainnet.dai.all.all.all ``` **REST API:** ``` /transfers/subscribe/ethereum.mainnet.dai.all.all.all ``` #### Historical Transfers from a Specific Sender **CLI:** ``` transfer list ethereum.mainnet.usdc.0x123...abc.all.all ``` **REST API:** ``` /transfers/list/ethereum.mainnet.usdc.0x123...abc.all.all ``` #### Real-time Swap Monitoring Between Specific Token Pairs **CLI:** ``` swap subscribe ethereum.mainnet.usdc.weth.all ``` **REST API:** ``` /swaps/subscribe/ethereum.mainnet.usdc.weth.all ``` ### Why Pattern-based Filtering? #### Consistency Across Methods The same pattern structure works for both historical data retrieval and real-time subscriptions, creating a unified query language for all interactions with Heimdahl. #### Cross-Chain Scalability Our pattern approach provides a unified syntax that works across all supported blockchains while respecting their unique characteristics. Adding support for new chains doesn't change the fundamental query structure. #### Parameter Extensibility As we add support for new filtering parameters, the pattern syntax naturally accommodates them in a consistent way. This future-proofs your integration with Heimdahl. #### Readability and Brevity Patterns using dot notation are more concise and readable than traditional query parameters: **CLI:** ``` # Pattern approach transfer list ethereum.mainnet.usdc.0x123...abc.all.all # Traditional query parameters approach would be more verbose transfer --chain=ethereum --network=mainnet --token=usdc --sender=0x123...abc ``` **REST API:** ``` # Pattern approach /transfers/list/ethereum.mainnet.usdc.0x123...abc.all.all # Traditional query parameters /transfers/list?chain=ethereum&network=mainnet&token=usdc&sender=0x123...abc ``` ### Dotted Pattern vs. Flag-based Filtering Many blockchain APIs use traditional flag or parameter-based filtering. While familiar, this approach has several disadvantages that our dotted pattern syntax addresses: 1. **Simplicity**: Dotted patterns create a natural hierarchy that's easy to understand and remember 2. **Consistency**: The same pattern structure works across all data types and interfaces 3. **Brevity**: Patterns require significantly fewer characters than equivalent flag-based queries 4. **Extensibility**: New filtering parameters can be added without changing the API structure 5. **Readability**: Patterns visually represent the relationship between filter parameters For example, a typical flag-based query might look like: ``` ?chain=ethereum&network=mainnet&token=usdc&sender=0x123...abc ``` While our dotted pattern approach simplifies this to: ``` ethereum.mainnet.usdc.0x123...abc.all.all ``` This approach scales much better as your queries become more complex. ### Advanced Usage #### Pattern Refinement Start with broader patterns and refine as needed: **CLI:** ``` # Start with all historical USDC transfers transfer list ethereum.mainnet.usdc.all.all.all # Refine to specific senders transfer list ethereum.mainnet.usdc.0x123...abc.all.all # Subscribe to specific transfers between two addresses transfer subscribe ethereum.mainnet.usdc.0x123...abc.0x456...def.all ``` **REST API:** ``` # Start with all historical USDC transfers /transfers/list/ethereum.mainnet.usdc.all.all.all # Refine to specific senders /transfers/list/ethereum.mainnet.usdc.0x123...abc.all.all # Subscribe to specific transfers between two addresses /transfers/subscribe/ethereum.mainnet.usdc.0x123...abc.0x456...def.all ``` ### Implementation Notes When implementing clients to work with our API, we recommend: 1. Building pattern-construction utilities to help users create valid patterns 2. Creating template functions for common queries (list vs. subscribe) 3. Implementing proper subscription management for real-time data ### Conclusion Our pattern-based filtering approach provides a powerful, consistent, and future-proof way to query blockchain data across different chains and data types. By using the same pattern syntax for both historical (`list`) and real-time (`subscribe`) data access, Heimdahl creates a unified experience that simplifies blockchain data integration. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://heimdahl.gitbook.io/heimdahl.xyz/getting-started/resource-filtering-pattern.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.