Skip to main content
Order tags let builders apply custom trading fees per order by assigning an order_tag such as enum:STRATEGY_DCA during order placement. The order tag value can be either a plain referral code or enum:<enum_id>. The enum_id is the fee config identifier; to apply custom trading fee per order, the order tag sent on an order must include the enum: prefix. 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 tags

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

Expose active order tags to your DEX

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

Apply the order tag during order placement

Set order_tag to enum:<enum_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 order tag lifecycle

Update fee rates, archive inactive order tags, unarchive order tags 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 tag fee configs for a builder. The public list endpoint is unauthenticated and takes broker_id as a query parameter:
Optional filters include symbol, enum_id, and include_archived.

​
Fee Disclosure

When order_tag uses the enum:<enum_id> format, the matching order tag fee config applies an additional custom trading fee on top of the standard fee schedule. The enum: prefix is required for custom trading fee per order. This is different from a plain referral-code order_tag, which is treated as referral attribution and does not apply the custom trading fee per order. The order tag fee is charged in addition to the user’s existing trading fee:
default_fee_rate is the fallback fee rate for the order tag. pair_overrides lets builders override that fallback for specific symbols, so one order tag can charge different additional fee rates by market. If pair_overrides includes the order symbol, use that symbol-specific order tag fee rate. Otherwise, use default_fee_rate. Display the order tag fee separately from the standard trading fee so users understand both components before placing an order.

​
Applying Order Tags to Orders

Set order_tag on supported order creation APIs: order_tag supports two formats: Custom trading fee order tags must use this format:
order_tag is immutable after order placement. To change the tag 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: Use trade APIs for fee reporting and reconciliation: On trade records, fee includes both the standard trading fee and the order tag fee:
If you need the amount excluding the order tag fee, calculate:

​
Admin Operations

Admin endpoints require standard Orderly signed request headers and should only be called from secured builder admin tooling or backend services.

​
Data Model Notes

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 fee config 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 required enum: prefix.
  • Archived order tags should not be used for new orders.
  • Do not expose admin endpoints, account credentials, or signing keys in the DEX frontend.
  • Cache public order tag 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.