> ## Documentation Index > Fetch the complete documentation index at: https://docs.route.fun/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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. ```bash theme={null} curl 'https://api.route.fun/api/v2/builders/history?code=YOUR_BUILDER_ID' \ -H "x-api-key: $ROUTE_API_KEY" ``` Pass `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](/api-reference/authentication) ยท [Builder integration](/builders) ## OpenAPI ````yaml openapi.json GET /api/v2/builders/history openapi: 3.1.0 info: title: route version: 2.15.0 description: >- Route compares swap paths offchain and executes swaps on Robinhood Chain. The API returns quotes and unsigned transactions. It does not sign or submit for you. V2 deducts a disclosed pair-dependent output fee up to 0.50%; pool fees, provider charges and gas may still apply. Contracts are experimental and unaudited. Public routing and data endpoints require no API key. Use the documented /api/v2 endpoints for integrations. Builder endpoints require a scoped x-api-key from build.route.fun. Public quote, swap and data endpoints remain keyless. servers: - url: https://api.route.fun security: [] paths: /api/v2/builders/history: get: tags: - Builder API summary: Read finalized builder settlement history description: >- 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. operationId: getBuilderHistory parameters: - in: query name: code required: true schema: type: string pattern: ^[A-Za-z0-9_-]{3,32}$ - in: query name: cursor schema: type: string maxLength: 1500 responses: '200': description: Verified registry or finalized history result content: application/json: schema: type: object properties: code: type: string pattern: ^[A-Za-z0-9_-]{3,32}$ builderId: type: string pattern: ^0x[0-9a-fA-F]{64}$ settlements: type: array items: type: object properties: quoteId: type: string pattern: ^0x[0-9a-fA-F]{64}$ builderCode: type: string pattern: ^[A-Za-z0-9_-]{3,32}$ builderId: type: string pattern: ^0x[0-9a-fA-F]{64}$ keyIdHash: type: string pattern: ^0x[0-9a-fA-F]{64}$ payer: type: string pattern: ^0x[0-9a-fA-F]{40}$ recipient: type: string pattern: ^0x[0-9a-fA-F]{40}$ tokenIn: type: string pattern: ^0x[0-9a-fA-F]{40}$ amountIn: type: string pattern: ^[0-9]+$ tokenOut: type: string pattern: ^0x[0-9a-fA-F]{40}$ grossAmountOut: type: string pattern: ^[0-9]+$ routeFee: type: string pattern: ^[0-9]+$ builderFee: type: string pattern: ^[0-9]+$ amountOut: type: string pattern: ^[0-9]+$ builderRecipient: type: string pattern: ^0x[0-9a-fA-F]{40}$ policyVersion: type: string pattern: ^[0-9]+$ hash: type: string pattern: ^0x[0-9a-fA-F]{64}$ blockNumber: type: string pattern: ^[0-9]+$ blockHash: type: string pattern: ^0x[0-9a-fA-F]{64}$ logIndex: type: integer status: type: string const: finalized required: - quoteId - builderCode - builderId - keyIdHash - payer - recipient - tokenIn - amountIn - tokenOut - grossAmountOut - routeFee - builderFee - amountOut - builderRecipient - policyVersion - hash - blockNumber - blockHash - logIndex - status additionalProperties: false nextCursor: type: - string - 'null' scannedFrom: type: string pattern: ^[0-9]+$ scannedThrough: type: string pattern: ^[0-9]+$ finalizedThrough: type: string pattern: ^[0-9]+$ snapshotHash: type: string pattern: ^0x[0-9a-fA-F]{64}$ totalsByToken: type: array items: type: object properties: tokenOut: type: string pattern: ^0x[0-9a-fA-F]{40}$ grossAmountOut: type: string pattern: ^[0-9]+$ routeFee: type: string pattern: ^[0-9]+$ builderFee: type: string pattern: ^[0-9]+$ amountOut: type: string pattern: ^[0-9]+$ count: type: integer required: - tokenOut - grossAmountOut - routeFee - builderFee - amountOut - count additionalProperties: false totalsScope: const: page type: string required: - code - builderId - settlements - nextCursor - finalizedThrough - totalsByToken - totalsScope additionalProperties: false '400': description: Malformed input, invalid code/cursor or fee above cap '401': description: Missing or invalid API key '403': description: Missing required API key scope '404': description: Builder not registered (lookup) '409': description: Registry operation rejected or history snapshot changed '429': description: Caller workspace or global rate limit '503': description: >- Registry/collector not commissioned, RPC unavailable, or verification/capacity failure security: - BuilderKey: [] components: securitySchemes: BuilderKey: type: apiKey in: header name: x-api-key description: >- Server-side key created in an authenticated developer workspace. Builder codes are public attribution, not credentials. ````