Explore unified inferred swaps

This tutorial demonstrates how to use our Swaps REST API to retrieve inferred swap data across different blockchains, tokens, and pairs. Inferred swaps are generated by matching token sender and receiver across 2 different tokens in same transation. They may provide some general information about the swap fact but for more detailed information you may want to explore decoded swaps documentation.

API Endpoint

https://api.heimdahl.xyz/v1/swaps/list/{path}

Note: This API requires authentication using a Bearer token.

Path Format

The path follows this pattern:

{chain}.{network}.{token1}.{token2}.all

Where:

• chain: Blockchain (ethereum, polygon, base, binance, solana, arbitrum, tron)

• network: Network type (mainnet, testnet, etc.)

• token1: First token symbol (USDC, USDT, WETH, etc.)

• token2: Second token symbol (USDC, USDT, WETH, etc.)

• The final parameter is all, reserved for size bucket filtering (not currently active).

Example Usage

Bash

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.heimdahl.xyz/v1/swaps/list/{path}?page=0&pageSize=2"

CLI

heimdahl swap list all.mainnet.usdc.weth.all --perPage=20

Sample curl reponse

The API returns swap data in JSON array format. Each swap entry contains:

[
  {
    "chain_name": "ethereum",
    "tx_hash": "0x3e78165e95accac994192c573fc3e34a93b79fe101fde33a1dd53c2f28e7e44d",
    "timestamp": 1741969405,
    "token1_address": "0x5050e08626c499411B5D0E0b5AF0E83d3fD82EDF",
    "token1_symbol": "USDC",
    "token1_decimals": 6,
    "token2_address": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640",
    "token2_symbol": "WETH",
    "token2_decimals": 18,
    "token1_sender": "0x5050e08626c499411B5D0E0b5AF0E83d3fD82EDF",
    "token2_sender": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640",
    "token1_amount": 24957115193,
    "token2_amount": 12947804764536934000,
    "price_token1_in_token2": 1927517107,
    "price_token2_in_token1": 518802139766881000000000000
  },
  {
    "chain_name": "ethereum",
    "tx_hash": "0x8713e0df807c48d9396e5b017f73e896c4502f7d904328c5c556886744c328a4",
    "timestamp": 1741969405,
    "token1_address": "0xA69babEF1cA67A37Ffaf7a485DfFF3382056e78C",
    "token1_symbol": "USDC",
    "token1_decimals": 6,
    "token2_address": "0xE0554a476A092703abdB3Ef35c80e0D76d32939F",
    "token2_symbol": "WETH",
    "token2_decimals": 18,
    "token1_sender": "0xA69babEF1cA67A37Ffaf7a485DfFF3382056e78C",
    "token2_sender": "0xE0554a476A092703abdB3Ef35c80e0D76d32939F",
    "token1_amount": 7309553024,
    "token2_amount": 3794441433022390000,
    "price_token1_in_token2": 1926384463,
    "price_token2_in_token1": 519107176671927460000000000
  }
]

Field Descriptions:

• chain_name: Blockchain name

• tx_hash: Transaction hash of the swap

• timestamp: Unix timestamp of the swap

• token1_address: Contract address of the first token

• token1_symbol: Symbol of the first token

• token1_decimals: Number of decimal places for token1

• token2_address: Contract address of the second token

• token2_symbol: Symbol of the second token

• token2_decimals: Number of decimal places for token2

• token1_sender: Address sending token1

• token2_sender: Address sending token2

• token1_amount: Amount of token1 swapped

• token2_amount: Amount of token2 swapped

• price_token1_in_token2: Price of token1 denominated in token2 (scaled number)

• price_token2_in_token1: Price of token2 denominated in token1 (scaled number)

Pagination Parameters

• page: The page number (starting from 0)

• pageSize: Number of results per page