Get Bridge Stats

curl --request GET \
  --url 'https://api.example.com/api/bridge-stats/[address]'

{
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "year": 2025,
  "generatedAt": "2025-03-15T14:30:00.000Z",
  "totalBridgingActions": 42,
  "totalVolumeUSD": 125430.50,
  "mostUsedSourceChain": {
    "chainId": 1,
    "chainName": "Ethereum",
    "count": 18,
    "percentage": 42.86,
    "volumeUSD": 0,
    "logo": "https://example.com/logos/ethereum.png"
  },
  "mostUsedDestinationChain": {
    "chainId": 42161,
    "chainName": "Arbitrum",
    "count": 15,
    "percentage": 35.71,
    "volumeUSD": 0,
    "logo": "https://example.com/logos/arbitrum.png"
  },
  "highestVolumeDestination": {
    "chainId": 42161,
    "chainName": "Arbitrum",
    "count": 15,
    "percentage": 35.71,
    "volumeUSD": 85230.25,
    "logo": "https://example.com/logos/arbitrum.png"
  },
  "mostBridgedToken": {
    "symbol": "USDC",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "count": 28,
    "totalVolumeUSD": 95600.00,
    "percentage": 66.67,
    "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png"
  },
  "busiestDay": {
    "date": "2025-06-15",
    "count": 8,
    "primaryDestination": {
      "chainId": 42161,
      "chainName": "Arbitrum",
      "count": 5
    }
  },
  "providerBreakdown": {
    "across": {
      "count": 25,
      "volumeUSD": 78500.25
    },
    "relay": {
      "count": 12,
      "volumeUSD": 35200.00
    },
    "lifi": {
      "count": 5,
      "volumeUSD": 11730.25
    }
  },
  "monthlyActivity": [
    {
      "month": "2025-01",
      "monthName": "January",
      "count": 5,
      "volumeUSD": 15230.50
    },
    {
      "month": "2025-02",
      "monthName": "February",
      "count": 3,
      "volumeUSD": 8400.00
    },
    {
      "month": "2025-03",
      "monthName": "March",
      "count": 0,
      "volumeUSD": 0
    }
  ],
  "topSourceChains": [
    {
      "chainId": 1,
      "chainName": "Ethereum",
      "count": 18,
      "percentage": 42.86,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/ethereum.png"
    },
    {
      "chainId": 10,
      "chainName": "Optimism",
      "count": 12,
      "percentage": 28.57,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/optimism.png"
    }
  ],
  "topDestinationChains": [
    {
      "chainId": 42161,
      "chainName": "Arbitrum",
      "count": 15,
      "percentage": 35.71,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/arbitrum.png"
    },
    {
      "chainId": 8453,
      "chainName": "Base",
      "count": 10,
      "percentage": 23.81,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/base.png"
    }
  ],
  "topTokens": [
    {
      "symbol": "USDC",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "count": 28,
      "totalVolumeUSD": 95600.00,
      "percentage": 66.67,
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png"
    },
    {
      "symbol": "WETH",
      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "count": 10,
      "totalVolumeUSD": 25830.50,
      "percentage": 23.81,
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png"
    }
  ],
  "transactions": [
    {
      "id": "across-1234567890",
      "provider": "across",
      "txHash": "0xabc123...",
      "timestamp": 1704067200,
      "sourceChainId": 1,
      "sourceChainName": "Ethereum",
      "destinationChainId": 42161,
      "destinationChainName": "Arbitrum",
      "tokenSymbol": "USDC",
      "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "amount": "5000000000",
      "amountFormatted": 5000,
      "amountUSD": 5000.00,
      "status": "completed"
    }
  ]
}

GET

api

bridge-stats

[address]

Get Bridge Stats

curl --request GET \
  --url 'https://api.example.com/api/bridge-stats/[address]'

