### Install Python Kafka Client with pip

Source: https://docs.allium.so/datastreams/kafka

This command installs the `confluent_kafka` Python library using the `pip` package manager, which is the standard package installer for Python. It provides the core functionalities for developing Kafka consumer applications.

```bash
pip install confluent_kafka
```

--------------------------------

### Install Python Kafka Client with uv

Source: https://docs.allium.so/datastreams/kafka

This command installs the `confluent_kafka` Python library using the `uv` package manager, which is a modern and fast tool for Python dependency management. It ensures the necessary dependencies are available for building Kafka consumer applications.

```bash
uv add confluent_kafka
```

--------------------------------

### Example cURL Request for DEX Trades API

Source: https://docs.allium.so/developer/data/ethereum/dex/dex-trades

Provides a cURL command example to demonstrate how to make a GET request to the DEX trades API endpoint. Users must replace `{chain}` with the desired blockchain identifier (e.g., 'ethereum') and `<api-key>` with their valid Allium API key to authenticate the request.

```bash
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/dex/trades \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Example cURL GET Request for ERC20 Tokens

Source: https://docs.allium.so/developer/data/optimism/raw/erc20-tokens

Provides a cURL command to perform a GET request to the Allium.so API. This example retrieves raw ERC20 token data for a specified blockchain `chain` using an API key.

```curl
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/raw/erc20-tokens \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Hyperliquid Trade Fills Data Payload Example

Source: https://docs.allium.so/historical-data/supported-blockchains/hyperliquid/datastreams

Example JSON payload for combined trade and fill data on Hyperliquid. This structure enhances basic trade information with detailed fill specifics for both the buyer and seller, including closed PnL, fees, order IDs, and starting positions. Note that complete fill data may not always be available through this topic.

```json
{
  "payload": {
    "coin": "HYPE",
    "extra_fields": {
      "buyer": {
        "builder_fee": null,
        "closed_pnl": "-1.800181",
        "crossed": true,
        "dir": "Close Short",
        "fee": "0.019579",
        "fee_token": "USDC",
        "order_id": 104547724355,
        "start_position": "-92667.36"
      },
      "seller": {
        "builder_fee": null,
        "closed_pnl": "-0.019941",
        "crossed": false,
        "dir": "Close Long",
        "fee": "-0.002996",
        "fee_token": "USDC",
        "order_id": 104547723702,
        "start_position": "7.04"
      }
    },
    "hash": "0x011483d2e4dac0c9df710425ed622a01c2009d120eb4a007cd3812dad4521c9c",
    "px": "34.566",
    "side": "B",
    "sz": "2.89",
    "tid": 1085099771108828,
    "time": 1750478864336,
    "users": [
      "0xefd3ab65915e35105caa462442c9ecc1346728df",
      "0x4fb31d5ffaa08be2128cb14485584d76eebef173"
    ]
  }
}
```

--------------------------------

### cURL Example to Get ERC20 Token Data

Source: https://docs.allium.so/developer/data/polygon/raw/erc20-tokens

Demonstrates how to make a GET request using cURL to retrieve ERC20 token metadata from the Allium API. This example requires an API key for authentication, which should be replaced with your actual key.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/raw/erc20-tokens \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Initiate Asynchronous Query Run (General Example)

Source: https://docs.allium.so/explorer/api/execute-query-async

This section provides a cURL code example for initiating an asynchronous query run. It demonstrates the basic request structure including content type, API key, and a minimal request body with parameters and run configuration.

```cURL
curl --request POST \
  --url https://api.allium.so/api/v1/explorer/queries/{query_id}/run-async \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "parameters": {},
  "run_config": {
    "limit": 123
  }
}'
```

--------------------------------

### Python Kafka Consumer for Allium Data Streams

Source: https://docs.allium.so/datastreams/kafka

This Python script demonstrates how to set up and run a Kafka consumer to access real-time data from Allium. It configures the consumer with essential parameters including security protocols, subscribes to specified topics, and includes a robust loop for polling and processing messages, handling Kafka-specific errors like partition EOF. Users need to replace placeholder values for `bootstrap.servers`, `group.id`, `username`, and `password` with their actual Allium Kafka credentials.

