Quickstart

This guide walks you through the two Trade History API endpoints. You’ll query trades for a wallet address and look up a specific transaction by hash.

What you’ll build: Scripts that fetch and display trade history from Bebop.Time required: 5 minutesPrerequisites: None for public wallet lookups. To fetch trades attributed to your own integration, authenticate with your API key.

1. Look up trades for a wallet

Retrieve all trades for a given wallet address. The API returns trades across all Bebop-supported chains in a single response.

GET /history/v2/trades

Parameter	Required	Type	Description
`wallet_address`	Yes	string	Wallet address to look up
`start`	No	integer	Start of time range (UNIX timestamp in nanoseconds)
`end`	No	integer	End of time range (UNIX timestamp in nanoseconds)
`size`	No	integer	Number of trades to return per chain, between 1 and 500 (default: 500)

NOW_NS=$(date +%s)000000000
THIRTY_DAYS_NS=$((30 * 24 * 60 * 60))000000000
START_NS=$((NOW_NS - THIRTY_DAYS_NS))

curl --get "https://api.bebop.xyz/history/v2/trades" \
  --data-urlencode "wallet_address=0xcaBD7845e4E51069E87a62d0A29064782134124C" \
  --data-urlencode "start=$START_NS" \
  --data-urlencode "end=$NOW_NS" \
  --data-urlencode "size=5"

import time

import httpx

now_ns = int(time.time() * 1_000_000_000)
thirty_days_ns = 30 * 24 * 60 * 60 * 1_000_000_000

resp = httpx.get(
    "https://api.bebop.xyz/history/v2/trades",
    params={
        "wallet_address": "0xcaBD7845e4E51069E87a62d0A29064782134124C",
        "start": now_ns - thirty_days_ns,
        "end": now_ns,
        "size": 5,
    },
)
data = resp.json()

for trade in data.get("results", []):
    sell = (
        list(trade.get("sellTokens", {}).values())[0]
        if trade.get("sellTokens")
        else {}
    )
    buy = (
        list(trade.get("buyTokens", {}).values())[0]
        if trade.get("buyTokens")
        else {}
    )
    print(
        f'{sell.get("symbol", "?")} -> {buy.get("symbol", "?")}  '
        f'${trade.get("volumeUsd", 0):.2f}  ({trade.get("timestamp", "")})'
    )

Understanding the response

This abridged response shows the fields used by most integrations. See the API reference for the complete historical schema.

{
  "results": [
    {
      "chain_id": 42161,
      "txHash": "0x56927ccf...9c05",
      "status": "Success",
      "type": "121",
      "taker": "0xcaBD78...124C",
      "receiver": "0xcaBD78...124C",
      "sellTokens": {
        "0xEeeeeE...EEeE": {
          "amount": "9706350785296284",
          "amountUsd": 20.03361683032797
        }
      },
      "buyTokens": {
        "0xaf88d0...5831": {
          "amount": "20057981",
          "amountUsd": 20.056035375843003
        }
      },
      "volumeUsd": 20.056035375843003,
      "gasFeeUsd": 0.01292311262430648,
      "timestamp": "2026-02-25 19:44:34Z",
      "route": "JAM"
    }
  ],
  "metadata": {
    "timestamp": "2026-03-18 09:49:08",
    "results": 1,
    "tokens": {
      "42161": {
        "0xEeeeeE...EEeE": {
          "name": "Ethereum",
          "symbol": "ETH",
          "decimals": 18,
          "displayDecimals": 5,
          "icon": "https://bebop-public-images.s3.eu-west-2..."
        },
        "0xaf88d0...5831": {
          "name": "USDC",
          "symbol": "USDC",
          "decimals": 6,
          "displayDecimals": 2,
          "icon": "https://bebop-public-images.s3.eu-west-2..."
        }
      }
    }
  }
}

Field	Type	Description
`results`	array	Array of trade objects, newest first
`results[].chain_id`	integer	Chain ID where the trade settled
`results[].txHash`	string	Transaction hash
`results[].status`	string	`Success`, etc.
`results[].type`	string	Trade type (see trade types below)
`results[].taker`	string	Address that sent the sell tokens
`results[].receiver`	string	Address that received the buy tokens
`results[].sellTokens`	object	Map of contract address to token info (`amount`, `amountUsd`, `symbol`)
`results[].buyTokens`	object	Map of contract address to token info (`amount`, `amountUsd`, `symbol`)
`results[].volumeUsd`	number	Trade volume in USD (excluding gas)
`results[].gasFeeUsd`	number	Gas fee in USD at the time of the trade
`results[].timestamp`	string	When the trade occurred
`results[].route`	string	Which Bebop API executed the trade (`JAM` or `PMM`)
`nextAvailableTimestamp`	integer or null	Nanosecond timestamp for pagination. `null` when all trades have been returned.
`metadata.timestamp`	string	Current server timestamp
`metadata.results`	integer	Number of trade objects in this response

