> ## 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.

# Set your builder fee rules

> Set or delete your builder fee rules.

 Upserts and deletes add-on rules in one save: all of it is written or none
 of it is. One call is one change against your daily change limit, however
 many rules it writes; a call that changes nothing is free. Each rule
 scopes your add-on by wallet (one with an account on your application),
 trading pair or market type, and track. Monaco's OVERRIDE rules cannot be
 deleted here, and any that match an order win over your rules. A rule above the cap that applies is saved and charged at
 the cap.

 Refused (**HTTP 403** / **FAILED_PRECONDITION**) until Monaco turns
 scoped builder fee rules on: check `builderFeeRulesEnabled` in
 `GetBuildercodesConfig` first, and use `SetBuilderFee` until then.



## OpenAPI

````yaml /proto-openapi/api/openapi.yaml put /api/v1/buildercodes/rules
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://apimonaco.xyz
    description: Production (Sei mainnet)
security: []
tags:
  - name: AccountsService
  - name: AnalyticsService
  - name: ApplicationsService
  - name: AuthService
  - name: BuildercodeRewardsService
  - name: ComplianceService
  - 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: RfqService
  - name: SweeperService
  - name: TraderCodeService
  - name: TradesService
  - name: WithdrawalsService
paths:
  /api/v1/buildercodes/rules:
    put:
      tags:
        - BuildercodeRewardsService
        - BuilderCodes
      summary: Set your builder fee rules
      description: |-
        Set or delete your builder fee rules.

         Upserts and deletes add-on rules in one save: all of it is written or none
         of it is. One call is one change against your daily change limit, however
         many rules it writes; a call that changes nothing is free. Each rule
         scopes your add-on by wallet (one with an account on your application),
         trading pair or market type, and track. Monaco's OVERRIDE rules cannot be
         deleted here, and any that match an order win over your rules. A rule above the cap that applies is saved and charged at
         the cap.

         Refused (**HTTP 403** / **FAILED_PRECONDITION**) until Monaco turns
         scoped builder fee rules on: check `builderFeeRulesEnabled` in
         `GetBuildercodesConfig` first, and use `SetBuilderFee` until then.
      operationId: set_builder_rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetBuilderRulesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetBuilderRulesResponse'
        '400':
          description: >-
            Invalid input: a malformed scope or rate, a wallet with no account
            on this application, the same scope twice, or too many rules in one
            save or for this application (gRPC: INVALID_ARGUMENT)
        '401':
          description: Authentication required
        '403':
          description: >-
            Refused: neither the revenue share nor builder fees are switched on,
            scoped builder fee rules are not on yet, the request deletes the
            scope of a Monaco override, the caller is delegated, or the caller
            is not this application's payout wallet (gRPC: PERMISSION_DENIED, or
            FAILED_PRECONDITION while scoped rules are off)
        '404':
          description: >-
            Authenticated application not found, or a deleted rule does not
            exist (gRPC: NOT_FOUND)
        '409':
          description: >-
            The application has already used every change the limit allows in
            the last 24 hours; carries `details.nextChangeAllowedAt` (gRPC:
            FAILED_PRECONDITION)
        '500':
          description: Internal server error
      security:
        - monacoSignature: []
        - monacoHttpSignature: []
components:
  schemas:
    SetBuilderRulesRequest:
      type: object
      properties:
        upserts:
          type: array
          items:
            $ref: '#/components/schemas/BuilderAddOnRuleInput'
          description: Rules to create or change, each by its scope.
          nullable: true
        deletes:
          type: array
          items:
            $ref: '#/components/schemas/BuilderRuleScope'
          description: >-
            Scopes of your rules to delete. Your default rule (no wallet, every
            market, both tracks) is set with `SetBuilderFee` and cannot be
            changed or deleted here; nor can an upsert name it.
          nullable: true
        note:
          type: string
          description: A note saved with every rule this call writes.
          nullable: true
      additionalProperties: false
    SetBuilderRulesResponse:
      type: object
      properties:
        changes:
          type: array
          items:
            $ref: '#/components/schemas/BuilderRuleChange'
          description: Every rule this call changed; empty when it changed nothing.
          nullable: true
        changesRemaining:
          example: 49
          maximum: 500
          type: integer
          description: >-
            Changes this application can still make in the current rolling 24
            hours.
          format: uint32
          nullable: true
        nextChangeAllowedAt:
          type: string
          description: >-
            RFC 3339 time at which the next change becomes allowed, or null
            while `changesRemaining` is above 0.
          format: date-time
          nullable: true
    BuilderAddOnRuleInput:
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/BuilderRuleScope'
        makerCbps:
          example: 150
          maximum: 10000
          type: integer
          description: The maker add-on, in centi-bps (100 cbps = 1 bps).
          format: int32
          nullable: true
        takerCbps:
          example: 250
          maximum: 10000
          type: integer
          description: The taker add-on, in centi-bps (100 cbps = 1 bps).
          format: int32
          nullable: true
    BuilderRuleScope:
      type: object
      properties:
        walletAddress:
          example: '0x0000000000000000000000000000000000000001'
          type: string
          description: >-
            The wallet the rule applies to, lowercase `0x` and 40 hex digits; it
            must have an account on your application. Omit for every wallet.
          nullable: true
          pattern: ^0x[0-9a-fA-F]{40}$
          minLength: 42
          maxLength: 42
        tradingPairId:
          type: string
          description: >-
            The trading pair the rule applies to. Omit for every pair. At most
            one of `tradingPairId` and `marketType`.
          format: uuid
          nullable: true
        marketType:
          example: SPOT
          enum:
            - SPOT
            - MARGIN
          type: string
          description: >-
            The market type the rule applies to. Omit for every market. At most
            one of `tradingPairId` and `marketType`.
          nullable: true
        track:
          example: BOTH
          enum:
            - CLOB
            - RFQ
            - BOTH
          type: string
          description: >-
            The track the rule applies to: `CLOB` (the order book), `RFQ`, or
            `BOTH`.
          nullable: true
    BuilderRuleChange:
      type: object
      properties:
        op:
          example: SET
          enum:
            - SET
            - DELETE
          type: string
          description: '`SET` for a created or changed rule, `DELETE` for a deleted one.'
          nullable: true
        scope:
          $ref: '#/components/schemas/BuilderRuleScope'
        makerCbpsBefore:
          type: integer
          description: The maker add-on before, in centi-bps; null for a new rule.
          format: int32
          nullable: true
        takerCbpsBefore:
          type: integer
          description: The taker add-on before, in centi-bps; null for a new rule.
          format: int32
          nullable: true
        makerCbpsAfter:
          type: integer
          description: The maker add-on after, in centi-bps; null for a deleted rule.
          format: int32
          nullable: true
        takerCbpsAfter:
          type: integer
          description: The taker add-on after, in centi-bps; null for a deleted rule.
          format: int32
          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.