MNXDocs

Builder codes

An app, bot platform or other interface that places orders for traders can tag those orders with its builder code. MNX pays a registered builder a share of the trading fee it charges on the fills of its tagged orders. Traders pay the usual trading fees: the builder's share comes out of the fee MNX charges, never on top of it.

Becoming a builder

During the beta, MNX approves every builder. To become one, email builders@mnx.fi:

  1. You sign the builder agreement.
  2. MNX screens the MNX account you will earn with, and checks your app's name against the other builders': names are plain ASCII and unique whatever their letter case, and MNX turns down a name made to look like another's.
  3. MNX registers the account with your app's name, site and logo, and your share of each fee, in basis points (one basis point is 0.01%), at most half of the fee.

Your builder code is that account's wallet address. MNX can change your share, or suspend you; a change applies from the moment MNX makes it, and each fill keeps the terms in force when its batch settled. Your name, site, logo, status and share are public, with your totals and your payouts, including each fill a payout pays you for and the trading account that made it.

Tagging orders

Send your code as the optional builder field of each order you place with POST /v0/orders or POST /v0/orders/place/batch, alongside the signed order (see Placing orders):

{
  "market_id": 1,
  "side": "LONG",
  "...": "the signed order's other fields",
  "builder": "0x1234567890abcdef1234567890abcdef12345678"
}
  • The code is not part of the signed order, so signing does not change, and any credential that may place the order can send it.
  • The exchange records it in lowercase on the order, which returns it as builder. A resend of the same signed order with another code is refused with HTTP 409.
  • Placement checks only that the code is an address. A code that is not a registered builder's earns nothing, and orders naming a suspended builder still trade.
  • On mnx.fi, traders see your app's name on the orders you placed and on their trades. Each row of GET /v0/fills/by-user/:user_id, one batch's fills, lists the codes on the orders behind it in builders. A code that no registered builder has shows as unregistered.
  • Child-vault orders do not take a builder code.

How earnings are counted

Every few minutes, once a batch has settled on chain, MNX records each fill of a tagged order. A fill earns your share of the fee the chain charged on it, rounded down to the smallest unit of USDM:

reward = charged fee × share_bps / 10000
  • The fee is the one the chain actually charged the trader's account in the batch, at most the fee planned when the batch was sealed: a discount, or a closing fee capped at the position's equity, lowers it. The chain charges an account one fee for the batch, which does not say which fills it was for. So your fills are credited at most what that fee leaves after the planned fees of the account's other fills in the batch, those without a code and those of other builders, shared among your fills in proportion to their planned fees. A fill can therefore earn less than it was charged when the account traded other fills in the same batch.
  • Under the standard fee schedule makers pay no fee, so the taker side of a fill earns and the maker side earns nothing.
  • The terms that apply are those in force when the fill's batch settled.
  • Batches normally settle within seconds of being sealed. A fill whose batch takes more than an hour to settle is counted only once MNX recovers it by hand.

A tagged fill earns nothing when:

  • the trader's referral is still earning: their referrer is paid instead, as one partner is paid per fill; once the referral ends, the trader's tagged fills earn for you;
  • the order is your own account's;
  • you are suspended when its batch settles; or
  • the chain charged the account no fee in the batch, or the account's other fills in the same batch, without a code or of other builders, took all of the fee it charged.

MNX can void a builder's unpaid earnings for abuse, such as trading with itself or related accounts, which the builder agreement forbids. Voided earnings are never paid.

Public builder data

Anyone can read each builder's terms and totals without signing in. Address a builder by its code in lowercase:

curl "https://api.testnet.mnx.fi/v0/builders"
curl "https://api.testnet.mnx.fi/v0/builders/0x1234567890abcdef1234567890abcdef12345678"

Each builder shows its name, site, logo, status, share of each fee in basis points (share_bps), the time its status and share took effect (terms_starts_at), and running totals: the volume of its tagged fills, the fees charged on them, the rewards earned, the number of traders, and its earnings unpaid, in a payout, paid and voided. The totals leave out the builder's own account. accrued_through says how far earnings are counted. MNX publishes individual fills only as the fills each payout pays for (see Payouts); fills in no payout are not listed one by one.

Rewards divided by fees can differ from the current share: each fill keeps the terms in force when its batch settled, rewards are rounded down, and the fees include fills that earned nothing, such as those a trader's referral took or those that settled while the builder was suspended.

Payouts

MNX pays builder earnings in payouts, intended weekly. A payout takes each builder's unpaid earnings that settled before its cutoff, when they reach its minimum; smaller amounts wait for a later payout. A builder is paid with an ordinary deposit into its MNX account's margin balance, from a wallet used for that payout alone. Earnings of a suspended builder wait until it is resumed.

GET /v0/builder-payouts lists the payouts, newest first, and GET /v0/builder-payouts/:payout_id shows one with its lines: each builder's code, amount and number of fills, and once paid, the deposit that paid it (its transaction hash and the log's position within the transaction).

GET /v0/builder-payouts/:payout_id/fills lists the fills a payout pays for, a page at a time in fill id order, so that anyone can check each line against the chain before it is paid. Each fill shows its id, the builder's code, the address of the trading account that placed the order, the market, the fill's volume, the fee planned and the fee charged, the share, the reward, and when its batch settled. Its charge_event_key names the log the charged fee came from: the trader's BatchTradeExecuted log in the settlement transaction, which carries the account's whole fee for the batch, as perpetual:<tx hash>:<log index>:batch-trade-realized-pnl:user:<user id>. A line's amount is the sum of the rewards of its builder's fills there.

curl "https://api.testnet.mnx.fi/v0/builder-payouts/1/fills?limit=100"

So the traders who use your code are public, by their account's address, once a payout pays you for their fills. A payout MNX voids before paying it lists no fills: they return to your unpaid earnings for a later payout, unless MNX has voided those earnings.