Read finalized builder settlement history
curl --request GET \
--url https://api.route.fun/api/v2/builders/history \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.route.fun/api/v2/builders/history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.route.fun/api/v2/builders/history"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"code": "<string>",
"builderId": "<string>",
"settlements": [
{
"quoteId": "<string>",
"builderCode": "<string>",
"builderId": "<string>",
"keyIdHash": "<string>",
"payer": "<string>",
"recipient": "<string>",
"tokenIn": "<string>",
"amountIn": "<string>",
"tokenOut": "<string>",
"grossAmountOut": "<string>",
"routeFee": "<string>",
"builderFee": "<string>",
"amountOut": "<string>",
"builderRecipient": "<string>",
"policyVersion": "<string>",
"hash": "<string>",
"blockNumber": "<string>",
"blockHash": "<string>",
"logIndex": 123,
"status": "finalized"
}
],
"nextCursor": "<string>",
"finalizedThrough": "<string>",
"totalsByToken": [
{
"tokenOut": "<string>",
"grossAmountOut": "<string>",
"routeFee": "<string>",
"builderFee": "<string>",
"amountOut": "<string>",
"count": 123
}
],
"totalsScope": "page",
"scannedFrom": "<string>",
"scannedThrough": "<string>",
"snapshotHash": "<string>"
}Builder registry
Read finalized builder settlement history
Requires receipts scope and shares its quota. Reads events directly from the reviewed collector without saved quote records. Each page scans at most 1000 blocks and returns at most 1000 events. Pass nextCursor unchanged, including after an empty page; null means the fixed finalized snapshot is complete. Totals cover only this page and remain separated by output-token address in raw units. History is readable while the builder is suspended. Invalid canonical snapshots return 409; restart pagination.
GET
/
api
/
v2
/
builders
/
history
Read finalized builder settlement history
curl --request GET \
--url https://api.route.fun/api/v2/builders/history \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.route.fun/api/v2/builders/history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.route.fun/api/v2/builders/history"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"code": "<string>",
"builderId": "<string>",
"settlements": [
{
"quoteId": "<string>",
"builderCode": "<string>",
"builderId": "<string>",
"keyIdHash": "<string>",
"payer": "<string>",
"recipient": "<string>",
"tokenIn": "<string>",
"amountIn": "<string>",
"tokenOut": "<string>",
"grossAmountOut": "<string>",
"routeFee": "<string>",
"builderFee": "<string>",
"amountOut": "<string>",
"builderRecipient": "<string>",
"policyVersion": "<string>",
"hash": "<string>",
"blockNumber": "<string>",
"blockHash": "<string>",
"logIndex": 123,
"status": "finalized"
}
],
"nextCursor": "<string>",
"finalizedThrough": "<string>",
"totalsByToken": [
{
"tokenOut": "<string>",
"grossAmountOut": "<string>",
"routeFee": "<string>",
"builderFee": "<string>",
"amountOut": "<string>",
"count": 123
}
],
"totalsScope": "page",
"scannedFrom": "<string>",
"scannedThrough": "<string>",
"snapshotHash": "<string>"
}Build a builder earnings or swap-history view from finalized settlements. Each entry includes the transaction hash, traded tokens, input/output amounts and separate Route and builder fees.
Pass
curl 'https://api.route.fun/api/v2/builders/history?code=YOUR_BUILDER_ID' \
-H "x-api-key: $ROUTE_API_KEY"
nextCursor as cursor until it is null, even when a page has no settlements. totalsByToken covers the current page only, in token base units. Keep different tokens separate when adding totals.
Authentication · Builder integrationAuthorizations
Server-side key created in an authenticated developer workspace. Builder codes are public attribution, not credentials.
Query Parameters
Pattern:
^[A-Za-z0-9_-]{3,32}$Maximum string length:
1500Response
Verified registry or finalized history result
Pattern:
^[A-Za-z0-9_-]{3,32}$Pattern:
^0x[0-9a-fA-F]{64}$Show child attributes
Show child attributes
Pattern:
^[0-9]+$Show child attributes
Show child attributes
Allowed value:
"page"Pattern:
^[0-9]+$Pattern:
^[0-9]+$Pattern:
^0x[0-9a-fA-F]{64}$