Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orderly.network/docs/llms.txt

Use this file to discover all available pages before exploring further.

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: 
GET /v1/public/broker/order_enums?broker_id={broker_id}
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: 
final fee = trading fee + order tag 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:
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 order tag fee config.
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 tag fee configenum:STRATEGY_DCAApplies an additional custom trading fee on top of the standard fee schedule and preserves referral.
Custom trading fee order tags must use this format: 
enum:<enum_id>
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:
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 order tag fee fields.
GET /v1/algo/order/{order_id}/tradesReturns algo order trades with order tag fee fields.
On trade records, fee includes both the standard trading fee and the order tag fee: 
fee = standard trading fee + order_enum_fee
If you need the amount excluding the order tag 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 order tagPOST /v1/broker/order_enum
Update order tagPUT /v1/broker/order_enum/{enum_id}
List order tags with usage statsGET /v1/broker/order_enums
Get single order tag with usage statsGET /v1/broker/order_enum/{enum_id}
Archive order tagPOST /v1/broker/order_enum/archive
Unarchive order tagPOST /v1/broker/order_enum/unarchive

​
Data Model Notes

FieldDescription
enum_idUnique uppercase fee config ID, for example STRATEGY_DCA. The order tag value must be enum:<enum_id>, for example enum: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 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.