```python
import sys
from confluent_kafka import Consumer, KafkaError, KafkaException

consumer = Consumer(
    {
        "bootstrap.servers": "Your Bootstrap Servers",
        "group.id": "Your Group ID",
        "security.protocol": "SASL_SSL",
        "sasl.mechanisms": "PLAIN",
        "sasl.username": "Your Username",
        "sasl.password": "Your Password",
        "auto.offset.reset": "latest",
    }
)

def msg_process(msg):
    print(msg.value())
    # do stuff

def consume_loop(consumer, topics):
    try:
        consumer.subscribe(topics)
        while True:
            msg = consumer.poll(timeout=1.0)
            if msg is None: continue

            if msg.error():
                if msg.error().code() == KafkaError._PARTITION_EOF:
                    sys.stderr.write('%% %s [%d] reached end at offset %d\n' %
                                     (msg.topic(), msg.partition(), msg.offset()))
                elif msg.error():
                    raise KafkaException(msg.error())
            else:
                # msg_process(msg)
                pass
    finally:
        # Close down consumer to commit final offsets.
        consumer.close()

consume_loop(consumer, ["hyperliquid.misc_events"])
```

--------------------------------

### Example cURL GET Request for ERC20 Tokens

Source: https://docs.allium.so/developer/data/ethereum/raw/erc20-tokens

Demonstrates how to make a GET request to the Allium.so API using cURL. This example retrieves ERC20 token data for a specified blockchain `chain` and requires an API key for authentication.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/raw/erc20-tokens \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Example MCP Request to Run Saved Explorer Query

Source: https://docs.allium.so/assistant/allium-mcp

This JSON payload demonstrates how an LLM agent invokes the 'explorer_run_query' tool via the Model Context Protocol (MCP). It specifies the 'query_id' of a pre-saved Allium Explorer SQL query and optionally includes 'parameters' for parameterized queries.

```JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "explorer_run_query",
    "arguments": {
      "query_id": "<YOUR_QUERY_ID>"
      /* "parameters": { "param_name": "value", ... } // optional */
    }
  }
}
```

--------------------------------

### Example Successful JSON Response for Get Filter by ID

Source: https://docs.allium.so/developer/data-transformations/filters/get-filter

An example of the JSON payload returned upon a successful retrieval of a filter. It includes the filter's unique identifier and an empty filter object placeholder, illustrating the basic structure of the response.

```JSON
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "filter": {}
}
```

--------------------------------

### Example Request for frontendOpenOrders

Source: https://docs.allium.so/historical-data/supported-blockchains/hyperliquid/api

A JSON example demonstrating the structure of the request payload required to query a user's open orders using the frontendOpenOrders endpoint. It specifies the request type and the user's address.

```JSON
{
	"type": "frontendOpenOrders",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}
```

--------------------------------

### cURL Example to Get ERC721 Tokens Raw Data

Source: https://docs.allium.so/developer/data/polygon/raw/erc721-tokens

Illustrates how to make a GET request to the ERC721 tokens raw data API using cURL. This example includes the necessary 'X-API-KEY' header for authentication, which must be replaced with a valid API key.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/raw/erc721-tokens \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Example Response for openOrders API

Source: https://docs.allium.so/historical-data/supported-blockchains/hyperliquid/api

Provides a sample JSON array representing the response from the openOrders API, detailing multiple open orders for a user.