{
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "year": 2025,
  "generatedAt": "2025-03-15T14:30:00.000Z",
  "totalBridgingActions": 42,
  "totalVolumeUSD": 125430.50,
  "mostUsedSourceChain": {
    "chainId": 1,
    "chainName": "Ethereum",
    "count": 18,
    "percentage": 42.86,
    "volumeUSD": 0,
    "logo": "https://example.com/logos/ethereum.png"
  },
  "mostUsedDestinationChain": {
    "chainId": 42161,
    "chainName": "Arbitrum",
    "count": 15,
    "percentage": 35.71,
    "volumeUSD": 0,
    "logo": "https://example.com/logos/arbitrum.png"
  },
  "highestVolumeDestination": {
    "chainId": 42161,
    "chainName": "Arbitrum",
    "count": 15,
    "percentage": 35.71,
    "volumeUSD": 85230.25,
    "logo": "https://example.com/logos/arbitrum.png"
  },
  "mostBridgedToken": {
    "symbol": "USDC",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "count": 28,
    "totalVolumeUSD": 95600.00,
    "percentage": 66.67,
    "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png"
  },
  "busiestDay": {
    "date": "2025-06-15",
    "count": 8,
    "primaryDestination": {
      "chainId": 42161,
      "chainName": "Arbitrum",
      "count": 5
    }
  },
  "providerBreakdown": {
    "across": {
      "count": 25,
      "volumeUSD": 78500.25
    },
    "relay": {
      "count": 12,
      "volumeUSD": 35200.00
    },
    "lifi": {
      "count": 5,
      "volumeUSD": 11730.25
    }
  },
  "monthlyActivity": [
    {
      "month": "2025-01",
      "monthName": "January",
      "count": 5,
      "volumeUSD": 15230.50
    },
    {
      "month": "2025-02",
      "monthName": "February",
      "count": 3,
      "volumeUSD": 8400.00
    },
    {
      "month": "2025-03",
      "monthName": "March",
      "count": 0,
      "volumeUSD": 0
    }
  ],
  "topSourceChains": [
    {
      "chainId": 1,
      "chainName": "Ethereum",
      "count": 18,
      "percentage": 42.86,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/ethereum.png"
    },
    {
      "chainId": 10,
      "chainName": "Optimism",
      "count": 12,
      "percentage": 28.57,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/optimism.png"
    }
  ],
  "topDestinationChains": [
    {
      "chainId": 42161,
      "chainName": "Arbitrum",
      "count": 15,
      "percentage": 35.71,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/arbitrum.png"
    },
    {
      "chainId": 8453,
      "chainName": "Base",
      "count": 10,
      "percentage": 23.81,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/base.png"
    }
  ],
  "topTokens": [
    {
      "symbol": "USDC",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "count": 28,
      "totalVolumeUSD": 95600.00,
      "percentage": 66.67,
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png"
    },
    {
      "symbol": "WETH",
      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "count": 10,
      "totalVolumeUSD": 25830.50,
      "percentage": 23.81,
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png"
    }
  ],
  "transactions": [
    {
      "id": "across-1234567890",
      "provider": "across",
      "txHash": "0xabc123...",
      "timestamp": 1704067200,
      "sourceChainId": 1,
      "sourceChainName": "Ethereum",
      "destinationChainId": 42161,
      "destinationChainName": "Arbitrum",
      "tokenSymbol": "USDC",
      "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "amount": "5000000000",
      "amountFormatted": 5000,
      "amountUSD": 5000.00,
      "status": "completed"
    }
  ]
}

Endpoint

GET /api/bridge-stats/{address}

Fetches and aggregates bridge statistics from multiple providers (Across, Relay, LiFi) for a specific wallet address.

Path Parameters

address

string

required

Ethereum wallet address to fetch statistics for. Must be a valid 42-character hexadecimal address starting with 0x.Format: 0x followed by 40 hexadecimal characters (0-9, a-f, A-F)Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Query Parameters

year

integer

default:"2025"

The year to fetch statistics for. Used to calculate the time range (January 1 00:00:00 to December 31 23:59:59 UTC).Constraints:

Must be between 2020 and 2030
Defaults to 2025 if not provided

Example: 2024

Request Examples

curl -X GET "https://bridge-wrapped.vercel.app/api/bridge-stats/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb?year=2025" \
  -H "Content-Type: application/json"

Response

walletAddress

string

required

The wallet address that was queried (checksummed format)

year

integer

required

The year for which statistics were calculated

generatedAt

string

required

ISO 8601 timestamp when the statistics were generatedExample: 2025-03-15T14:30:00.000Z

totalBridgingActions

integer

required

Total number of bridge transactions completed during the year

totalVolumeUSD

number

required

Total USD value of all bridged assets (calculated at time of transaction)

mostUsedSourceChain

object

The blockchain most frequently used as the source for bridge transactions

Show properties

chainId

integer

Numeric chain identifier

chainName

string

Human-readable chain name (e.g., “Ethereum”, “Arbitrum”)

count

integer

Number of transactions from this chain

percentage

number

Percentage of total transactions (0-100)

volumeUSD

number

USD volume (always 0 for source chains)

logo

string

URL to chain logo image

mostUsedDestinationChain

object

The blockchain most frequently used as the destination for bridge transactions

Show properties

chainId

integer

Numeric chain identifier

chainName

string

Human-readable chain name

count

integer

Number of transactions to this chain

percentage

number

Percentage of total transactions (0-100)

volumeUSD

number

USD volume (0 for destination counts)

logo

string

URL to chain logo image

highestVolumeDestination

object

The destination chain with the highest total USD volume

Show properties

chainId

integer

Numeric chain identifier

chainName

string

Human-readable chain name

count

integer

Number of transactions to this chain

percentage

number

Percentage of total transactions (0-100)

volumeUSD

number

