Skip to main content
Order enums let builders apply custom trading fees per order by assigning an enum-backed order_tag such as enum:STRATEGY_DCA during order placement. Use this guide when your DEX, strategy backend, vault, bot flow, campaign, or broker-specific UX needs fee rules that differ by order category. This guide explains the integration flow and links to the API reference pages. It intentionally does not duplicate the full API specs.

​
Integration Flow

1

Create order enums

Builder admins create one or more order enums with a default_fee_rate and optional pair_overrides.Use POST /v1/broker/order_enum.
2

Expose active enums to your DEX

Your DEX or backend fetches active enums with broker_id so it can decide which enum to apply and disclose the extra fee to users.Use GET /v1/public/broker/order_enums.
3

Apply the enum during order placement

Set order_tag to enum:<UPPERCASE_ID> on supported order creation requests, for example enum:STRATEGY_DCA.Use POST /v1/order, POST /v1/batch-order, or POST /v1/algo/order.
4

Reconcile order and trade results

Read order_tag on orders for attribution and use trade-level fee fields for reporting and reconciliation.Use the order and trade APIs listed below.
5

Operate the enum lifecycle

Update fee rates, archive inactive enums, unarchive enums when needed, and review usage stats through admin APIs.

​
Public DEX Integration

Use GET /v1/public/broker/order_enums from your DEX or backend service to discover available order enums for a builder. The public list endpoint is unauthenticated and takes broker_id as a query parameter: 
GET /v1/public/broker/order_enums?broker_id={broker_id}
Optional filters include symbol, enum_id, and include_archived.

​
Fee Disclosure

The order enum fee is charged in addition to the user’s existing trading fee: 
final fee = trading fee + order enum fee
If pair_overrides includes the order symbol, use that symbol-specific enum fee rate. Otherwise, use default_fee_rate. Display the enum fee separately from the standard trading fee so users understand both components before placing an order.

​
Applying Order Enums to Orders

Set order_tag on supported order creation APIs:
APIIntegration note
POST /v1/orderSet order_tag on the order request body.
POST /v1/batch-orderSet order_tag on each order object inside orders that should use the enum.
POST /v1/algo/orderSet order_tag on the algo order request body.
order_tag supports two formats:
FormatExampleBehavior
Referral codeREFERRAL2026Plain string. Overrides the referral relationship.
Order enumenum:STRATEGY_DCAAdds the configured order enum fee on top of existing fees and preserves referral.
Order enum tags must use this format: 
enum:<UPPERCASE_ID>
order_tag is immutable after order placement. To change the enum on an open order, cancel the order and place a new one with the intended order_tag.

​
Returned Order and Trade Data

Use order APIs for attribution and UI display:
APIRelevant data
GET /v1/order/{order_id}Returns order_tag on the order.
GET /v1/client/order/{client_order_id}Returns order_tag on the order.
GET /v1/ordersReturns order_tag on each order row.
Use trade APIs for fee reporting and reconciliation:
APIRelevant data
GET /v1/tradesReturns fee, order_enum_fee, and order_enum_fee_rate on trade rows.
GET /v1/trade/{trade_id}Returns fee, order_enum_fee, and order_enum_fee_rate.
GET /v1/order/{order_id}/tradesReturns order trades with enum fee fields.
GET /v1/algo/order/{order_id}/tradesReturns algo order trades with enum fee fields.
On trade records, fee includes both the standard trading fee and the order enum fee: 
fee = standard trading fee + order_enum_fee
If you need the amount excluding the enum fee, calculate: 
standard trading fee = fee - order_enum_fee

​
Admin Operations

Admin endpoints require standard Orderly signed request headers and should only be called from secured builder admin tooling or backend services.
ActionAPI reference
Create enumPOST /v1/broker/order_enum
Update enumPUT /v1/broker/order_enum/{enum_id}
List enums with usage statsGET /v1/broker/order_enums
Get single enum with usage statsGET /v1/broker/order_enum/{enum_id}
Archive enumPOST /v1/broker/order_enum/archive
Unarchive enumPOST /v1/broker/order_enum/unarchive

​
Data Model Notes

FieldDescription
enum_idUnique uppercase enum ID, for example STRATEGY_DCA.
statusactive or archived.
default_fee_rateDefault fee rate applied when no symbol override exists.
pair_overridesOptional map of symbol to fee rate.
created_timeCreation timestamp in milliseconds.
updated_timeLast update timestamp in milliseconds.
Admin list responses include usage stats such as total_orders, total_volume, and total_fees_collected.

​
Implementation Notes

  • Treat enum_id as immutable. If the classification semantics change, create a new enum rather than reusing a misleading ID.
  • Use uppercase alphanumeric characters and underscores only, with a maximum enum_id length of 31 characters.
  • The full order_tag value must fit within 36 characters, including the enum: prefix.
  • Archived enums should not be used for new orders.
  • Do not expose admin endpoints, account credentials, or signing keys in the DEX frontend.
  • Cache public enum responses briefly to avoid rate limit pressure, but refresh when admin configuration changes need to be reflected quickly.
  • Fee configuration is evaluated at execution time, so updates can affect later fills of existing open orders.