GDEX Trading

Cancel an open order directly with a private key on HyperLiquid.

Get a cross-chain bridge quote without executing. Returns estimated output, provider, and time.

Execute a cross-chain bridge transaction. Requires managed-custody auth.

Execute a cross-margin perpetual trade directly with a private key (no managed custody). Supports TP/SL and builder fees.

Execute an isolated-margin perpetual trade directly with a private key. Requires explicit leverage.

Execute a spot trade directly on HyperLiquid with a private key.

Explain an end-to-end GDEX trading workflow with step-by-step instructions and code.

List accounts connected on this machine (accountRef, control wallet, managed wallets, session age). No secrets are returned.

Connect a GDEX trading account without putting any secret in the conversation. Signs in from a control-wallet key file on this machine (keyFile), or creates a new local wallet (create: true), or refreshes an existing accountRef. Returns an accountRef plus public addresses; pass accountRef to any trading tool instead of sessionPrivateKey/privateKey. Never ask the user to paste a private key or seed phrase.

Forget a connected account on this machine (deletes its stored keys). Funds are not affected; reconnect later with gdex_connect and the key file.

Execute a preview within the user's authority: userApproved=true only after the user approved THIS preview's terms; otherwise the account's delegated policy must allow it (else status denied). Re-quotes first: moved or expired terms return status revised with a new preview instead of trading. Returns an operation; follow it with gdex_operation. Never call again for the same intent after submission_unknown.

Preview an exit for an existing position, against its live state: close/reduce a perp (reduce-only, correct side for longs and shorts) or sell a spot token back to USDC. Returns a preview; execute it with gdex_execute_trade.

Follow or recover an operation by opId: waits for funding/fill (spot streams funding steps; perps check the live position), resolves submission_unknown by looking for the trade instead of resending, and reports needs_retry when the backend offers an in-place sell retry (usdc_retry_sell). Without opId, lists recent operations.

What the account owns and has pending: unified USDC + gas balances per chain, Hyperliquid positions on every DEX, open orders, and unfinished operations. Each section says ok or unavailable; unavailable means unknown, not empty.

Turn an explicit trade intent into exact executable terms without trading: market, side, human and raw amounts, quote source and time, minimum received or limit price, funding plan, expiry (60s). Returns a previewId for gdex_execute_trade. kind=spot (USDC wallet), perp_open, perp_close. For perps give notionalUsd (position size) or marginUsd (collateral), never guess which.

Start here. Reports version, connected accounts (no secrets), API reachability, delegated trading policy per account, pending operations, supported trade kinds, and the next setup step.

Generate a new EVM wallet offline (no network call). To trade with it, use gdex_connect { create: true } instead, which stores it locally. Returns only the address unless revealSecrets is true.

Trigger backend PnL generation for a wallet.

Advanced/manual signing only: generate a secp256k1 session keypair. Prefer gdex_connect, which signs in and keeps keys on this machine. Returns only the public sessionKey unless revealPrivateKey is true.

Get full HyperLiquid account state: positions, margin, balance, withdrawable amount. No auth required.

Get all current mid prices across all HyperLiquid assets. No auth required.

Get GDEX API endpoint details — URL, method, parameters, and response format.

Token balances of the managed GDEX wallet on one chain, optionally one token. [] means the backend reported no holdings; a failed read errors. Native balance: get_trading_funds.

"Big buy" alert feed for a chain — recent large buy transactions.

Get bridge order history for a user. Requires session-key auth.

Get supported chains, chain IDs, DEXes, and capabilities.

Get comments for a token.

Get React UI component patterns for GDEX trading interfaces.

Get top 300 wallets ranked by net received. No auth. Cached 2 min.

List supported DEXes for a chain (e.g. Raydium, Pumpfun on Solana). No auth.

Get hot new tokens heavily traded by top wallets. No auth. Cached 20s.

Get a copy trading guide for Solana spot or HyperLiquid perp copy trading.

List all copy trade configurations for a user. Requires session-key auth.

List copy trade transaction history with PnL. Requires session-key auth.

Get top 300 wallets ranked by totalPnl for Solana spot copy trade leaderboard. No auth. Cached 2 min.

Currently-livestreaming token launches.

Get all tradeable assets on HyperLiquid with max leverage info. No auth.

Get account state (positions, margin) on a HyperLiquid DEX. No auth. Builder/HIP-3 positions (e.g. xyz:NVDA) live under their own dex — pass `dex` ("xyz") to see them. The default query does NOT show builder positions; an open builder position will look empty without `dex`.

List all HL perp copy trade configurations for a user. Requires session-key auth.

Get HL copy trade fill history. Supports pagination (max 100 per page). Session-key auth. Cached 15s.

