Partner Integration

This guide explains how partners can integrate with Lighter programmatically to earn additional fees for trades executed through their applications. The program is permissionless, allowing any account index to be used to collect fees, including subaccounts.

Definitions

Partner: You, the integrator building on top of Lighter.

Client: Your user, or customer, whose transactions you send on their behalf. Both standard and premium accounts are accepted.

Integrator Approval

Before you can append partner attributes to client transactions, they must submit an ApproveIntegrator transaction. Approving an account index associated with a different L1 address requires an L1 signature. However, if the account index is associated with the same L1 address, only an L2 signature is needed, so the Ethereum private key can be omitted in that case. This transaction authorizes you to charge additional taker/maker fees on trades originating from orders created through your platform, as defined via the systemConfig endpoint.

At any point in time, there can only be a maximum of 4 approved Partners per Client.

Example (Python SDK)

client.approve_integrator(
        eth_private_key=STRING,
        integrator_account_index=INTEGER,
        max_perps_taker_fee=INTEGER,
        max_perps_maker_fee=INTEGER,
        max_spot_taker_fee=INTEGER,
        max_spot_maker_fee=INTEGER,
        approval_expiry=INTEGER # in ms  
    )

client.approve_integrator(
        eth_private_key="",
        integrator_account_index=1234,
        max_perps_taker_fee=1000, # 10 bps
        max_perps_maker_fee=1000, # 10 bps
        max_spot_taker_fee=1000,  # 10 bps
        max_spot_maker_fee=1000,  # 10 bps
        approval_expiry=1775518466000 # in ms
    )

You can find the full example here. To revoke an integrator before the allowance expires, you can send another ApproveIntegrator request setting all fees to zero.

Fields Explanation

IntegratorAccountIndex: Partner's account index. All partner fees collected from client trades will be credited to this account. For perpetual markets, the fees are paid and credited in USDC (perps). For spot markets, the fees are paid and credited in the received asset (e.g. buying spot ETH means the Client pays fees in ETH directly).

Max Fees: These values define the maximum fees you are allowed to charge your client.

Fees are calculated as:

fee(bps) = trade_size × (fee_value / 1e6)

Example:

MaxPerpsTakerFee = 500
500 / 1e6 = 0.0005 = 5 basis points

This means you can charge up to 5 bps of the trade quote for each perpetual taker order.

System-wide Maximums

Lighter enforces global maximum fee limits. If you submit an approval transaction exceeding these limits, the transaction will fail. Current limits can be checked via the systemConfig endpoint.

ApprovalExpiry

The timestamp when the integrator approval expires in a form of Unix timestamp in milliseconds. After this time, the partner must obtain approval again from the client.

The maximum value you can send is equivalent to 2^48-1.

Creating Orders for Your Client

Once the integrator approval is successfully submitted, you can begin sending transactions for the client and collecting partner fees.

When creating orders, include the following fields:

IntegratorAccountIndex: INTEGER # the partner account index, where integrator fees will accrue
IntegratorMakerFee: INTEGER     # fee the partner wants to charge for maker trades
IntegratorTakerFee: INTEGER     # fee the partner wants to charge for taker trades

These fees must not exceed the maximum values defined during the approval step.

Example: Creating an Order via Python SDK

client.create_order(
        market_index=0,
        client_order_index=0 # bound to 2^48-1
        base_amount=1000,  # decimals as described in the orderBookDetails endpoint
        price=4050_00,  # decimals as descibred in the orderBookDetails endpoin
        is_ask=True, # sell
        order_type=client.ORDER_TYPE_LIMIT,
        time_in_force=client.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
        reduce_only=False,
        trigger_price=0,
        integrator_account_index=integrator_account_index,
        integrator_taker_fee=integrator_taker_fee,
        integrator_maker_fee=integrator_maker_fee,
        nonce=nonce,
        api_key_index=api_key_index,
    )