Gdex Limit Orders

GDEX: Limit Orders

Create limit buy/sell orders that trigger when a token reaches your target price. Uses the same managed-custody encryption flow as spot trades (ABI-encoded → signed → AES-encrypted computedData).

Critical: Endpoint Structure

Limit orders use separate endpoints for buy vs sell (NOT a single create endpoint):

There is NO /v1/orders/create or /v1/orders/cancel endpoint.

When to Use

• Buy a token when its price drops to a target → limitBuy()
• Sell a token when its price rises (take-profit) or drops (stop-loss) → limitSell()
• Cancel an existing order → updateOrder({ isDelete: true })
• Update an order's price/amount → updateOrder()
• List all active orders → getLimitOrders()

Prerequisites

• @gdexsdk/gdex-skill installed
• Authenticated via loginWithApiKey() — see gdex-authentication
• Minimum order: config.chains[chainId].minLimitOrder (typically 0.01 native token)

Limit Buy — Buy Token When Price Drops

import { GdexSkill, GDEX_API_KEY_PRIMARY } from '@gdexsdk/gdex-skill';

const skill = new GdexSkill();
skill.loginWithApiKey(GDEX_API_KEY_PRIMARY);

const result = await skill.limitBuy({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId: '0x53D029a671bd1CF61a2fB1F4F6e4bD830BFBb2eD',  // control wallet
  sessionPrivateKey: '<session-private-key-hex>',
  chainId: 622112261,           // Solana
  tokenAddress: 'EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm', // WIF
  amount: '10000000',           // 0.01 SOL in lamports
  triggerPrice: '0.50',         // trigger when WIF price ≤ $0.50
  profitPercent: '50',          // take profit at 50% gain (optional)
  lossPercent: '25',            // stop loss at 25% loss (optional)
});

LimitBuyParams

ABI schema: ['string','string','string','uint256','uint256','string'] = [tokenAddress, amount, triggerPrice, profitPercent, lossPercent, nonce] Signature: limit_buy-{userId}-{data}

CRITICAL (Live-Tested): profitPercent and lossPercent MUST be ABI-encoded as uint256, NOT string. The backend decodes them as uint256 and validates 0-100 range. Using string type produces ABI byte-offsets (e.g. 192) that fail the range check with "lossPercent must be between 0 and 100". The SDK handles this correctly — only matters if encoding manually.

Limit Sell — Sell Token at Target Price

// Sell WIF when price reaches $999.99 (take-profit)
const result = await skill.limitSell({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId: '0x53D029a671bd1CF61a2fB1F4F6e4bD830BFBb2eD',
  sessionPrivateKey: '<session-private-key-hex>',
  chainId: 622112261,
  tokenAddress: 'EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm', // WIF
  amount: '100000',             // token amount in raw units
  triggerPrice: '999.99',       // trigger when WIF price reaches $999.99
});

LimitSellParams

ABI schema: ['string','string','string','string'] = [tokenAddress, amount, triggerPrice, nonce] Signature: limit_sell-{userId}-{data}

The backend auto-classifies as take-profit (trigger > current price) or stop-loss (trigger < current price).

Update or Delete an Order

// Delete an order
await skill.updateOrder({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId: '0x53D029a671bd1CF61a2fB1F4F6e4bD830BFBb2eD',
  sessionPrivateKey: '<session-private-key-hex>',
  chainId: 622112261,
  orderId: '64-char-hex-order-id',
  isDelete: true,
});

// Update an order's trigger price
await skill.updateOrder({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId: '0x53D029a671bd1CF61a2fB1F4F6e4bD830BFBb2eD',
  sessionPrivateKey: '<session-private-key-hex>',
  chainId: 622112261,
  orderId: '64-char-hex-order-id',
  triggerPrice: '1.50',
  amount: '10000000',
});

UpdateOrderParams

ABI schema: ['string','string','string','uint256','uint256','string','string'] = [orderId, amount, triggerPrice, profitPercent, lossPercent, nonce, isDelete] Signature: update_order-{userId}-{data}

