Structure

General strucure used for all apis

Base URL & Versioning

Base URL: https://api.defistream.dev/v1

All endpoints are prefixed with /v1/. The version prefix ensures backwards compatibility as the API evolves.

Request Format

All API endpoints use HTTP GET requests with query parameters.

Common Parameters

*Either block range (block_start + block_end) OR time range (since + until) is required, but not both.

Block Range vs Time Range

You must specify either a block range or a time range:

Block Range:

?network=ETH&block_start=24000000&block_end=24010000

Time Range:

?network=ETH&since=2024-01-01T00:00:00Z&until=2024-01-01T01:00:00Z

Time range accepts:

• ISO 8601 format: 2024-01-15T10:30:00Z
• Unix timestamp (seconds): 1705315800

Value Column

Pass with_value=true to add USD value to applicable events.

• Individual event endpoints: Adds value_usd (amount × price) column to each event.
• Aggregate endpoints: When a protocol’s aggregatable columns include value_usd, the aggregation produces agg_value_usd (sum per bucket). Without with_value=true, these columns are absent and aggregation skips them gracefully (no errors).
• Supported protocols: aave_v3, uniswap_v3, lido, erc20, native_token
• Prices used are estimates and gathered primarily from Binance

Address Label & Category Filters

Filter events by known entity names or categories instead of raw addresses. This allows filtering blockchain addresses by their tagged labels (e.g., “Binance”) and categories (e.g., “exchange”, “whale”).

How Matching Works

• Labels use involving_label (and sender_label and received_labels in relevant events) to filter addresses for labels (e.g. involving_label=Deposit)
• Categories similar to label, you can use involving_categoy (and sender and receiver varients) (e.g. involving_category=exchange)
• Multi-value support: For most events, comma-separated values are accepted (e.g., sender_label=Binance,Coinbase)
• Case Insensitive support: all the variations of coinbase, Coinbase returns same results

Mutual Exclusivity Rules

Within each slot (involving/sender/receiver), only one of address/label/category can be set:

• involving vs involving_label vs involving_category — pick one
• sender vs sender_label vs sender_category — pick one
• receiver vs receiver_label vs receiver_category — pick one

Additionally, involving* filters cannot be combined with sender*/receiver* filters.

Output Formats

Per-Provider Range Limits

Time range limits apply to all output formats. Block range limits vary by format as shown above.

JSON (Default)

• Max block range: 10,000 blocks (all providers)
• Best for: Small queries, real-time applications
• Time fields are ISO 8601 formatted

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24010000&token=USDT&format=json"

CSV

• Max block range: Per-provider (see table above)
• Best for: Spreadsheet analysis, data export
• Streams in chunks for memory efficiency

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24100000&token=USDT&format=csv" 
  -o transfers.csv

Parquet

• Max block range: Per-provider (see table above)
• Best for: Large-scale analysis, data pipelines
• Columnar format with excellent compression
• Recommended for queries over 10K blocks

curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24100000&token=USDT&format=parquet" 
  -o transfers.parquet

Link Mode (File Sharing)

When link=true is combined with format=csv or format=parquet, the file is uploaded to a temporary file sharing service and a JSON response with the download link is returned instead of the file itself.

• Supported formats: csv, parquet only
• File expiry: 1 hour
• Use case: Share data files with others without downloading first, or for programmatic access to large files

Example:

# Get a shareable link for CSV data
curl -H "X-API-Key: $API_KEY" 
  "https://api.defistream.dev/v1/erc20/events/transfer?network=ETH&block_start=24000000&block_end=24100000&token=USDT&format=csv&link=true"

Response:

{
    "filename": "erc20_transfer_ETH_24000000_24100000.csv",
    "link": "https://dl.defistream.dev/dh/abc123/erc20_transfer_ETH_24000000_24100000.csv",
    "expiry": "2026-02-03 14:30:00",
    "size": "1.29 MB"
}

Verbose Mode

When verbose=true, responses include additional fields:

• name: Event type name
• network: Network identifier
• tx_hash / tx_id: Transaction hash
• log_index: Log index within the transaction

Default (verbose=false) omits these fields to reduce payload size.

Response Format

Success Response (JSON)

{
  "status": "success",
  "events": [
    {
      "block_number": 24000001,
      "time": "2024-07-15T10:30:00Z",
      "token": "USDT",
      "sender": "0x1234...5678",
      "receiver": "0xabcd...ef01",
      "amount": 10000.0
    }
  ],
  "count": 1
}

Error Response

{
  "status": "error",
  "events": [],
  "count": 0,
  "error": "Description of the error"
}

HTTP Status Codes