Skip to main content

Builder Code – Client Integration

This article explains how to authorize a Builder API and create orders using builder fees.

Updated this week

1. Authorize Builder API

API Docs: Trading API – Gravity Markets API Docs
​

Signature Requirements:

  • max_futures_fee_rate and max_spot_fee_rate are in percentages (e.g., 0.1 = 0.1%).

  • Signer must have Account Admin Permission.

  • In the signature payload, maxFutureFeeRate and maxSpotFeeRate use 4 decimals:

    • Example:

      • Request: max_futures_fee_rate: "0.01" → Signature: maxFutureFeeRate = 0.01 * 10^4 = 100

      • Request: max_spot_fee_rate: "0.1" → Signature: maxSpotFeeRate = 0.1 * 10^4 = 1000

Signature Structure Example:

"AuthorizeBuilder": [   {"name": "mainAccountID", "type": "address"},   {"name": "builderAccountID", "type": "address"},   {"name": "maxFutureFeeRate", "type": "uint32"},   {"name": "maxSpotFeeRate", "type": "uint32"},   {"name": "nonce", "type": "uint32"},   {"name": "expiration", "type": "int64"} ]

2. Create Order with Builder

API Docs: Trading API – Gravity Markets API Docs

Steps:

  1. Specify the builder account ID in order.builder.

  2. Specify the builder fee in percentage in order.builder_fee (e.g., 0.1 = 0.1%).

  3. Sign the payload following the rules below.

Notes:

  • builderFee is in 4 decimals in the signature payload:

    • Example: builder_fee: "0.01" → Signature payload: builderFee = 0.01 * 10^4 = 100

Signature Structure Example:

"OrderWithBuilderFee": [   {"name": "subAccountID", "type": "uint64"},   {"name": "isMarket", "type": "bool"},   {"name": "timeInForce", "type": "uint8"},   {"name": "postOnly", "type": "bool"},   {"name": "reduceOnly", "type": "bool"},   {"name": "legs", "type": "OrderLeg[]"},   {"name": "builder", "type": "address"},   {"name": "builderFee", "type": "uint32"},   {"name": "nonce", "type": "uint32"},   {"name": "expiration", "type": "int64"} ]

OrderLeg Structure:

"OrderLeg": [   {"name": "assetID", "type": "uint256"},   {"name": "contractSize", "type": "uint64"},   {"name": "limitPrice", "type": "uint64"},   {"name": "isBuyingContract", "type": "bool"} ]

Notes for Developers:

  • Builder accounts allow a third-party or sub-account to place orders with its own fee settings.

  • Use this integration when you want to delegate order placement while controlling fee limits.

  • Always ensure payloads are signed with the correct decimal conversion for fees.

Did this answer your question?