Delegated trading integration

This page explains how to build delegated trading flows on GMX V2 using the subaccount and relay surfaces documented in Advanced entry points. It is intended for integrators who need an end-to-end implementation pattern, not just a function reference.

Use this guide when your application needs a model like:

• an account owner retains primary control of funds
• a delegated trader can place, update, and cancel orders
• delegated access expires automatically or is limited by action count
• your backend, relayer, or UI coordinates the signing flow

If you only need the raw contract surfaces, start with Advanced entry points. If you need read-path architecture and freshness guidance, also see the API integration guide and Reader.

What GMX exposes

The delegated trading surface is built around:

• SubaccountGelatoRelayRouter for same-chain delegated order management (gasless, relay-based)
• MultichainSubaccountRouter for cross-chain delegated order management
• DataStore and Keys for delegated-access state such as expiry, action count, and integration id

A legacy SubaccountRouter contract is still deployed but is no longer used for order operations. The current GMX interface only calls it for wallet-based removeSubaccount(...) when the user is not going through the express flow. For new integrations, use SubaccountGelatoRelayRouter for same-chain delegated order execution and MultichainSubaccountRouter for cross-chain delegated order execution.

At the contract level, the main account can authorize or remove a subaccount, set an expiry timestamp for delegated actions, cap how many delegated actions may be performed, and bind a subaccount to an integration id. The delegated subaccount can then create, update, and cancel orders through the delegated trading surface.

Permission model

The GMX subaccount model is scoped to delegated trading, not broad account delegation. Delegated access is designed for order management — it is narrower than giving a third party full account ownership, and it does not turn the delegated signer into a general-purpose owner of the account.

Boundaries

Area	Behavior
Order outputs	Constrained to the main account
Collateral and WNT	The delegated flow can spend the main account's collateral and WNT within the supported order flow
Deposits, withdrawals, shifts, claims	Not delegated — these use their own routers and flows

For a summary of integration caveats, also review Known issues.

Roles in a delegated trading flow

Most integrations end up with three roles:

1. Main account owner

The owner wallet is the trust anchor for the trading account. It decides which delegated signer is allowed to trade, sets expiry and action-count limits, revokes delegated access, and optionally binds the subaccount to an integrationId.

2. Delegated trader or subaccount signer

This signer executes delegated trading actions within the limits the owner authorized. Depending on your design, it may be a key generated and stored locally in the user's browser for one-click trading, a key generated and managed by your backend or trading service, or a wallet controlled directly by a trader operating under your system's authorization flow.

3. Backend or relayer

Your backend may orchestrate owner-authorization flows, store or broker delegated session metadata, relay gasless order flow through SubaccountGelatoRelayRouter, and monitor expiry, action count, order lifecycle, and risk state.

Common integration patterns

GMX supports multiple delegated trading patterns. The right one depends on your custody and trust model.

Browser-local one-click signer

This is the closest match to the GMX interface's one-click trading flow described in Trading overview. The delegated signer is created client-side, the key stays in the browser or local device storage, the owner authorizes delegated access with expiry and action limits, and the UI uses the delegated signer for order flow. This is the lowest-backend-custody model, but it shifts key-security risk to the browser environment.

Backend-managed delegated signer

This pattern is useful when your product already operates managed trading infrastructure. Your backend provisions and manages the delegated signer, the owner authorizes that signer as a subaccount, and your backend handles session lifecycle, revocation, and monitoring. This gives you more operational control, but the delegated signer becomes part of your key-management perimeter — treat it as a hot operational key with strict lifecycle controls.

Relay-first owner approval flow

This pattern is useful when you want owner-controlled authorization, delegated trading without repeated wallet popups, and gasless or sponsored execution. The owner signs the subaccount approval payload, the delegated signer signs the trade payload, and your relayer or backend submits through SubaccountGelatoRelayRouter. This is the most natural path when you want tight control over expiry, nonce handling, and replay protection while still delivering a low-friction user experience.

Recommended end-to-end flow

The most common delegated trading sequence looks like this:

Step 1 — Choose the delegated signer model

Decide whether the delegated signer will be browser-local, backend-managed, or externally controlled by the delegated trader.

Step 2 — Create or identify the delegated signer

This signer becomes the subaccount address that the main account owner authorizes.

Step 3 — Owner authorizes delegated trading

The owner enables delegated trading by setting the subaccount address, the delegated action type, expiry, maximum allowed action count, and an optional integration id.