```json
[
	{
		"coin": "SPX",
		"side": "A",
		"limitPx": "1.2257",
		"sz": "962.3",
		"oid": 105776978379,
		"timestamp": 1750755964151,
		"origSz": "962.3",
		"cloid": "0x17507559639529516246375212044205"
	},
	{
		"coin": "SPX",
		"side": "A",
		"limitPx": "1.2253",
		"sz": "962.9",
		"oid": 105776978378,
		"timestamp": 1750755964151,
		"origSz": "962.9",
		"cloid": "0x17507559639529316246375212044205"
	},
	{
		"coin": "SPX",
		"side": "B",
		"limitPx": "1.2229",
		"sz": "962.9",
		"oid": 105776978377,
		"timestamp": 1750755964151,
		"origSz": "962.9",
		"cloid": "0x17507559639529216246375212044205"
	},
	{
		"coin": "DOGE",
		"side": "A",
		"limitPx": "0.16352",
		"sz": "371611.0",
		"oid": 105776977010,
		"timestamp": 1750755963751,
		"origSz": "371611.0",
		"cloid": "0x17507559635115391326505820107857"
	},
	{
		"coin": "DOGE",
		"side": "B",
		"limitPx": "0.16334",
		"sz": "371611.0",
		"oid": 105776977009,
		"timestamp": 1750755963751,
		"origSz": "371611.0",
		"cloid": "0x17507559635115291326505820107857"
	},
	{
		"coin": "SEI",
		"side": "B",
		"limitPx": "0.2836",
		"sz": "20835.0",
		"oid": 105776974611,
		"timestamp": 1750755963130,
		"origSz": "20835.0",
		"cloid": "0x17507559629647803449121614997909"
	},
	{
		"coin": "SEI",
		"side": "A",
		"limitPx": "0.2845",
		"sz": "20835.0",
		"oid": 105776974610,
		"timestamp": 1750755963130,
		"origSz": "20835.0",
		"cloid": "0x17507559629647303449121614997909"
	},
	{
		"coin": "SEI",
		"side": "B",
		"limitPx": "0.28386",
		"sz": "20835.0",
		"oid": 105776974609,
		"timestamp": 1750755963130,
		"origSz": "20835.0",
		"cloid": "0x17507559629647203449121614997909"
	},
	{
		"coin": "VIRTUAL",
		"side": "A",
		"limitPx": "1.6541",
		"sz": "4126.0",
		"oid": 105776973789,
		"timestamp": 1750755962927,
		"origSz": "4126.0",
		"cloid": "0x17507559628603995268977069835943"
	},
	{
		"coin": "VIRTUAL",
		"side": "B",
		"limitPx": "1.6486",
		"sz": "4126.0",
		"oid": 105776973788,
		"timestamp": 1750755962927,
		"origSz": "4126.0",
		"cloid": "0x17507559628603895268977069835943"
	},
	{
		"coin": "VIRTUAL",
		"side": "A",
		"limitPx": "1.6536",
		"sz": "4126.0",
		"oid": 105776973787,
		"timestamp": 1750755962927,
		"origSz": "4126.0",
		"cloid": "0x17507559628603795268977069835943"
	},
	{
		"coin": "VIRTUAL",
		"side": "B",
		"limitPx": "1.6491",
		"sz": "4126.0",
		"oid": 105776973786,
		"timestamp": 1750755962927,
		"origSz": "4126.0",
		"cloid": "0x17507559628603695268977069835943"
	},
	{
		"coin": "VIRTUAL",
		"side": "A",
		"limitPx": "1.6531",
		"sz": "4126.0",
		"oid": 105776973785,
		"timestamp": 1750755962927,
		"origSz": "4126.0",
		"cloid": "0x17507559628603595268977069835943"
	},
	{
		"coin": "VIRTUAL",
		"side": "B",
		"limitPx": "1.6496",
		"sz": "4126.0",
		"oid": 105776973784,
		"timestamp": 1750755962927,
		"origSz": "4126.0",
		"cloid": "0x17507559628603495268977069835943"
	},
	{
		"coin": "VIRTUAL",
		"side": "A",
		"limitPx": "1.6526",
		"sz": "4126.6",
		"oid": 105776973783,
		"timestamp": 1750755962927,
		"origSz": "4126.6",
		"cloid": "0x17507559628603395268977069835943"
	},
	{
		"coin": "VIRTUAL",
		"side": "B",
		"limitPx": "1.6501",
		"sz": "4126.6",
		"oid": 105776973782,
		"timestamp": 1750755962927,
		"origSz": "4126.6",
		"cloid": "0x17507559628603295268977069835943"
	},
	{
		"coin": "FARTCOIN",
		"side": "B",
		"limitPx": "1.0238",
		"sz": "6075.5",
		"oid": 105776973651,
		"timestamp": 1750755962927,
		"origSz": "6075.5",
		"cloid": "0x17507559627933660643675839412425"
	},
	{
		"coin": "FARTCOIN",
		"side": "A",
		"limitPx": "1.0265",
		"sz": "6075.5",
		"oid": 105776973650,
		"timestamp": 1750755962927,
		"origSz": "6075.5",
		"cloid": "0x17507559627933560643675839412425"
	},
	{
		"coin": "FARTCOIN",
		"side": "B",
		"limitPx": "1.0241",
		"sz": "6075.5",
		"oid": 105776973649,
		"timestamp": 1750755962927,
		"origSz": "6075.5",
		"cloid": "0x17507559627933460643675839412425"
	},
	{
		"coin": "FARTCOIN",
		"side": "A",
		"limitPx": "1.0262",
		"sz": "6076.2",
		"oid": 105776973648,
		"timestamp": 1750755962927,
		"origSz": "6076.2",
		"cloid": "0x17507559627933360643675839412425"
	},
	{
		"coin": "FARTCOIN",
		"side": "B",
		"limitPx": "1.0244",
		"sz": "6076.2",
		"oid": 105776973647,
		"timestamp": 1750755962927,
		"origSz": "6076.2",
		"cloid": "0x17507559627933260643675839412425"
	},
	{
		"coin": "WLD",
		"side": "A",
		"limitPx": "0.9327",
		"sz": "7267.1",
		"oid": 105776973184,
		"timestamp": 1750755962815,
		"origSz": "7267.1",
		"cloid": "0x17507559622671301213236824249599"
	},
	{
		"coin": "WLD",
		"side": "B",
		"limitPx": "0.9309",
		"sz": "7267.1",
		"oid": 105776973183,
		"timestamp": 1750755962815,
		"origSz": "7267.1",
		"cloid": "0x17507559622671201213236824249599"
	}
]
```