CRITICAL: Same as limit_buy — profitPercent and lossPercent are uint256, not string.

List Orders

const { count, orders } = await skill.getLimitOrders({
  userId: '0x53D029a671bd1CF61a2fB1F4F6e4bD830BFBb2eD',
  data: encryptedSessionKey,  // from buildGdexUserSessionData()
  chainId: 622112261,
});

GetLimitOrdersParams

LimitOrder Object (response)

interface LimitOrder {
  orderId: string;           // unique 64-char hex ID
  fromToken: string;         // token being sold
  toToken: string;           // token being bought
  isBuyLimit: boolean;       // true = buy limit, false = sell limit
  price: number;             // trigger price in USD
  takeProfitPrice: number;   // TP price (0 = disabled)
  stopLossPrice: number;     // SL price (0 = disabled)
  fromTokenAmount: string;   // amount in raw units
  toTokenAmount: string;     // computed output amount
  walletAddress: string;     // managed wallet address
  userId: string;            // control wallet address
  chainId: number;           // numeric chain ID
  pairAddress: string;       // DEX pair address
  isActive: boolean;         // still pending?
  isCancelled?: boolean;     // was cancelled?
  expiredAt: number;         // expiry Unix timestamp
  profitPercent?: string;    // TP % (buy orders)
  lossPercent?: string;      // SL % (buy orders)
}

Order Fill Logic

Orders are filled by background processes that monitor prices via NATS:

• Buy limit: triggers when tokenPrice <= order.price
• Sell take-profit: triggers when tokenPrice >= takeProfitPrice
• Sell stop-loss: triggers when tokenPrice <= stopLossPrice

Error Codes

Legacy Aliases

For backward compatibility, older method names still work:

• createLimitOrder() → calls limitBuy()
• cancelLimitOrder() → calls updateOrder({ isDelete: true })

Autonomous Agent Notes (Live-Tested)

Verified Working Flow (Solana/WIF Example)

This exact sequence was tested end-to-end and succeeded:

// 1. List existing orders
const orders = await skill.getLimitOrders({ userId, data, chainId: 622112261 });

// 2. Create a limit buy order
const result = await skill.limitBuy({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId: controlAddress,          // MUST be control address, lowercase
  sessionPrivateKey,
  chainId: 622112261,              // Solana
  tokenAddress: 'EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm', // WIF
  amount: '1000000',               // ~0.001 SOL in lamports (raw units)
  triggerPrice: '0.0001',          // trigger when price drops to $0.0001
  profitPercent: '50',             // 50% take-profit
  lossPercent: '30',               // 30% stop-loss
});
// → { isSuccess: true, message: "Order created successfully", order: {...} }

// 3. Verify order appears in list
const updated = await skill.getLimitOrders({ userId, data, chainId: 622112261 });

// 4. Cancel the order
await skill.updateOrder({
  apiKey, userId, sessionPrivateKey,
  chainId: 622112261,
  orderId: result.order.orderId,
  isDelete: true,
});

Key Requirements for Limit Buy

• amount must be in raw units (lamports for Solana, wei for EVM) — NOT float
• profitPercent and lossPercent are mandatory for limit_buy (both must be > 0)
• profitPercent and lossPercent must be valid 0-100 range (ABI-encoded as uint256)
• userId must be the control wallet address, lowercase
• triggerPrice is in USD (string)

Minimum Order Size

The backend enforces config.chains[chainId].minLimitOrder per chain. For Solana, this is approximately 0.001 SOL (1000000 lamports). Going below returns "Insufficient balance".

Order Cancellation

To cancel, use updateOrder({ isDelete: true }). There is no separate cancel endpoint. The cancelLimitOrder() alias calls this internally.

Error Messages and What They Mean

Related Skills

• gdex-authentication — Auth setup required before creating orders
• gdex-spot-trading — Market orders (immediate execution) instead of limits
• gdex-portfolio — Track order fills in trade history