Trade types

Type	Description
`121`	Single swap - one token in, one token out
`12M`	One token in, multiple tokens out (exact amounts per token)
`M21`	Multiple tokens in, one token out (exact amounts per token)
`12MPercentages`	One token in, multiple tokens out (percentage ratios across output tokens)
`M21Percentages`	Multiple tokens in, one token out (percentage ratios across input tokens)

Filtering by time range

Narrow results to a specific window using start and end parameters.

Timestamps are in nanoseconds, not seconds or milliseconds. For example, 1680303600000000000 corresponds to 2023-03-31T21:00:00Z. Passing a millisecond timestamp will return no results.

import time

import httpx

# Last 30 days
now_ns = int(time.time() * 1_000_000_000)
thirty_days_ns = 30 * 24 * 60 * 60 * 1_000_000_000

resp = httpx.get(
    "https://api.bebop.xyz/history/v2/trades",
    params={
        "wallet_address": "0xcaBD7845e4E51069E87a62d0A29064782134124C",
        "start": now_ns - thirty_days_ns,
        "end": now_ns,
        "size": 100,
    },
)

data = resp.json()
print(f'Fetched {len(data.get("results", []))} trades in last 30 days')

Pagination

A single response returns at most 500 trades per chain (the size cap). If nextAvailableTimestamp is not null, repeat the request using that value as your new end parameter:

import time

import httpx

now_ns = int(time.time() * 1_000_000_000)
thirty_days_ns = 30 * 24 * 60 * 60 * 1_000_000_000

all_trades = []
end = now_ns

while True:
    resp = httpx.get(
        "https://api.bebop.xyz/history/v2/trades",
        params={
            "wallet_address": "0xcaBD7845e4E51069E87a62d0A29064782134124C",
            "start": now_ns - thirty_days_ns,
            "end": end,
            "size": 100,
        },
    )
    data = resp.json()
    all_trades.extend(data.get("results", []))

    next_ts = data.get("nextAvailableTimestamp")
    if next_ts is None:
        break
    end = next_ts

print(f"Fetched {len(all_trades)} trades")

2. Look up a specific transaction

Retrieve details for a single transaction hash. The API searches across all chains automatically.

GET /history/v2/tx/{tx_hash}

Parameter	Required	Type	Description
`tx_hash`	Yes	string	Transaction hash (66-character hex string starting with `0x`)

curl "https://api.bebop.xyz/history/v2/tx/0x8f4adfc8aa60711c464194a2d297f823e7f54fadc3995ea1844d6731fdaf38ee"

import httpx

tx_hash = "0x8f4adfc8aa60711c464194a2d297f823e7f54fadc3995ea1844d6731fdaf38ee"
resp = httpx.get(f"https://api.bebop.xyz/history/v2/tx/{tx_hash}")
data = resp.json()

# The response wraps results in a list
results = data.get("results", [data])
trade = results[0] if results else data

sell = (
    list(trade.get("sellTokens", {}).values())[0] if trade.get("sellTokens") else {}
)
buy = list(trade.get("buyTokens", {}).values())[0] if trade.get("buyTokens") else {}
print(
    f'Chain {trade.get("chain_id", "?")}: {sell.get("symbol", "?")} -> {buy.get("symbol", "?")}'
)
print(
    f'Volume: ${trade.get("volumeUsd", 0):.2f}  Gas: ${trade.get("gasFeeUsd", 0):.4f}'
)

The response is a single trade object with the same schema as the items in the /trades array.

Errors

Code	Detail	Reason
400	`Invalid tx hash: {tx_hash}.`	Not a valid 66-character hex string
404	`Tx hash not found: {tx_hash}.`	Transaction was not executed through Bebop
500	`Something went wrong, try again later.`	Server error

Introduction

Core Concepts

RFQ API

BopAMM

Aggregation API

Price API

Trade History API

1. Look up trades for a wallet

Understanding the response

Trade types

Filtering by time range

2. Look up a specific transaction

Errors

​1. Look up trades for a wallet

​Understanding the response

​Trade types

​Filtering by time range

​Pagination

​2. Look up a specific transaction

​Errors

1. Look up trades for a wallet

Understanding the response

Trade types

Filtering by time range

Pagination

2. Look up a specific transaction

Errors