--------------------------------

### cURL Example to Get Raw Block Data

Source: https://docs.allium.so/developer/data/optimism/raw/blocks

Illustrates how to use cURL to perform a GET request to the Allium.so API's raw blocks endpoint. This example requires replacing `{chain}` and `{block_number}` with actual values and providing a valid API key in the `X-API-KEY` header.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/raw/blocks/{block_number} \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### bitcoin.assets.balances_latest Table Schema Reference

Source: https://docs.allium.so/historical-data/supported-blockchains/bitcoin-ecosystem/bitcoin/assets/latest-balances

This section details the schema for the `bitcoin.assets.balances_latest` table, providing a comprehensive list of all available columns. Each entry includes the column name, a description of its purpose, and an example value, which is essential for understanding the table's structure and the data it contains.

```APIDOC
Table: bitcoin.assets.balances_latest
Columns:
  - address:
      Description: Address of the account.
      Example: bc1qdm8s6drm6dkvfqczyneldq2zmw5995dg3hhvky
  - token_address:
      Description: Token address of the asset, 0x0000000000000000000000000000000000000000 for native token
      Example: 0x0000000000000000000000000000000000000000
  - token_name:
      Description: Name of the token.
      Example: BTC
  - token_symbol:
      Description: Token symbol of this token.
      Example: BTC
  - raw_balance:
      Description: Balance of tokens (unnormalized)
      Example: 15,834,706
  - raw_balance_str:
      Description: Balance of tokens (unnormalized) in string.
      Example: 15834706
  - balance_str:
      Description: Balance of the token, normalized by the decimal points defined by BTC protocol in sats. One sat = 1e-8 btc
      Example: 0.15834706
  - balance:
      Description: Balance of this token, normalized by the decimal points defined in the token contract.
      Example: 0.15834706
  - usd_balance_current:
      Description: The amount of tokens, in $USD at the current time
      Example: 5,373.119530803
  - usd_balance_at_block_timestamp:
      Description: The amount of tokens, in $USD at the price evaluated at the time of the block_timestamp
      Example: 5,403.393905204
  - usd_exchange_rate_current:
      Description: The exchange rate used to calculate the usd_value at current time
      Example: 33,932.55
  - usd_exchange_rate_at_block_timestamp:
      Description: The exchange rate used to calculate the usd_value at block_timestamp
      Example: 34,123.74
  - last_activity_block_timestamp:
      Description: The latest timestamp of the block that that resulted in change in balance.
      Example: 2023-10-24 09:34:58
  - last_activity_block_number:
      Description: The number of the latest block that resulted in change in balance.
      Example: 813,624
  - last_activity_block_hash:
      Description: The hash of the latest block that resulted in change in balance.
      Example: 00000000000000000003306de67b0a54e98ef716b46b012d4d0937286e38d577
  - _updated_at__usd_exchange_rate_current:
      Description: Time the usd exchange rate was calculated
      Example: 2023-10-24 17:00:00
  - _updated_at__unhydrated:
      Description: Time the raw balance was calculated
      Example: 2023-10-24 18:17:07
  - _updated_at:
      Description: Time the row was updated
      Example: 2023-10-24 18:17:07
  - unique_id:
      Description: Unique ID of the balances entry
      Example: block-20755138_address-0xe6c27255fbb9d3a9718fb5e2dc313cd6eba10b78_eth
```