Total USD volume bridged to this chain

logo

string

URL to chain logo image

mostBridgedToken

object

The token most frequently bridged across all transactions

Show properties

symbol

string

Token symbol (e.g., “USDC”, “ETH”)

address

string

Token contract address

count

integer

Number of times this token was bridged

totalVolumeUSD

number

Total USD value of this token bridged

percentage

number

Percentage of total transactions (0-100)

logo

string

URL to token logo image from CoinMarketCap

busiestDay

object

The date with the most bridge transactions

Show properties

date

string

Date in YYYY-MM-DD format

count

integer

Number of transactions on this day

primaryDestination

object

The most common destination chain on this day

Show properties

chainId

integer

Numeric chain identifier

chainName

string

Human-readable chain name

count

integer

Number of transactions to this destination on the busiest day

providerBreakdown

object

required

Usage statistics broken down by bridge provider

Show properties

across

object

Show properties

count

integer

Number of transactions via Across Protocol

volumeUSD

number

Total USD volume via Across

relay

object

Show properties

count

integer

Number of transactions via Relay

volumeUSD

number

Total USD volume via Relay

lifi

object

Show properties

count

integer

Number of transactions via LiFi

volumeUSD

number

Total USD volume via LiFi

monthlyActivity

array

required

Array of monthly activity data for all 12 months (even if count is 0)

Show object properties

month

string

Month in YYYY-MM format

monthName

string

Full month name (e.g., “January”, “February”)

count

integer

Number of transactions in this month

volumeUSD

number

Total USD volume for this month

topSourceChains

array

required

Top 5 most used source chains, sorted by transaction count

Show object properties

chainId

integer

Numeric chain identifier

chainName

string

Human-readable chain name

count

integer

Number of transactions from this chain

percentage

number

Percentage of total transactions (0-100)

volumeUSD

number

Always 0 for source chains

logo

string

URL to chain logo image

topDestinationChains

array

required

Top 5 most used destination chains, sorted by transaction count

Show object properties

chainId

integer

Numeric chain identifier

chainName

string

Human-readable chain name

count

integer

Number of transactions to this chain

percentage

number

Percentage of total transactions (0-100)

volumeUSD

number

Always 0 for top destination counts

logo

string

URL to chain logo image

topTokens

array

required

Top 5 most bridged tokens, sorted by transaction count

Show object properties

symbol

string

Token symbol (e.g., “USDC”, “WETH”)

address

string

Token contract address

count

integer

Number of times this token was bridged

totalVolumeUSD

number

Total USD value of this token bridged

percentage

number

Percentage of total transactions (0-100)

logo

string

URL to token logo from CoinMarketCap

transactions

array

required

Complete list of all normalized bridge transactions, sorted by timestamp

Show object properties

string

Unique transaction identifier

provider

string

Bridge provider: “across”, “relay”, or “lifi”

txHash

string

Transaction hash on the source chain

timestamp

integer

Unix timestamp in seconds

sourceChainId

integer

Source blockchain ID

sourceChainName

string

Human-readable source chain name

destinationChainId

integer

Destination blockchain ID

destinationChainName

string

Human-readable destination chain name

tokenSymbol

string

Token symbol being bridged

tokenAddress

string

Token contract address

amount

string

Raw token amount in smallest unit (wei)

amountFormatted

number

Human-readable amount with decimals

amountUSD

number

USD value at time of transaction

status

string

Transaction status: “pending”, “completed”, or “failed”

Response Example

