> ## 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. # Claim accrued BuilderCodes payout balance > Claim accrued BuilderCodes payout balance. Move accrued BuilderCodes payout balance from your reserved payout bucket into a trading balance under the authenticated application, making it withdrawable through the ordinary withdrawal flow. Ledger-only (one shared vault + one backend ledger) — no on-chain transaction and no gas. The bucket is resolved from the AUTHENTICATED caller's own wallet address, never from the request body, so a caller can only ever claim their own accrued balance. A wallet that has never been an enrolled frontend's payout address simply has an empty bucket. A wallet that USED to be a payout address keeps whatever it accrued back then and can still claim it — payout-address changes are not retroactive, so current enrollment is deliberately not required. The payout wallet may be an EOA or a smart-contract wallet. An EOA answers Monaco's signature challenge directly. A contract wallet — a multisig such as a Safe — holds no private key and cannot, so it authenticates by EIP-1271 contract signature instead: Monaco asks the wallet contract whether it accepts the challenge. That path is deliberately narrow. It is offered only to a wallet that holds a BuilderCodes payout bucket, only while the `contract_wallet_auth_enabled` flag is on, and only where the deployment has a chain RPC endpoint configured. While any of those is not met, login is EOA-only and a contract payout wallet can neither call this endpoint nor withdraw afterwards, so its accrued share stays unclaimable. Delegated-agent sessions are refused: a delegated grant conveys only order-management authority, and this claim converts reserved balance into a tradeable one. No program switch gates the claim: a balance already credited stays claimable whether or not the revenue share is on. Transport contracts differ, and this comment is emitted into the generated gRPC SDK where HTTP statuses do not exist. An insufficient payout balance is **HTTP 409** on REST and **FAILED_PRECONDITION** on gRPC; a refused caller (delegated session) is **HTTP 403** on REST and **PERMISSION_DENIED** on gRPC. A claim can also fail as **HTTP 503** / **UNAVAILABLE** when the matching engine is unreachable, restarting, or slow to answer. Treat that as an UNKNOWN outcome, NOT a rejection. The request is admitted to the sequencer before its reply is sent, so a claim that timed out in transit may still commit, and there is no idempotency key — a blind retry can claim a SECOND time. Do NOT retry automatically, and do not settle it with a balance read: an admitted claim can still be sitting in the sequencer queue when the balance is read, so an unchanged balance does not prove the claim will not commit. Treat the claim as PENDING rather than failed, re-check once the engine is healthy again, and reconcile before issuing another claim. Not every 503 is ambiguous, and the safe ones are tagged. TWO outcomes are refused BEFORE the claim can be admitted to the sequencer, so they left no durable-log or state footprint and definitely committed nothing. One is a deliberate maintenance block, where REST carries `"error": "OPERATIONS_BLOCKED"` and gRPC tags the status with `x-maintenance-blocked: true`. The other is a sequencer admission rejection when the engine is saturated, where REST carries `"code": "OVERLOADED"` and gRPC carries the same code in the status' error details. Both are safe to retry with backoff, and an overload positively wants one. Only an UNTAGGED availability failure — matching-engine transport, timeout and fail-closed paths — carries the unknown outcome. A claim spends the per-user movement budget withdrawals and collateral transfers share. Over budget it is refused with **HTTP 429** / **RESOURCE_EXHAUSTED** before it reaches the sequencer, so it committed nothing and is safe to retry after the interval in `details.retryAfter`. ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml post /api/v1/buildercodes/rewards/claim 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/rewards/claim: post: tags: - BuildercodeRewardsService - BuilderCodes summary: Claim accrued BuilderCodes payout balance description: |- Claim accrued BuilderCodes payout balance. Move accrued BuilderCodes payout balance from your reserved payout bucket into a trading balance under the authenticated application, making it withdrawable through the ordinary withdrawal flow. Ledger-only (one shared vault + one backend ledger) — no on-chain transaction and no gas. The bucket is resolved from the AUTHENTICATED caller's own wallet address, never from the request body, so a caller can only ever claim their own accrued balance. A wallet that has never been an enrolled frontend's payout address simply has an empty bucket. A wallet that USED to be a payout address keeps whatever it accrued back then and can still claim it — payout-address changes are not retroactive, so current enrollment is deliberately not required. The payout wallet may be an EOA or a smart-contract wallet. An EOA answers Monaco's signature challenge directly. A contract wallet — a multisig such as a Safe — holds no private key and cannot, so it authenticates by EIP-1271 contract signature instead: Monaco asks the wallet contract whether it accepts the challenge. That path is deliberately narrow. It is offered only to a wallet that holds a BuilderCodes payout bucket, only while the `contract_wallet_auth_enabled` flag is on, and only where the deployment has a chain RPC endpoint configured. While any of those is not met, login is EOA-only and a contract payout wallet can neither call this endpoint nor withdraw afterwards, so its accrued share stays unclaimable. Delegated-agent sessions are refused: a delegated grant conveys only order-management authority, and this claim converts reserved balance into a tradeable one. No program switch gates the claim: a balance already credited stays claimable whether or not the revenue share is on. Transport contracts differ, and this comment is emitted into the generated gRPC SDK where HTTP statuses do not exist. An insufficient payout balance is **HTTP 409** on REST and **FAILED_PRECONDITION** on gRPC; a refused caller (delegated session) is **HTTP 403** on REST and **PERMISSION_DENIED** on gRPC. A claim can also fail as **HTTP 503** / **UNAVAILABLE** when the matching engine is unreachable, restarting, or slow to answer. Treat that as an UNKNOWN outcome, NOT a rejection. The request is admitted to the sequencer before its reply is sent, so a claim that timed out in transit may still commit, and there is no idempotency key — a blind retry can claim a SECOND time. Do NOT retry automatically, and do not settle it with a balance read: an admitted claim can still be sitting in the sequencer queue when the balance is read, so an unchanged balance does not prove the claim will not commit. Treat the claim as PENDING rather than failed, re-check once the engine is healthy again, and reconcile before issuing another claim. Not every 503 is ambiguous, and the safe ones are tagged. TWO outcomes are refused BEFORE the claim can be admitted to the sequencer, so they left no durable-log or state footprint and definitely committed nothing. One is a deliberate maintenance block, where REST carries `"error": "OPERATIONS_BLOCKED"` and gRPC tags the status with `x-maintenance-blocked: true`. The other is a sequencer admission rejection when the engine is saturated, where REST carries `"code": "OVERLOADED"` and gRPC carries the same code in the status' error details. Both are safe to retry with backoff, and an overload positively wants one. Only an UNTAGGED availability failure — matching-engine transport, timeout and fail-closed paths — carries the unknown outcome. A claim spends the per-user movement budget withdrawals and collateral transfers share. Over budget it is refused with **HTTP 429** / **RESOURCE_EXHAUSTED** before it reaches the sequencer, so it committed nothing and is safe to retry after the interval in `details.retryAfter`. operationId: claim_buildercode_rewards requestBody: content: application/json: schema: $ref: '#/components/schemas/ClaimBuildercodeRewardsRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ClaimBuildercodeRewardsResponse' '400': description: Invalid token or amount '401': description: Authentication required '403': description: >- Refused: the caller is a delegated-agent session (gRPC: PERMISSION_DENIED) '409': description: >- Insufficient BuilderCodes payout balance, including a wallet that never accrued one (gRPC: FAILED_PRECONDITION) '429': description: >- Movement rate limit exceeded — withdrawals, collateral transfers and reward transfers share a per-user budget; refused before the claim reaches the sequencer, so nothing committed; retry after the interval in details.retryAfter (gRPC: RESOURCE_EXHAUSTED) '500': description: Internal server error '503': description: >- Matching engine unavailable or slow to answer. Outcome UNKNOWN, not a rejection — the claim may still commit and there is no idempotency key, so treat it as pending and do not retry automatically; a balance read does not settle it, because an admitted claim may still be queued. Two tagged cases are the exception, both refused before the claim can be admitted and so provably non-committing, and both safe to retry: a maintenance block (`error: OPERATIONS_BLOCKED`; gRPC metadata `x-maintenance-blocked: true`) and a sequencer overload (`code: OVERLOADED`) (gRPC: UNAVAILABLE) security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: ClaimBuildercodeRewardsRequest: required: - token - amount type: object properties: token: example: '0x0000000000000000000000000000000000000002' type: string description: >- Payout token contract address (0x-prefixed) to claim. BuilderCodes shares accrue in the quote token of the traded pair. amount: example: '1000000' type: string description: >- Amount to claim, in RAW atomic units of the token. Must be positive and no greater than the accrued payout balance. additionalProperties: false ClaimBuildercodeRewardsResponse: type: object properties: payoutBalance: example: '0' type: string description: >- Your BuilderCodes payout-bucket balance after the claim, RAW atomic units. nullable: true tradingBalance: example: '1000000' type: string description: >- Your trading balance for the token after the claim, RAW atomic units. 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.