--------------------------------

### cURL Example: Retrieve Filter Data Source

Source: https://docs.allium.so/developer/data-transformations/filter-data-sources/get-data-source

Demonstrates how to make a GET request to the Allium API using cURL to fetch a filter data source by its ID. This example requires replacing '{data_source_id}' with an actual ID and '<api-key>' with a valid Allium API key.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/streams/data-management/filter-data-sources/{data_source_id} \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Example JSON Response for Get All Filters

Source: https://docs.allium.so/developer/data-transformations/filters/get-filters

A sample JSON response illustrating the structure of data returned upon a successful request to the Get All Filters endpoint. It includes a unique identifier and a placeholder for the filter object.

```JSON
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "filter": {}
}
```

--------------------------------

### API Documentation for Ethereum Asset Balances Latest Table Columns

Source: https://docs.allium.so/historical-data/supported-blockchains/evm/ethereum/assets/balances-latest

This section provides a detailed description of the columns available in the `ethereum.assets.balances_latest` table, including their data types, descriptions, and examples. It serves as an API documentation for understanding the schema of asset balance data.

```APIDOC
Table: ethereum.assets.balances_latest

Columns:
- address (string): Address of the account. Example: 0x66a84d487780c088d862971045d84b02d9b25aab
- token_address (string): Address of the token. For Ether it is represented as null address. Example: 0x0000000000000000000000000000000000000000
- token_name (string): Name of the token. Example: ETH
- token_symbol (string): Symbol of the token. Example: ETH
- token_id (string): Token ID of a ERC721 token or ERC1155 token.
- raw_balance (string): Raw balance amount of the token (not divided by the number of decimals). Example: 216,765,847,229,634
- raw_balance_str (string): Raw balance amount of the token (not divided by the number of decimals) in string. Example: 216765847229634
- balance (float): `raw_balance` divided by the number of decimals of this token. This value will be the same as raw_balance for erc721 and erc1155 tokens. Example: 0.0002167658472
- balance_str (string): Balance of token normalized and in string format. Example: 0.0002167658472
- usd_balance_current (float): USD balance of token at the current timestamp. Example: 0.308804626
- usd_balance_at_block_timestamp (float): USD balance of token at the timestamp of the last activity that resulted in balance change. Example: 0.2800939895
- usd_exchange_rate_current (float): USD exchange rate of token at the current timestamp. Example: 1,424.60
- usd_exchange_rate_at_block_timestamp (float): USD exchange rate of token at the timestamp of the last activity that resulted in balance update. Example: 1,292.15
- transaction_hash (string): The transaction hash that resulted in the balance update. Example: 0xb2bf75bdb376ab2c59fdfed688355bc4b3b20d2e71d3ec6ff8e3a6b47f3894dc
- last_activity_block_timestamp (datetime): The last timestamp of the block that that resulted in the balance update. Example: 2022-12-05 03:58:11
- last_activity_block_number (integer): The last block number that resulted in the balance update. Example: 16,116,061
- last_activity_block_hash (string): The block hash of the last activity that resulted in this balance. Example: 0x49ae37a2a5feb07d3f237dbfe4af59abb3b9ef19e3cd47ef083f1d7e45a2e616
- _updated_at__usd_exchange_rate_current (datetime): Timestamp of the current USD exchange. Example: 2023-03-10 22:00:00
- unique_id (string): Unique ID of the balance. Example: block-16116061_address-0x66a84d487780c088d862971045d84b02d9b25aab_eth
- _updated_at (datetime): Timestamp of the balance update. Example: 2023-03-10 10:18:07
```

