Partner attribution

Partner Attribution works on binary options with the same approval, order fields, tier requirements and reporting. This page covers the binary options parameters and fee calculation.

Client approval

Binary options are governed by the spot limits of the client's ApproveIntegrator: max_spot_taker_fee and max_spot_maker_fee. There is no binary-options-specific field. A client who has approved you with spot limits needs no new approval; a perps-only approval (spot limits 0) must be re-sent with spot limits.

System-wide maximum

The spot maximum applies: max_integrator_spot_taker_fee / max_integrator_spot_maker_fee in systemConfig, currently 10000 = 1% (perps: 1000 = 0.1%). Fee units are unchanged: 1e6 = 100%, 100 = 1 bp.

Order fields

integratorAccountIndex, integratorTakerFee, integratorMakerFee on CreateOrder / ModifyOrder, exactly as on other markets. Non-zero fees require a Plus or Premium/Advanced client (21520 otherwise); zero-fee attribution works on Standard. 21149 not approved / expired, 21150 above the approved maximum.

Fee calculation

The integrator fee you set is a maximum rate, scaled by the same price curve as the market fee and charged in USDC on the notional, to the side it applies to:

integratorFee = integratorRate × size × P × (1 − P)

The client's bo_fee_rate discount applies to the market fee only, not to the integrator fee.

Example

With integratorTakerFee = 5000 (a maximum rate of 0.5%), the client buys 100 Up shares at 0.51 as a taker. For the market fee, this example assumes bo_fee_rate = 1. Use integratorRate = 0.005 in the formula.

notional         = 100 × 0.51                    = 51.00 USDC
integrator rate  = 0.005 × (1 − 0.51)             = 0.00245 (0.245%)
integrator fee   = 51.00 × 0.00245                = 0.12495 USDC
market taker fee = 0.01 × (1 − 0.51) × 51.00     = 0.2499 USDC

The corresponding trade rates are integrator_taker_fee: 2450 and taker_fee: 4900. These are rate ticks, not fee amounts in USDC. The rate stored in a trade is already scaled by the price curve. Compute the actual fee as usd_amount × integrator_taker_fee / 1e6 (or the maker field for the maker side); do not multiply by (1 − P) again.

Python

Use an initialized client and a current MARKET_ID from Discover markets. PARTNER_ACCOUNT_INDEX is the approved fee-collecting account.

tx, tx_hash, err = await client.create_order(
    market_index=MARKET_ID,
    client_order_index=1234,
    base_amount=1000000,
    price=51,
    is_ask=False,
    order_type=client.ORDER_TYPE_LIMIT,
    time_in_force=client.ORDER_TIME_IN_FORCE_IMMEDIATE_OR_CANCEL,
    reduce_only=False,
    order_expiry=client.DEFAULT_IOC_EXPIRY,
    integrator_account_index=PARTNER_ACCOUNT_INDEX,
    integrator_taker_fee=5000,   # 0.5% max rate, ≤ client's max_spot_taker_fee
    integrator_maker_fee=0,
)

Reporting

Trades expose integrator_taker_fee, integrator_taker_fee_collector_index, integrator_maker_fee, integrator_maker_fee_collector_index (effective rate after scaling); filter with GET /api/v1/trades?integrator_account_index=<partner>&market_type=bo. Orders expose the requested integrator_taker_fee / integrator_maker_fee and integrator_fee_collector_index. partnerStats includes binary options volume and fees together with perps and spot. Fees are credited to the integrator account in USDC in the execution cycle after the trade.