GET /builder/fills

Return fills attributed to the authenticated builder. Use cursor or offset pagination, not both. Use format=csv to export CSV with the same start_time, end_time, and instrument filters; CSV mode ignores cursor and offset and caps exports at 50,000 rows.

GET https://api.aevo.xyz/builder/fills

Authentication required. Include your AEVO-KEY and AEVO-SECRET headers. See Authentication.

Query Parameters

Field	Type	Required	Description
start_time	integer	No	Window start, Unix nanoseconds. Use with end_time, or use period. Example: 1672531200000000000
end_time	integer	No	Window end, Unix nanoseconds. Defaults to now. Example: 1675036800000000000
instrument	string	No	Instrument name. Example: ETH-PERP
limit	integer	No	Rows per page. Defaults to 50, maximum 200. On /builder/markets, omit both limit and offset to get every market. Example: 10
offset	integer	No	Rows to skip, for numbered pages (ceil(count / limit) pages). Use this or cursor, not both. Example: 10
cursor	string	No	Opaque cursor: pass the previous response's next_cursor. Use this or offset, not both. Example: MTcwMDAwMDAwMDAwMDAwMDAwMDoweHRyYWRlOjB4b3JkZXI
format	string	No	Optional builder export format. Example: csv

Example Request

curl --request GET \
     --url https://api.aevo.xyz/builder/fills \
     --header 'accept: application/json' \
     --header 'AEVO-KEY: <your-api-key>' \
     --header 'AEVO-SECRET: <your-api-secret>'

Responses

200 — Builder-attributed fills.

Field	Type	Required	Description
fills	array[object]	No
count	string	Yes	Total rows matching the filters, before pagination. Example: 5
next_cursor	string	No	Cursor for the next page. Returned only for cursor pagination, and only when more rows exist. Example: MTcwMDAwMDAwMDAwMDAwMDAwMDoweHRyYWRlOjB4b3JkZXI

fills items:

Field	Type	Required	Description
trade_id	string	Yes	Unique ID of the trade. Example: DwmDn5XnEyiqx5AB5CM4W8bgD137ASX4Lz1XWBYqvpX2
order_id	string	Yes	Order ID is the hash of the order payload Example: 0x4c43e0ab72a4edb72dfe4b129148899815d816837b9a7e22d964b884834639f8
account	string	Yes	Account's Ethereum address. Example: 0xBuilderUserAddress
instrument	string	Yes	Instrument name. Example: ETH-PERP
side	string	Yes	Trade side.
price	string	Yes	Limit price for the order. Example: 12.34
amount	string	Yes	Number of contracts. In 6 decimals fixed number. Example: 1000000
notional	string	Yes	USDC notional value. Example: 1700
builder_fee_rate	string	Yes	Builder fee rate as a decimal fraction. Uses 6-decimal fixed-point precision; 0.0003 is 3 bps. Example: 0.0003
builder_fee	string	Yes	Builder fee paid for the trade, denominated in USDC. Example: 0.3
is_maker	boolean	Yes	Whether the fill was maker-side for this order. Example: true
timestamp	string	Yes	Timestamp in UNIX in nanoseconds. Example: 1680249600000000000

400 — Bad request.

Field	Type	Required	Description
error	string	Yes	Error message. Example: ERR_MALFORMED_REQUEST

401 — Unauthorized.

Field	Type	Required	Description
error	string	Yes	Error message. Example: UNAUTHORIZED

429 — Rate limit exceeded.

Field	Type	Required	Description
error	string	Yes	Error message. Example: RATE_LIMIT_EXCEEDED

500 — Internal server error.

Field	Type	Required	Description
error	string	Yes	Error message. Example: INTERNAL_ERROR