--------------------------------

### Example Request for openOrders API

Source: https://docs.allium.so/historical-data/supported-blockchains/hyperliquid/api

Illustrates the JSON payload required to query a user's open orders using the openOrders API endpoint.

```json
{
	"type": "openOrders",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}
```

--------------------------------

### cURL Example: Get ERC20 Token Metadata

Source: https://docs.allium.so/developer/data/base/raw/erc20-tokens

Provides a cURL command example to fetch ERC20 token metadata from the API, demonstrating how to include the API key.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/raw/erc20-tokens \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Retrieve Workflow using cURL

Source: https://docs.allium.so/developer/data-transformations/workflows/get-workflow

Example cURL command to make a GET request to the Allium API to fetch a workflow by its ID, requiring an API key for authentication.

```curl
curl --request GET \
  --url https://api.allium.so/api/v1/streams/data-management/workflows/{id} \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Bitcoin Credit Debit Table Schema Reference

Source: https://docs.allium.so/historical-data/supported-blockchains/bitcoin-ecosystem/bitcoin/assets/credit-debit

This section defines the structure and available columns of the `bitcoin.assets.btc_credit_debit` table. Each entry details a column's name, its purpose, and provides an example value, which is essential for understanding the data returned by queries.

```APIDOC
Table: bitcoin.assets.btc_credit_debit
  address: string
    Description: Address of the account.
    Example: bc1q6kglpx6h6f5a5nljr0u3pfnpgwkp7q4340mcs9
  value: integer
    Description: Change of value to the address.
    Example: -91,224
  block_timestamp: timestamp
    Description: The timestamp of the block that that resulted in change in balance.
    Example: 2023-10-24 09:34:58
  block_number: integer
    Description: The number of the block that resulted in change in balance.
    Example: 813,624
  block_hash: string
    Description: The hash of block that resulted in change in balance.
    Example: 00000000000000000003306de67b0a54e98ef716b46b012d4d0937286e38d577
  transaction_index: integer
    Description: Index of the transaction that resulted in the change in balance.
    Example: 3,703
  transaction_hash: string
    Description: Hash of the transaction that resulted in the change in balance.
    Example: c7de8299741c7bec5e8bf5f602e6d3ae0970d5f56c65b09e10ab5937afd6762c
  input_index: integer or NULL
    Description: Index of the inputs that resulted in the change in balance (debit).
    Example: 12 or NULL
  output_index: integer or NULL
    Description: Index of the output that resulted in the change in balance (credit).
    Example: 123 or NULL
  unique_id: string
    Description: Unique ID of the credit debit entry.
    Example: output-150
```

--------------------------------

### Retrieve a Filter using cURL

Source: https://docs.allium.so/developer/data-transformations/filters/get-filter

Example cURL command to make a GET request to the Allium API to retrieve a filter by its ID. This request requires an `X-API-KEY` header for authentication.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/streams/data-management/filters/{id} \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Allium API Endpoints Overview

Source: https://docs.allium.so/developer/data/optimism/raw/traces

This section provides a structured overview of various API endpoints available on the Allium platform, categorized by their functionality such as Prices, Wallets, NFT, Direct Data Access, and Optimism Raw Data. Each entry specifies the HTTP method and the relative path.

```APIDOC
Prices:
  POST Token Latest Price (/developer/prices/token-latest-price)
  POST Token Price Historical (/developer/prices/token-price-history)
  POST Token Price Stats (/developer/prices/token-price-stats)
Wallets:
  POST Wallet Transactions (/developer/wallets/transactions)
  POST Latest Fungible Token Balances (/developer/wallets/latest-token-balances)
  POST Latest NFT Balances (/developer/wallets/latest-nft-balances)
  POST Latest Solana NFT Balances (/developer/wallets/latest-sol-balances)
  POST Historical Fungible Token Balances (/developer/wallets/historical-token-balances)
  POST Holdings History (/developer/holdings/holdings-history)
  POST PnL (/developer/holdings/holdings-pnl)