Get supported deposit tokens for HyperLiquid. No auth.

Get market metadata and asset contexts from HyperLiquid. No auth.

Get all open orders on HyperLiquid for a wallet. No auth required.

Get 24h notional volume per outcome side coin from the Hyperliquid WS feed. Pass coins from hl_outcomes sides[].coin, e.g. ["#143150","#143151"]. Returns { coin: volume } for coins that reported; a missing coin means no reading (not zero). Prefer hl_outcomes withVolume=true, which reports coverage per market.

Get available perpetual DEX list on HyperLiquid. No auth.

Get HyperLiquid spot trading state for a wallet. No auth required.

Get top HyperLiquid perp traders by volume, trade count, or deposit. No auth. Cached 15 min.

Get top 30 HyperLiquid perp traders ranked by PnL. Data by day/week/month. No auth. Cached 15 min.

Get trade history on HyperLiquid for a wallet. No auth required.

Get detailed trading stats for an HL user: daily PnL, volumes, trade counts, win rates. No auth. Cached 1 hr.

List active limit orders for a user on a specific chain. Requires session-key auth.

Livestream status for a single token address.

Get the current mark price for a HyperLiquid asset. No auth required.

Get current native token prices (ETH, SOL, SUI, BNB, ...) keyed by chain.

Get newest tokens across all chains (or a specific chain).

Get NoF1 advanced trader analytics for a wallet.

Get OHLCV candlestick data for a token. No auth.

Get all open perpetual positions for a wallet on HyperLiquid. No auth required.

Token holdings of the managed GDEX wallet on one chain (/v1/portfolio): exact raw and decimal balances, price, native value and P&L per token. Needs the session (accountRef). Errors instead of returning an empty portfolio when the read fails.

List registered retailer integrations / branded onboarding partners.

Get TypeScript code patterns for common GDEX SDK operations. Returns working code examples.

Read a file that ships with a GDEX skill (e.g. gdex-token-risk scripts/token_risk.py). Omit path to list the skill's files.

Get detailed token info: price, market cap, liquidity, DEX pools, social links, security info. No auth.

Get server-rendered token social-card image metadata.

Recent trades for a specific token.

Get top tokens by volume / market cap.

Get top performing trader wallets ranked by P&L, win rate, volume, or trade count.

Successful spot trades of a GDEX account on one chain, newest first (/v1/user_history, keyed by the control wallet). Page with limit (max 50) and cursor = nextCursor of the previous page.

Get the active leverage setting a trader uses for a specific coin on HyperLiquid.

Native balance the managed GDEX wallet can trade with on one chain (/v1/user), plus the managed wallet address per chain family. The value is approximate (backend float). Cross-chain USDC: usdc_get_balances.

Get a complete trading guide for spot, perp, or limit order trading.

Get trending tokens sorted by volume and price change. No auth.

Get USDC balance on HyperLiquid for a wallet. No auth required.

Summary of the managed GDEX wallet on one chain: managed address, native balance (approximate, /v1/user), token count and USD total (/v1/portfolio). Needs the session (accountRef); there is no address-only read.

Get wallet performance / PnL summary across recent periods.

Fetch the user's watchlist.

List tokenised equities (xStocks).

List Zora-protocol tokens.

Get builder-referral metadata for a wallet.

Cancel a resting HIP-4 outcome order. Structured mode: apiKey, walletAddress (control), sessionPrivateKey, outcomeId, coin (must belong to outcomeId), orderId (numeric Hyperliquid oid from hl_create_outcome_order or hl_outcome_account openOrders). Partial fills before the cancel stay in the position. Pre-built mode: computedData alone.

Exit a HIP-4 outcome position by SELLING held side tokens (the backend always sells; it cannot short). Structured mode: apiKey, walletAddress (control), sessionPrivateKey, outcomeId, one of coin/sideIndex/sideLabel, price (limit) or isMarket=true, optional size (whole contracts; omit for a full exit — the backend caps size to what you hold). With managedAddress, partial exits must leave both the sold part and the remainder >= 11 quote. Settled markets have no book: GDEX has no claim endpoint, check the HL spot balance instead. Pre-built mode: computedData alone.

Place an order on a Hyperliquid HIP-4 outcome market. Structured mode (apiKey, walletAddress=control address, sessionPrivateKey, outcomeId, one of coin/sideIndex/sideLabel, isBuy, size, and price unless isMarket) is validated against the live market first: side must belong to outcomeId, size is whole contracts, price in [0.00001, 0.99999] with max 5 decimals, size×price >= 11 quote (a full-position sell is exempt when managedAddress is given), market must not be expired/settled. isBuy=false sells side tokens you hold. reduceOnly is ignored by the backend. Returns status resting (with orderId) …