{
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "year": 2025,
  "generatedAt": "2025-03-15T14:30:00.000Z",
  "totalBridgingActions": 42,
  "totalVolumeUSD": 125430.50,
  "mostUsedSourceChain": {
    "chainId": 1,
    "chainName": "Ethereum",
    "count": 18,
    "percentage": 42.86,
    "volumeUSD": 0,
    "logo": "https://example.com/logos/ethereum.png"
  },
  "mostUsedDestinationChain": {
    "chainId": 42161,
    "chainName": "Arbitrum",
    "count": 15,
    "percentage": 35.71,
    "volumeUSD": 0,
    "logo": "https://example.com/logos/arbitrum.png"
  },
  "highestVolumeDestination": {
    "chainId": 42161,
    "chainName": "Arbitrum",
    "count": 15,
    "percentage": 35.71,
    "volumeUSD": 85230.25,
    "logo": "https://example.com/logos/arbitrum.png"
  },
  "mostBridgedToken": {
    "symbol": "USDC",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "count": 28,
    "totalVolumeUSD": 95600.00,
    "percentage": 66.67,
    "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png"
  },
  "busiestDay": {
    "date": "2025-06-15",
    "count": 8,
    "primaryDestination": {
      "chainId": 42161,
      "chainName": "Arbitrum",
      "count": 5
    }
  },
  "providerBreakdown": {
    "across": {
      "count": 25,
      "volumeUSD": 78500.25
    },
    "relay": {
      "count": 12,
      "volumeUSD": 35200.00
    },
    "lifi": {
      "count": 5,
      "volumeUSD": 11730.25
    }
  },
  "monthlyActivity": [
    {
      "month": "2025-01",
      "monthName": "January",
      "count": 5,
      "volumeUSD": 15230.50
    },
    {
      "month": "2025-02",
      "monthName": "February",
      "count": 3,
      "volumeUSD": 8400.00
    },
    {
      "month": "2025-03",
      "monthName": "March",
      "count": 0,
      "volumeUSD": 0
    }
  ],
  "topSourceChains": [
    {
      "chainId": 1,
      "chainName": "Ethereum",
      "count": 18,
      "percentage": 42.86,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/ethereum.png"
    },
    {
      "chainId": 10,
      "chainName": "Optimism",
      "count": 12,
      "percentage": 28.57,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/optimism.png"
    }
  ],
  "topDestinationChains": [
    {
      "chainId": 42161,
      "chainName": "Arbitrum",
      "count": 15,
      "percentage": 35.71,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/arbitrum.png"
    },
    {
      "chainId": 8453,
      "chainName": "Base",
      "count": 10,
      "percentage": 23.81,
      "volumeUSD": 0,
      "logo": "https://example.com/logos/base.png"
    }
  ],
  "topTokens": [
    {
      "symbol": "USDC",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "count": 28,
      "totalVolumeUSD": 95600.00,
      "percentage": 66.67,
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png"
    },
    {
      "symbol": "WETH",
      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "count": 10,
      "totalVolumeUSD": 25830.50,
      "percentage": 23.81,
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png"
    }
  ],
  "transactions": [
    {
      "id": "across-1234567890",
      "provider": "across",
      "txHash": "0xabc123...",
      "timestamp": 1704067200,
      "sourceChainId": 1,
      "sourceChainName": "Ethereum",
      "destinationChainId": 42161,
      "destinationChainName": "Arbitrum",
      "tokenSymbol": "USDC",
      "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "amount": "5000000000",
      "amountFormatted": 5000,
      "amountUSD": 5000.00,
      "status": "completed"
    }
  ]
}

Error Codes

400

Bad Request

Invalid request parametersCauses:

Address is not a valid Ethereum address (must match pattern 0x[a-fA-F0-9]{40})
Year parameter is not a number
Year is outside the valid range (2020-2030)

500

Internal Server Error

Failed to fetch or process bridge statisticsCauses:

Upstream provider API failures (all providers failed)
Database connection issues
Unexpected errors during data aggregation

Note: Individual provider failures are handled gracefully - the endpoint only returns 500 if the entire operation fails

Implementation Details

Address Validation

The endpoint validates Ethereum addresses using the regex pattern:

/^0x[a-fA-F0-9]{40}$/

This ensures:

Address starts with 0x
Followed by exactly 40 hexadecimal characters
Case-insensitive validation (both checksummed and lowercase accepted)

Year Processing

The year parameter:

Defaults to 2025 if not provided
Must be an integer between 2020 and 2030
Used to calculate Unix timestamps for the full calendar year (UTC timezone)
Start: January 1, 00:00:00 UTC
End: December 31, 23:59:59 UTC

Data Aggregation Flow

Parallel Fetching: Queries all three providers simultaneously
Error Tolerance: Individual provider failures don’t stop the entire request
Deduplication: Combines results and removes duplicate transactions
Statistics Calculation: Processes normalized transactions to generate all metrics
Logo Enrichment: Fetches token logos from CoinMarketCap API

Transaction Deduplication

Transactions are deduplicated using a composite key:

{txHash.toLowerCase()}-{sourceChainId}-{destinationChainId}

When duplicates are found:

Prefer transactions with USD value > 0
Keep the most complete transaction data

Notes

All USD values are calculated at the time of the original transaction
Token logos are fetched from CoinMarketCap when available
Chain logos are provided from the internal chain registry
Monthly activity always includes all 12 months (with 0 counts for inactive months)
Top lists (chains, tokens) are limited to 5 items maximum
Transactions are sorted chronologically (oldest first)
Null values indicate no activity (e.g., mostBridgedToken: null if no transactions)

Bridge Stats API Overview

Token Info API

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Bridge Stats

Token Info

​Endpoint

​Path Parameters

​Query Parameters

​Request Examples

​Response

​Response Example

​Error Codes

​Implementation Details

​Address Validation

​Year Processing

​Data Aggregation Flow

​Transaction Deduplication

​Notes

Build docs developers (and LLMs) love

Endpoint

Path Parameters

Query Parameters

Request Examples

Response

Response Example

Error Codes

Implementation Details

Address Validation

Year Processing

Data Aggregation Flow

Transaction Deduplication

Notes