NFT:
  GET NFT Tokens by Contract (/developer/nft/get-nft-by-contract)
  GET NFT Token by Contract and Token ID (/developer/nft/nft-token-by-contract)
  GET NFT Contract (/developer/nft/nft-contract)
  GET NFT Collections (/developer/nft/nft-collections)
  GET NFT Listings by Contract Address (/developer/nft/nft-listings)
  GET NFT Listings by Token ID (/developer/nft/nft-listings-by-token)
  GET NFT Activities by Token ID (/developer/nft/nft-activities-token)
  GET NFT Activities by Contract Address (/developer/nft/nft-activities-contract)
Direct Data Access:
  POST Custom SQL API (/developer/direct-data-access/custom-sql-api)
Optimism Raw Data:
  GET Blocks (/developer/data/optimism/raw/blocks)
  GET Transactions (/developer/data/optimism/raw/transactions)
  GET Logs (/developer/data/optimism/raw/logs)
  GET Traces (/developer/data/optimism/raw/traces)
  GET ERC20 tokens (/developer/data/optimism/raw/erc20-tokens)
  GET ERC721 tokens (/developer/data/optimism/raw/erc721-tokens)
  GET ERC1155 tokens (/developer/data/optimism/raw/erc1155-tokens)
```

--------------------------------

### Successful Filter Retrieval API Response

Source: https://docs.allium.so/developer/data-transformations/filters/get-filter

Example JSON response body for a successful GET request to retrieve a filter. It includes the unique `id` of the retrieved filter and a `filter` object.

```JSON
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "filter": {}
}
```

--------------------------------

### LangGraph/LangChain Agent Tool Configuration for Allium MCP

Source: https://docs.allium.so/assistant/allium-mcp

This JSON snippet illustrates how to configure an agent framework (e.g., LangGraph, LangChain) to register the `explorer_run_query` tool with the Allium MCP server. It defines the tool's name, the MCP server endpoint, and includes an API key for authentication, enabling the agent to call Explorer queries.

```json
{
  "tools": [
    {
      "name": "explorer_run_query",
      "server": "https://mcp.allium.so",
      "headers": {
        "X-API-KEY": "<YOUR_API_KEY>"
      }
    }
  ]
}
```

--------------------------------

### cURL Example to Get ERC20 Token Data

Source: https://docs.allium.so/developer/data/optimism/raw/erc20-tokens

Demonstrates how to make a GET request to the ERC20 token data API endpoint using cURL. Requires an API key for authentication.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/developer/{chain}/raw/erc20-tokens \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Identify Rainbow Wallet Funding Sources

Source: https://docs.allium.so/historical-data/wallet-360

This SQL query identifies the initial funding sources for Ethereum wallets tagged as 'Rainbow Wallet'. It joins the `ethereum.wallet_features.wallet_360` table with `common.identity.entities` to determine the project and category of the first funding address, then counts the number of wallets for each source.

```SQL
select
    nvl(entities.project, 'Unknown') as funder,
    nvl(entities.category, 'Unknown') as funder_category,
    count(1) as wallet_count
from ethereum.wallet_features.wallet_360
left join common.identity.entities on first_funding_address = address and chain = 'ethereum'
where array_contains('rainbow_wallet'::variant, app_list)
group by all
order by 1 asc
```

--------------------------------

### Allium Explorer API Endpoints and Asynchronous Query Workflow

Source: https://docs.allium.so/explorer/api/explorer-api-user-tutorial

This section outlines the core REST API endpoints for the Allium Explorer, enabling asynchronous query execution, status polling, and result retrieval. It describes the typical sequence of operations: initiating a query run, polling its status until success, and then fetching the results.

```APIDOC
API Endpoints:
1. POST /api/v1/explorer/queries/{query_id}/run-async:
   - Description: Execute the query asynchronously. This creates a query run ID for you to poll the status and results from.
2. GET /api/v1/explorer/query-runs/{run_id}/status:
   - Description: Get the status of a query run.
   - Possible Statuses: created | queued | running | success | failed | canceled