Enable HL trading for a managed wallet (one-time, required before outcome/HIP-3 orders). Pass apiKey, walletAddress (control address), sessionPrivateKey and the SDK builds the payload; a pre-built computedData is also accepted.

Per-user realised PnL from HL copy-trading.

Normalised state of a MANAGED wallet on one HIP-4 outcome market: positions (per side: size, hold, available, avgEntryPrice, markPrice, value, unrealizedPnl), openOrders (resting / partially_filled with orderId, price, size, filledSize), fills, historicalOrders (Hyperliquid status). Use it to reconcile after create/cancel/close. raw=true returns the backend payload.

Check the managed wallet's Hyperliquid SPOT balance of a market's quoteToken (outcome buys draw on spot collateral, not the perp account) against size × price.

Discover Hyperliquid HIP-4 outcome markets (GDEX has no Polymarket/Kalshi). Returns normalised markets: outcomeId, title, sides[] (label, coin "#<assetId>", balanceCoin "+<assetId>", price = current mid), quoteToken (collateral, held in the HL spot balance), state (active | pre_launch | expired | settled), rules (price 0.00001-0.99999 tick 0.00001, whole-contract size, min order notional 11 quote), settlement (no claim via GDEX). withVolume=true adds volume24h {volume, asOf, source, coverage} with a bounded wait. raw=true returns the backend payload unchanged.

Submit a claim request for accrued HL referral rewards. Requires pre-built computedData.

Get HyperLiquid referral info (earned, eligibility, code).

Swap collateral between HL clearinghouses/perp DEXes (HIP-3). Pass apiKey, walletAddress, sessionPrivateKey, fromToken, toToken, amount or a pre-built computedData.

Get HL transaction list (fills / orders) for a wallet.

Import a user-defined custom token into the platform via managed custody. Requires pre-built encrypted computedData.

Create a limit buy order — buy a token when price drops to target. Uses ABI-encoded + AES-encrypted computedData.

Create a limit sell order — sell a token when price reaches target. Auto-classifies as TP or SL.

Submit an encrypted managed-custody buy trade via the GDEX backend.

Submit an encrypted managed-custody sell trade via the GDEX backend.

Sign in to GDEX managed-custody system using encrypted computedData payload.

Poll the status of a managed-custody trade by requestId.

Log in or sign up using a Google ID token. Google OIDC only — there is no Apple/GitHub branch. If the wallet has no associated email yet, the backend returns 404 with internal code 108 and the caller must invoke associate_email first (using the same idToken) before retrying.

Open a perpetual futures position on HyperLiquid with leverage, TP/SL. Supports market and limit orders.

Pause a Solana copy trade (isActive=false) WITHOUT deleting it. Reads the current state first and is a no-op if already paused. While paused the copier mirrors neither buys nor sells; positions it opened stay open and their TP/SL orders stay in place. Errors: PAUSE_STATE_UNVERIFIED (state could not be confirmed, nothing sent), PAUSE_UNSUPPORTED (stored config invalid; explains the alternative), COPY_TRADE_NOT_FOUND.

Pause an HL perp copy trade (isActive=false) WITHOUT deleting it. Reads the current state first and is a no-op if already paused. While paused the copier mirrors neither opens nor closes, so copied positions stay open and will NOT follow the trader's exits; their TP/SL orders stay in place. Errors: PAUSE_STATE_UNVERIFIED (nothing sent), PAUSE_UNSUPPORTED (stored config invalid; explains the alternative), COPY_TRADE_NOT_FOUND.

Deposit USDC into the HyperLiquid perpetual account from Arbitrum.

Withdraw USDC from the HyperLiquid perpetual account.

Place a simple perp order on HyperLiquid without TP/SL. isMarket=true (default) is sent via /hl/create_order as a market order; isMarket=false sends a limit order at `price` via /hl/place_order, which the backend currently accepts only with reduceOnly=true.

Resume a paused Solana copy trade (isActive=true). No-op if already active. Trades made while paused are not replayed.

Resume a paused HL perp copy trade (isActive=true). No-op if already active. Fills made while paused are not replayed.

Search GDEX documentation and skill files by keyword. Returns matching skill sections.

Sell a token for the chain's native token from the managed GDEX wallet (session-signed sell_v2). Amount is a token amount ('100') or a percentage of the held balance ('50%', '100%'), resolved from the managed holdings. Returns a requestId; follow it with wait_for_trade. To receive USDC use usdc_sell.

Set leverage for a specific asset on HyperLiquid. Known broken: /hl/update_leverage has returned 404 in live tests. Pass `leverage` on open_perp_position instead (sent with the order).

