> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt > Use this file to discover all available pages before exploring further. # List your per-trade BuilderCodes earnings > List this application's per-trade BuilderCodes earnings. Newest credits are returned first. The application is taken from the authenticated session and cannot be selected by the caller. ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml get /api/v1/buildercodes/payouts openapi: 3.0.3 info: title: Monaco Protocol API description: REST API for the Monaco Protocol hybrid CLOB exchange. version: 1.0.0 servers: - url: https://staging.apimonaco.xyz description: Staging server (Testnet) security: [] tags: - name: AccountsService - name: ApplicationsService - name: AuthService - name: BuildercodeRewardsService - name: CopyTradingService - name: DelegatedAgentsService - name: FaucetService - name: FeesService - name: HealthService - name: ManagedMarketsService description: |- Wallet-authenticated maker assignments. The signed session must match both configured maker user and application. Owner IDs are process fences, never auth. Only wallet sessions are supported; delegated-agent sessions receive 403. - name: MarginAccountsService description: |- Current public isolated-margin semantics: - a user has one parent margin account per application scope - opening orders create or reuse isolated position buckets under that parent - parent account creation is handled internally by margin workflows - name: MarketService - name: OrderbookService - name: OrdersService - name: PositionsService description: |- Current public isolated-margin semantics: - positions link to a parent margin account and, when applicable, a bucket id - opening orders create or reuse isolated position buckets under the parent - users can open another isolated position by reusing the parent account with a different market bucket - name: PulseService - name: SweeperService - name: TraderCodeService - name: TradesService - name: WhitelistService - name: WithdrawalsService paths: /api/v1/buildercodes/payouts: get: tags: - BuildercodeRewardsService - BuilderCodes summary: List your per-trade BuilderCodes earnings description: |- List this application's per-trade BuilderCodes earnings. Newest credits are returned first. The application is taken from the authenticated session and cannot be selected by the caller. operationId: list_buildercode_payouts parameters: - name: pageSize in: query schema: type: integer format: uint32 minimum: 1 maximum: 1000 default: 20 description: Items per page (max 1000) - name: pageToken in: query description: |- Pagination cursor with two states: - Omitted or empty string (""): start a cursor walk with no prior position, from the newest credit. - Non-empty: an opaque cursor from a previous response's `next_page_token`; results resume immediately after that position. The walk seeks on `(created_at, id)` descending, served by `idx_buildercode_payouts_application_created_id`, whose leading key is the caller's own application and whose remaining keys are this seek's, both descending. Both key columns are NOT NULL and fixed for a credit's lifetime. (Spelled without the column list on purpose: the read contract test asserts this request message never mentions a caller-selected identity.) This REPLACES the removed mode's `(sequence, sequence_ordinal, created_at, id)` order, whose two leading columns are nullable — no backfill exists for credits written before they did — and a nullable leading key cannot be a total cursor key: the NULL rows sort together at one end, and a seek through them would need a COALESCE no index covers. ORDERING CHANGE, not just a pagination change. The new key is total and stable — a page can neither skip nor duplicate a credit — but it is NOT chronological inside one persistor batch. `created_at` defaults to `NOW()`, which is transaction-start time, so every credit one batch writes shares an identical timestamp; the `id` tie-break defaults to `gen_random_uuid()`, which the persistor leaves alone. So within a batch the order is arbitrary and a LATER fill can be listed ahead of an earlier one. The removed order led with `sequence` and `sequence_ordinal` precisely because those carry the engine's fill order, and one entry routinely holds several credits (a taker sweeping N makers, or a flattened `BatchCreateOrders`). Preserving fill chronology would need those columns backfilled first, which is not possible for credits written before they existed. Across batches the order is still newest-first. `total` and `total_pages` are populated and exact, and count the rows the `kind` filter selects. Filters must match the request that produced the token, or the request is rejected 400. schema: type: string - name: kind in: query schema: type: string enum: - REVENUE_SHARE - BUILDER_FEE minLength: 1 description: >- Only return BuilderCodes payouts of this payout kind: REVENUE_SHARE (the frontend's share of Monaco's fee) or BUILDER_FEE (ordinary builder fees charged to takers and credited to enrolled applications). Omit for every kind. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListBuildercodePayoutsResponse' '400': description: Invalid pagination '401': description: Authentication required '403': description: >- Refused: the caller is delegated or is not this application's payout wallet (gRPC: PERMISSION_DENIED) '404': description: 'Authenticated application not found (gRPC: NOT_FOUND)' '500': description: Internal server error security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: ListBuildercodePayoutsResponse: type: object properties: payouts: type: array items: $ref: '#/components/schemas/BuildercodePayout' description: Per-trade credits, newest first. nullable: true total: type: integer description: Total payout rows for this application. format: uint32 nullable: true pageSize: type: integer description: Items per page. format: uint32 nullable: true totalPages: type: integer description: Total number of pages. format: uint32 nullable: true nextPageToken: type: string description: >- Cursor for the next page, minted from the last row of an over-fetched page: this listing is one ordered read, so a page shorter than `page_size` proves the walk is exhausted and this is empty. nullable: true BuildercodePayout: type: object properties: tradeId: type: string description: Trade that generated this credit. format: uuid nullable: true payoutAddress: example: '0x0000000000000000000000000000000000000001' type: string description: Application payout address at credit time. nullable: true token: example: '0x0000000000000000000000000000000000000002' type: string description: Credit token contract address. nullable: true amount: example: '1000000' type: string description: Credited amount in RAW atomic units of the token. nullable: true appliedBps: example: 1000 type: integer description: >- Basis-point rate applied to this credit. For `BUILDER_FEE`, this is the normalized builder-fee rate charged to the taker. For `REVENUE_SHARE`, it is the realized whole-basis-point rate for that fill and can be lower than the configured BuilderCodes budget. format: int32 nullable: true createdAt: type: string description: RFC 3339 credit timestamp. format: date-time nullable: true kind: example: REVENUE_SHARE enum: - REVENUE_SHARE - BUILDER_FEE type: string description: >- Payout category for this credit: `REVENUE_SHARE` for Monaco revenue sharing or `BUILDER_FEE` for an ordinary builder fee charged to the taker. nullable: true securitySchemes: monacoSignature: type: apiKey description: >- Ed25519 session-key request signing. Every authenticated request carries three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of server time), and `X-Monaco-Signature` (hex ed25519 signature). The signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`, where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from `POST /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`. name: X-Monaco-Signature in: header monacoHttpSignature: type: apiKey description: >- RFC 9421 Ed25519 session-key request signatures. Send Signature-Input, Signature, and Content-Digest together; never combine them with X-Monaco-* credentials. The monaco signature covers @method, @path, @query, and content-digest in that order, with created (Unix seconds within 30s of server time), keyid (registered lowercase-hex session public key), and alg=ed25519 parameters. Content-Digest uses RFC 9530 sha-256 over the exact body bytes, including the empty body. Query coverage retains ordering and percent encoding. Timestamp freshness does not reject repeated identical requests; use endpoint idempotency where supported. Existing legacy signing remains supported during server-first migration; SDK RFC 9421 signing is opt-in. See https://docs.0xmonaco.com/reference/http-message-signatures for the complete profile and trust model. name: Signature in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.