`approveBuilderFee`

Approves a builder to charge the signing user up to maxFeeRate. Submitting the action again for the same builder updates the existing rate.

POST/exchangetype approveBuilderFee

Let a builder charge this user a fee, up to a max rate.Direct EIP-712, signed by the account key

Action fields

apiVersioninteger · uint32required

TxFlow signing API version.

builderstring · addressrequired

Builder wallet to approve.

chainIdinteger · uint32required

TxFlow chain ID.

maxFeeRatestringrequired

Maximum percentage, for example `0.02%`. Must be greater than zero and at most `1%`.

nonceinteger · uint64required

Fresh millisecond timestamp. Direct EIP-712 actions carry the nonce inside the action as well as in the outer payload; the two must match.

txflowNetworkstringrequired

TxFlow network name used by the EIP-712 action and domain.

typestringrequired

Must be `approveBuilderFee`.

"approveBuilderFee"

Request example

curl -X POST https://rpc.txflow-testnet.xyz/exchange \
  -H "Content-Type: application/json" \
  -H "x-api-version: 2026-08-16" \
  -d '{
  "action": {
    "type": "approveBuilderFee",
    "txflowNetwork": "TxFlow-Testnet",
    "chainId": 2511,
    "apiVersion": 1,
    "builder": "0x2e4D75df2eE2653EA7a113cC1Fa36D45E923061F",
    "maxFeeRate": "0.02%",
    "nonce": 1757992743994
  },
  "signature": {
    "r": "0x<r>",
    "s": "0x<s>",
    "v": 27
  },
  "nonce": 1757992743994,
  "vaultAddress": null,
  "signatureChainId": null
}'

Try it

testnet · no account yet

Generates a throwaway key in your browser, claims testnet USDC and authorizes an agent key. The account is kept while you browse the docs and lost on reload.

Response · ApproveBuilderFee 200

codeinteger

`0` on success.

dataobject

typestring

The action's internal name, which does not always match the request `type`.

"ApproveBuilderFee"

statusstring

A rejected request returns `err` with a non-zero `code` and the reason in `message` (or `response`).

"ok"

Response example

{
  "status": "ok",
  "code": 0,
  "data": {
    "type": "ApproveBuilderFee",
    "data": {
      "statuses": [
        "success"
      ]
    }
  }
}

A user may approve up to 20 distinct builders. The builder cannot be the zero address, the signing user, or a vault. Updating an already approved builder does not consume another slot.

maxFeeRate is a percentage string, greater than 0% and at most 1% — the highest per-market cap, since an approval is builder-level rather than per-market. The lower perpetual cap still applies per order.

Signing

This action is signed directly by the account key as the ApproveBuilderFee EIP-712 primary type:

ApproveBuilderFee(string txflowNetwork,uint32 chainId,uint32 apiVersion,address builder,string maxFeeRate,uint64 nonce)

The signed message contains the action's business fields without the wire-level type discriminator:

{
  "type": "approveBuilderFee",
  "txflowNetwork": "TxFlow-Testnet",
  "chainId": 2511,
  "apiVersion": 1,
  "builder": "0x2e4D75df2eE2653EA7a113cC1Fa36D45E923061F",
  "maxFeeRate": "0.02%",
  "nonce": 1757992743994
}

The distinct ApproveBuilderFee typehash separates this action from revokeBuilderFee. The replay nonce is the body's own nonce, so send the same value in the envelope.

The recovered signer must be the approving user itself; an authorized agent cannot approve on the owner's behalf. When the outer payload carries signatureChainId, use it for domain.chainId while keeping the action's business chainId unchanged in the struct hash. See Signing.

Next steps

The approval takes effect once the action is included in a block; subsequent orders may carry this builder up to the approved rate — see Attach a builder to an order.