Builder Codes

Overview

Builder codes let front-end applications and integrators earn a share of trading fees from the order flow they direct to RISEx. Similar to a referral system, but designed for builders creating trading interfaces, bots, and aggregators.

A builder attaches its builder_id and a small fee to the orders it submits on a trader's behalf. When those orders fill, the builder fee is charged to the trader and paid to the builder's fee_recipient.

How it works

1. Register your builder code (permissionless, no approval needed) to get a builder_id, providing the fee_recipient that receives your fees. Confirm it appears in GET /v1/builders.
2. The trader registers an API wallet (a session key), so you are not prompting their main wallet for every order.
3. The trader approves your fee once, which caps the fee your builder_id can charge them.
4. You place orders carrying your builder_id and builder_fee_bps. Fees accrue to your fee_recipient.

Integration steps

1. Register your builder code

Builder registration is permissionless: any integrator can register directly, with no approval from the RISEx team. Call registerBuilderCode(feeRecipient) on the FeeManager contract, passing the address that should receive your builder fees. It returns your builder_id.

Confirm your builder appears in GET /v1/builders, then attach the returned builder_id to every order you submit.

2. Register an API wallet (session key)

Generate a session key for the trader and register it. The trader signs a RegisterSigner message once with their main wallet; the session key signs everything after that.

See Register Signer for the full flow. POST /v1/auth/register-signer.

3. Approve the builder fee (one time per trader and builder)

The trader authorizes a maximum fee your builder_id can charge them. This is signed by the session key inside a VerifyWitness permit (see Creating Permit Params).

POST /v1/orders/builder-fee/approve

The action hash the permit wraps is:

actionHash = keccak256(abi.encode(
  keccak256("RISE_APPROVE_BUILDER_FEE_V1"),
  uint16(builderId),
  uint16(maxFeeBps)
));

4. Place orders with your builder code

Attach builder_id and builder_fee_bps to each order (see Place Order for the base flow). Setting builder_id != 0 selects the V3 order layout, which includes the fee word in the signed action hash:

actionHash = keccak256(abi.encode(
  typeHash, uint8(flags), uint88(orderData),
  uint16(builderId), uint16(builderFeeBps),
  uint64(clientOrderId), uint16(ttlUnits)
));

The builderFeeBps word sits right after builderId. When builder_id == 0, the older layout is used and there is no fee word.

Request body

{
  "market_id": 1,
  "size_steps": 200,
  "price_ticks": 0,
  "side": 0,
  "post_only": false,
  "reduce_only": false,
  "stp_mode": 0,
  "order_type": 0,
  "time_in_force": 3,
  "builder_id": 1,
  "builder_fee_bps": 100,
  "client_order_id": "0",
  "ttl_units": 0,
  "permit": {
    "account": "0x...",
    "signer": "0x...",
    "nonce_anchor": 0,
    "nonce_bitmap_index": 0,
    "deadline": 0,
    "signature": "<base64>"
  }
}

Common errors

Verifying a fill

After an order fills, GET /v1/trade-history?account={account} returns the fill with the fee charged. The builder portion is included in the total fee and paid to your fee_recipient.

For the complete endpoint reference, see the Full API Documentation.