Discovery Endpoints

Use these endpoints to explore available protocols and their capabilities.

List All Protocols

Endpoint: GET /v1/protocols

Returns a list of all available protocol identifiers.

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/protocols"

Response:

["native_token", "erc20", "aave_v3", "uniswap_v3", "lido"]

List Tokens

Endpoint: GET /v1/tokens

Returns all supported ERC20 token symbols with their metadata.

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/tokens"

Response:

[
  {"symbol": "USDT", "name": "Tether", "aliases": ["tether"], ...},
  {"symbol": "USDC", "name": "USD Coin", "aliases": ["usd-coin"], ...},
  ...
]

List Supported Networks

Endpoint: GET /v1/{protocol}/networks

Returns networks supported by the specified protocol.

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/erc20/networks"

Response:

["ETH", "ARB", ...]

List Event Types

Endpoint: GET /v1/{protocol}/events/types

Returns event types available for the specified protocol.

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/aave_v3/events/types"

Response:

["deposit", "withdraw", "borrow", "repay", "flashloan", "liquidation"]

Get Parameter Schema

Endpoint: GET /v1/{protocol}/extra_args

Returns the schema for protocol-specific parameters.

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/uniswap_v3/extra_args"

Response:

{
  "symbol0": {
    "description": "First token symbol in the pool (e.g., 'WETH')",
    "type": "string",
    "required": true
  },
  "symbol1": {
    "description": "Second token symbol in the pool (e.g., 'USDC')",
    "type": "string",
    "required": true
  },
  "fee": {
    "description": "Pool fee tier in basis points",
    "type": "integer",
    "enum": [100, 500, 3000, 10000],
    "required": true
  }
}

Get Aggregate Schema

Endpoint: GET /v1/{protocol}/aggregate_schema

Returns which event types support aggregation and what columns are available.

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/aave_v3/aggregate_schema"

Response:

{
  "deposit": {
    "columns": [
      {"source_column": "amount", "aggregation": "sum", "output_column": "agg_amount"},
      {"source_column": "value_usd", "aggregation": "sum", "output_column": "agg_value_usd"}
    ],
    "always_included": ["count"]
  },
  "borrow": {
    "columns": [
      {"source_column": "amount", "aggregation": "sum", "output_column": "agg_amount"},
      {"source_column": "borrow_rate", "aggregation": "mean", "output_column": "mean_borrow_rate"},
      {"source_column": "value_usd", "aggregation": "sum", "output_column": "agg_value_usd"}
    ],
    "always_included": ["count"]
  }
}

For protocols with pivot columns (e.g., Uniswap), the schema includes a pivot_columns field describing dynamic per-token output columns:

{
  "swap": {
    "columns": [
      {"source_column": "sqrt_based_price", "aggregation": "mean", "output_column": "mean_sqrt_based_price"},
      {"source_column": "liquidity", "aggregation": "mean", "output_column": "mean_liquidity"}
    ],
    "pivot_columns": [
      {"value_column": "amountSold", "key_column": "tokenSold", "aggregation": "sum", "suffix": "sold", "output_pattern": "agg_<TOKEN>_sold"},
      {"value_column": "amountBought", "key_column": "tokenBought", "aggregation": "sum", "suffix": "bought", "output_pattern": "agg_<TOKEN>_bought"}
    ],
    "always_included": ["count"]
  }
}

<TOKEN> is replaced by the actual token symbol found in the data (e.g., agg_WETH_sold, agg_USDC_bought).

An empty object {} means the protocol has no aggregatable event types.

Calculate Cost

Endpoint: POST /v1/calculate-cost

Estimate the cost of a query before executing it. Returns the block cost and your remaining quota without deducting anything.

curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" 
  -d '{"query": "/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=USDT"}' 
  "https://api.defistream.dev/v1/calculate-cost"

Response:

{
  "query": "/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=USDT",
  "cost": 10000,
  "quota_remaining": 500000,
  "quota_remaining_after": 490000,
  "breakdown": {
    "network": "eth",
    "network_discount": 1.0,
    "is_aggregate": false,
    "aggregate_discount": 1.0,
    "range_type": "block",
    "block_range": 10000,
    "estimated_from_time": false,
    "block_cost": 10000,
    "formula": "10,000 blocks = 10,000"
  }
}