3. GET /api/v1/explorer/query-runs/{run_id}/results:
   - Description: Get the results of a query run with status 'success'.

Typical Workflow:
1. Create a query run, and get the run_id.
2. Poll the query run status using the run_id in a while loop.
3. When the query run status is 'success', get the results.
```

--------------------------------

### Get All Filters using cURL

Source: https://docs.allium.so/developer/data-transformations/filters/get-filters

Example cURL command to retrieve all filters from the Allium API. This request requires an `X-API-KEY` header for authentication. Replace `<api-key>` with your actual Allium API key.

```cURL
curl --request GET \
  --url https://api.allium.so/api/v1/streams/data-management/filters \
  --header 'X-API-KEY: <api-key>'
```

```Python
# Python example for Get All Filters (not provided in source)
```

```JavaScript
// JavaScript example for Get All Filters (not provided in source)
```

```PHP
// PHP example for Get All Filters (not provided in source)
```

```Go
// Go example for Get All Filters (not provided in source)
```

```Java
// Java example for Get All Filters (not provided in source)
```

--------------------------------

### API Documentation: Allium.so Lending Data Models

Source: https://docs.allium.so/historical-data/supported-blockchains/evm/core-schemas

Documents the data models for complete coverage of on-chain lending activity, total locked value, and interest rates, including daily TVL snapshots, detailed interest rate data, deposit/withdrawal tracking, loan records, repayment documentation, and liquidation events.

```APIDOC
TVL Daily: Delivers daily snapshots of Total Value Locked in lending markets with token-level breakdowns for market size and utilization analysis
Interest Rates: Provides detailed interest rate data including supply APY, borrow rates, and market conditions from Aave, Compound, and Morpho Blue for yield analysis
Deposits: Tracks deposit events across major lending protocols including Aave and Compound, capturing deposit amounts, token details, and participant addresses
Withdrawals: Monitors withdrawal events from lending protocols with complete data on withdrawn amounts, tokens, and user addresses for liquidity analysis
Loans: Records borrowing activity from leading lending platforms, with comprehensive data on loan amounts, terms, borrower addresses, and collateralization
Repayments: Documents loan repayment transactions with detailed information on repaid amounts, outstanding balances, and borrower activity
Liquidations: Captures liquidation events with data on liquidated collateral, repaid debt, liquidators, and borrowers across all major lending protocols
```

--------------------------------

### Example Query Run Status Response

Source: https://docs.allium.so/explorer/api/get-query-run-status

An example of a successful response from the Get Query Run Status API endpoint, showing a typical status value returned as a JSON string.

```JSON
"created"
```

--------------------------------

### cURL Example: Retrieve All Workflows

Source: https://docs.allium.so/developer/data-transformations/workflows/get-workflows

A practical cURL command demonstrating how to make a GET request to the Allium API to retrieve all data transformation workflows. Remember to replace `<api-key>` with your actual API key.

```curl
curl --request GET \
  --url https://api.allium.so/api/v1/streams/data-management/workflows \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### Calculate Stablecoin Holdings for OpenSea Users

Source: https://docs.allium.so/historical-data/wallet-360

This SQL query categorizes OpenSea users by their total USD balance tiers and calculates the average stablecoin holdings within each tier. It uses a `CASE` statement to define balance ranges and groups by these tiers to provide insights into stablecoin distribution among OpenSea users.

```SQL
  select
      case
          when total_usd_balance = 0 or total_usd_balance is null then 'Null'
          when total_usd_balance <= 1000 then 'a. <=1k'
          when total_usd_balance > 1000 and total_usd_balance <= 10000 then 'b. 1-10k'
          when total_usd_balance > 10000 and total_usd_balance <= 100000 then 'c. 10-100k'
          when total_usd_balance > 100000 and total_usd_balance <= 1000000 then 'd. 100k-1m'
          when total_usd_balance > 1000000 then 'e. >1m'
      end as balance_tier,
      avg(stablecoin_usd_balance) as avg_stable_balance,
      count(1) as count_all
  from ethereum.wallet_features.wallet_360
  where array_contains('opensea_nft_marketplace'::variant, app_list)
  group by all
  order by 1 asc
```