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. Filtering by source (partner attribution) requires an 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.
| Parameter | Required | Type | Description |
|---|
wallet_address | Yes | string | Wallet address to look up |
source | No | string | Partner identifier. Filter trades to only those originating from your integration. |
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 | Maximum number of trade objects to return |
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"
Understanding the response
{
"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",
"gasless": false
}
],
"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) |
results[].gasless | boolean | Whether the trade was executed gaslessly |
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')
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"
/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 |