Transfer native asset (ETH, SOL, SUI, BNB, ...) via managed custody. Requires pre-built encrypted computedData.

Transfer ERC20 / SPL token via managed custody. Requires pre-built encrypted computedData.

Check trending-slot booking status (pending payment, active, expired).

List currently promoted / booked trending tokens.

List available trending-slot packages and prices.

Register / pay for a trending slot.

Low-level Solana copy trade update (prefer update_copy_trade_settings / pause_copy_trade / resume_copy_trade / delete_copy_trade). Every field is rewritten from this payload, so pass the full current config. isDelete=true permanently deletes the configuration; positions it opened are NOT sold and their TP/SL limit orders are NOT cancelled. isChangeStatus=true TOGGLES active/paused relative to the stored state (sending it twice resumes). isDelete and isChangeStatus cannot both be true.

Change settings of an existing Solana copy trade. Never deletes and never pauses/resumes. Reads the current config first; omitted fields keep their current values. Open positions are not resized.

Low-level HL perp copy trade update (prefer update_hl_copy_trade_settings / pause_hl_copy_trade / resume_hl_copy_trade / delete_hl_copy_trade). Every field is rewritten from this payload, so pass the full current config. isDelete=true permanently deletes the configuration; perp positions it opened are NOT closed and their TP/SL orders are NOT cancelled. isChangeStatus=true TOGGLES active/paused relative to the stored state. isDelete and isChangeStatus cannot both be true.

Change settings of an existing HL perp copy trade. Never deletes and never pauses/resumes. Reads the current config first; omitted fields keep their current values. Configs created by SDK <= 4.12 may hold an invalid copyMode (e.g. 416/480) and oppositeCopy=true; pass copyMode, fixedAmountCostPerOrder and oppositeCopy explicitly to repair them.

Update or delete an existing limit order. Set isDelete=true to cancel (no other fields needed). An update replaces amount, triggerPrice and TP/SL together, so all four are required.

Buy a token paying with USDC. Automatic funding is on by default: GDEX bridges USDC and tops up gas from the user's other chains when this chain is short, capped by the signed maxSourceSpendRaw. A pending result returns a requestId: follow it with usdc_wait_for_trade.

Buy a token paying with the chain's native token (ETH, BNB, SOL...). Auto-bridge from other chains is on by default, as on gdex.pro.

Convert the chain's native gas token to USDC, keeping a per-chain gas reserve. Get amounts from usdc_get_convert_quote.

Quote moving USDC between chains (Relay). amountRaw is what arrives on the destination. The response fromAmountRaw is the source spend to cap usdc_execute_bridge with.

Move USDC between chains. maxFromAmountRaw is the signed maximum source spend: use the estimate's fromAmountRaw plus a small headroom. Poll usdc_get_bridge_status with the returned id.

Unified USDC wallet: the user's USDC and native gas balance on every supported chain, plus the cross-chain USDC total.

The user's USDC bridge history.

Status of a USDC bridge by id. refresh=true polls the bridge provider once.

Quote converting the chain's native gas token to USDC, keeping a gas reserve. amount is raw native or "max".

Status and funding steps of a deferred (auto-bridged) USDC trade, by tradeId.

Status of a USDC trade or its auto-funding (bridge legs, confirmation, failure reason). Poll with the requestId a trade returned. If it returns a retry capability for a stuck sell, use usdc_retry_sell.

Pending USDC trades on a chain. Check before resubmitting any trade whose outcome is unknown; never resubmit while one is pending.

Executable quote for a USDC- or native-paid buy, or a sell to USDC. Returns amountOutRaw; apply slippage to get the minimum out for usdc_buy / usdc_sell.

Retry a stuck USDC sell in place, reusing its transaction nonce so it cannot execute twice. Use when usdc_wait_for_trade returns needs_retry (or funding status shows retry.available). Token, amount, chain and nonce are read from the backend's retry capability; re-quote the sell for minUsdcOutRaw.

Sell a token and receive USDC into the unified USDC wallet. Settles on its own chain (no auto-funding, as on gdex.pro).

Follow a pending USDC trade (requestId from usdc_buy, usdc_buy_with_native or usdc_sell) to its result, like gdex.pro's live progress note: polls every 3s and returns each step as it happened (bridge legs, gas top-up, approve, swap), the outcome and the tx hash. outcome "needs_retry" means a sell broadcast was dropped and can be retried in place with usdc_retry_sell; "pending" after the timeout means still settling: never resubmit.

Cast a bullish/bearish sentiment vote on a token.

Follow a buy_token / sell_token requestId to its result by polling /v1/trade-status. outcome: filled, failed, not_found (expired id) or pending (still running at the timeout: never resubmit).