Endpoints
- By time range
- By transaction hash
Query parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
maker | string | Yes | N/A | Maker ID whose trade history is requested. |
start | integer | No | 0 | Start timestamp in Unix nanoseconds to begin retrieving trades from. |
end | integer | No | 0 | End timestamp in Unix nanoseconds to stop retrieving trades at. |
limit | integer | No | 0 | Limit the number of trades returned. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | API key as a Bearer token. |
Request example
Response example
Types
MakerTrade
The MakerTrade object represents a single maker-side trade.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
| quote_id | str | Yes | Unique identifier of the quote associated with the trade. |
| tx_hash | str | Yes | Transaction hash for the trade. |
| executor | str | Yes | Entity responsible for sending the order on-chain: bebop (gasless) or user (self-executed). |
| event_id | str | Yes | Identifier for finding the order on-chain. Emitted by the contract, found in the transaction event logs. |
| status | str | Yes | Status of the trade. See Trade status for possible values. |
| order_time | int | Yes | Timestamp of when the order was mined (Unix nanoseconds). |
| surplus_recipient | str | Yes | Entity receiving any surplus (user or bebop). |
| surplus_usd | float | Yes | Surplus in USD, rounded up to a $0.001 minimum. |
| surplus | float | Yes | Surplus in native token, at the native price at time of request. Deprecated - removed 31 Aug 2026; use surplus_usd. |
| fee_usd | float | Yes | Fee in USD, rounded up to a $0.001 minimum. |
| fee_native | float | Yes | Fee in native token. Deprecated - removed 31 Aug 2026; use fee_usd. |
| reference_quote_id | str | null | No | Identifier of the reference quote, if any. Whale-mode only. |
| quotes | list[MakerQuote] | Yes | List of quotes filled in the trade. |
| reference_quotes | list[MakerQuote] | null | No | List of reference quotes. Whale-mode only. |
| taker_address | str | Yes | Address of the user sending the taker tokens. |
| receiver_address | str | Yes | Address that received the tokens. |
| origin_address | str | Yes | Origin address that requested the quote, passed down by partners for cases when the taker and receiver are the partner’s Router or Settlement contracts. |
MakerQuote
The MakerQuote object is returned inside quotes and reference_quotes of MakerTrade.
| Field | Type | Required | Description |
|---|---|---|---|
| taker_token | str | Yes | Address of the taker token. |
| taker_amount | str | Yes | Amount of taker token. |
| maker_token | str | Yes | Address of the maker token. |
| maker_amount | str | Yes | Amount of maker token. |
| filled_taker_amount | str | No | Amount of taker token actually filled (when order is partially filled at execution time). |
| filled_maker_amount | str | No | Amount of maker token actually filled (when order is partially filled at execution time). |
| onchain_maker_amount | str | No | RFQA only. Maker token that left your wallet, net of the oracle slippage refund. |
| refunded_maker_amount | str | No | RFQA only. Maker’s share of the recovered slippage. Satisfies onchain_maker_amount + refunded_maker_amount == filled_maker_amount. |
For RFQA trades, responses are anonymized:
taker_address and receiver_address are the BebopRouter and no end-user address is exposed.MakerTradesResponse
Returned by the “By time range” endpoint. Contains trades, pagination, and summary.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
| trades | list[MakerTrade] | Yes | List of trades matching the request. |
| next_ts | int | Yes | Pagination timestamp. 0 means all trades in the range have been returned. Otherwise, use this value as the new end parameter to fetch the next page. |
| summary | MakerSummaryResponse | Yes | Aggregated statistics across all returned trades. |
MakerSummaryResponse
Aggregated information about a set of maker trades. Returned in the summary field of MakerTradesResponse.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
| num_trades | int | Yes | Number of trades in the response. |
| fee_currency | str | Yes | Symbol of the native fee currency (e.g. ETH). |
| total_fees_usd | float | Yes | Total fees in USD. |
| total_fees_native | float | Yes | Total fees in native token. Deprecated - removed 31 Aug 2026; use total_fees_usd. |
| total_surplus_bebop_usd | float | Yes | Total surplus captured by Bebop, in USD (0 if none). |
| total_surplus_bebop | float | Yes | Total surplus captured by Bebop, native token (0 if none). Deprecated - removed 31 Aug 2026. |
| total_surplus_user_usd | float | Yes | Total surplus captured by users, in USD (0 if none). |
| total_surplus_user | float | Yes | Total surplus captured by users, native token (0 if none). Deprecated - removed 31 Aug 2026. |
| first_trade_ts | datetime | null | No | Timestamp of the earliest trade in the response. |
| last_trade_ts | datetime | null | No | Timestamp of the latest trade in the response. |