Step 4 — Store delegated session metadata

Your application should track:

State	Notes
Subaccount address	The delegated signer's address
Authorization status	Whether the subaccount is currently active
Expiry	When delegated access expires
Remaining action budget	How many actions remain before re-authorization
Nonce state	Required if you are using relay-based approvals
Integration id	If you use one

Step 5 — Execute delegated orders

Use SubaccountGelatoRelayRouter for same-chain delegated order execution or MultichainSubaccountRouter for cross-chain delegated order execution.

Step 6 — Monitor and refresh

Your system should detect expiry approaching, action count approaching the cap, nonce invalidation, and revoked delegated access.

Step 7 — Re-authorize or revoke

When the delegated session is no longer valid, the owner can refresh authorization with a new expiry or action budget, or remove the subaccount entirely.

Router selection

Use SubaccountGelatoRelayRouter for same-chain delegated trading. This is the primary delegated order path used by the current GMX interface — it supports gasless delegated order creation, updates, cancellation, and subaccount removal, with owner-signed approval payloads and delegated trade payloads in one relay flow. Use MultichainSubaccountRouter for cross-chain delegated trading flows.

A legacy SubaccountRouter contract remains deployed on all networks but is no longer used for order operations. The GMX interface only calls it for wallet-based subaccount removal outside the express flow.

SDK, API, and contract responsibilities

GMX does not currently package delegated trading as a single turnkey integration surface. In practice, delegated trading integrations compose three layers:

Layer	Role	Notes
Contracts	Source of truth for delegated authorization, order execution, and expiry/action-count/integration-id enforcement	Always the canonical state
SDK	Typed read helpers, order-building convenience, and wallet-client integration	Useful in delegated flows, but you own the overall authorization and session architecture
API	Near-live positions and orders over HTTP, lighter-weight read integration, and separation between read polling and write submission	See API integration guide for freshness and consistency expectations

Monitoring architecture

If delegated trading is part of a risk-managed product, design the monitoring layer intentionally rather than treating every read surface as interchangeable.

Surface	Best for	Latency	Examples
Reader, DataStore, Multicall3	Tight on-chain state loops	Lowest — same-block	Subaccount expiry, action-count consumption, delegated access status, position state for risk controls
API and SDK reads	Application state and account views	Near-live	Dashboards, trader-facing views, normal order monitoring, eventual-consistency workflows after writes
GraphQL and indexed surfaces	History and analytics	Higher	Investigations, reporting, trade history

tip

Treat API and SDK reads as near-live, not as a strict same-block risk engine. Do not rely only on indexed or historical surfaces for latency-sensitive delegated trading controls.

See Overview for the read contracts and Reader for position and order helpers.

Security guidance

Delegated trading is a security-sensitive integration. Keep these constraints in mind:

Limit scope aggressively

Always use the protocol's built-in controls — expiry, maximum allowed action count, and optional integration id. Do not treat delegated access as open-ended if your use case does not require it.

Be explicit about key custody

If you use a browser-local signer, the browser becomes part of the trust boundary — compromised local storage or injected scripts can compromise the delegated signer. If you use a backend-managed signer, your backend becomes part of the custody boundary, and you should treat the delegated signer as a hot key with planned revocation, rotation, and auditability.

Avoid unnecessary private-key transport

If your integration can avoid transporting raw delegated private keys between backend and browser, that is generally the safer design. Prefer architectures where the delegated signer is generated client-side, or the backend signs on behalf of the delegated session without exposing raw key material to the browser.

Separate read architecture from write architecture

Do not tie delegated trade submission and risk monitoring to the same fragile polling path. In production integrations, treat authorization and write flow, state polling, and risk enforcement as separate responsibilities, even if they are implemented by the same service.

What GMX provides vs what your integration must provide

GMX provides	Your integration provides
Delegated trading primitives	Signer custody design
Gasless relay primitives	User authorization UX
Owner-controlled expiry and action limits	Session lifecycle management
Read contracts and APIs for account state	Monitoring and risk architecture
Protocol-level enforcement, not custody	Key-security controls appropriate for your trust model

Next steps

• Advanced entry points for the raw delegated trading surfaces
• Reader for position and order reads
• Overview for read contracts and multicall guidance
• Trading overview for the user-facing one-click trading model
• SDK v1 integration guide for SDK operational notes
• API integration guide for freshness, consistency, and read-surface guidance